API reference
Sending controls
Kill switches, their audit trail and the workspace's test people.
Kill switches, their audit trail and the workspace's test people.
POST /v1/scopes/{id}/pause#
Pause a store's sending (workspace keys only); reads go on; audited with reason and actor
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
reason required | string | min 1, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scopes/user-42/pause" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/pause`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"scopeId": "<scopeId>",
"stored": true,
"planCode": "<planCode>",
"tier": "free",
"trustTier": "red",
"rampStep": 1,
"reachCap": 1,
"effectiveReachCap": 1,
"fullReachCap": 1,
"quotas": {},
"monthlyQuota": {
"push": 1,
"email": 1,
"inapp": 1
},
"dailyMax": 1,
"effectiveDailyMax": 1,
"campaignsPerWeek": 1,
"allowedChannels": [
"push"
],
"frequencyCap": {},
"segmentCooldownHours": 1,
"contactAccess": "masked",
"status": "<status>",
"paused": true,
"pausedReason": "<pausedReason>",
"pausedAt": "<pausedAt>",
"updatedAt": "<updatedAt>",
"pausedBy": "<pausedBy>",
"updatedBy": "<updatedBy>"
}POST /v1/scopes/{id}/resume#
Resume a paused store (workspace keys only); audited
A store paused automatically for its health (P1-11) is resumed only by an operator session (a workspace key is 403 operator_required) with a reason of 3 characters or more (400 otherwise); the reason ends its automatic pause and is shown to the seller.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
reason | string | max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scopes/user-42/resume" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/resume`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"scopeId": "<scopeId>",
"stored": true,
"planCode": "<planCode>",
"tier": "free",
"trustTier": "red",
"rampStep": 1,
"reachCap": 1,
"effectiveReachCap": 1,
"fullReachCap": 1,
"quotas": {},
"monthlyQuota": {
"push": 1,
"email": 1,
"inapp": 1
},
"dailyMax": 1,
"effectiveDailyMax": 1,
"campaignsPerWeek": 1,
"allowedChannels": [
"push"
],
"frequencyCap": {},
"segmentCooldownHours": 1,
"contactAccess": "masked",
"status": "<status>",
"paused": true,
"pausedReason": "<pausedReason>",
"pausedAt": "<pausedAt>",
"updatedAt": "<updatedAt>",
"pausedBy": "<pausedBy>",
"updatedBy": "<updatedBy>"
}GET /v1/setup/test-people#
The workspace's test people, with their names
External ids (at most 100), each with the live profile that has it and the person's name, or nulls (not known yet). key says where the list lives: recipient_allowlist in a development workspace (nobody else receives anything from it), test_people in production (who tests reach; it never limits real sends). gate: a production workspace's go-live allowlist while it is still set. Audited as a list of people.
curl -X GET "$SAPAGAN_URL/v1/setup/test-people" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/setup/test-people`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"env": "production",
"key": "recipient_allowlist",
"people": [
{
"externalId": "user-42",
"profileId": "user-42",
"name": "order_placed",
"unsubscribed": true
}
],
"gate": [
"<gate>"
]
}GET /v1/workspace/policy-audit#
The workspace's own policy history: kill switch and policy defaults changes, newest first (workspace keys only)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/workspace/policy-audit" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/policy-audit`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"entries": [
{
"id": "user-42",
"action": "<action>",
"actor": "<actor>",
"reason": "Checked with the owner",
"before": null,
"after": null,
"occurredAt": "<occurredAt>"
}
]
}GET /v1/workspace/sending#
The workspace's global kill switch (workspace keys only)
curl -X GET "$SAPAGAN_URL/v1/workspace/sending" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/sending`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"sendingEnabled": true,
"env": "<env>"
}PUT /v1/workspace/sending#
Turn all sending in the workspace on or off (workspace keys only); always with a reason; audited
An operator session must also send confirm, the workspace's slug typed by the operator (P1-13); without it the answer is 400 confirmation_required.
Request body
| Field | Type | Notes |
|---|---|---|
enabled required | boolean | |
reason required | string | min 1, max 2000 |
confirm | string | max 100 |
curl -X PUT "$SAPAGAN_URL/v1/workspace/sending" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/sending`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"enabled": true,
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"sendingEnabled": true,
"env": "<env>",
"changed": true
}