API reference
Broadcasts
One-off campaigns: write, submit for approval, schedule, test and read results.
One-off campaigns: write, submit for approval, schedule, test and read results.
GET /v1/broadcasts#
List broadcasts
A workspace key lists every broadcast (filter with scopeId, or none for the workspace's own); a store's credential lists its own store's only. Newest first.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
scopeId | query | string (uuid) or "none" | |
status | query | "draft" | "submitted" | "ai_flagged" | "approved" | "rejected" | "scheduled" | "sending" | "sent" | "failed" | "cancelled" | |
after | query | string (uuid) | |
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/broadcasts" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"broadcasts": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"channel": "<channel>",
"templateId": "<templateId>",
"content": null,
"audience": null,
"status": "draft",
"statusReason": "<statusReason>",
"requiresApproval": true,
"marketing": true,
"approvedAt": "<approvedAt>",
"contentUpdatedAt": "<contentUpdatedAt>",
"contentVersion": 1,
"scheduledFor": "<scheduledFor>",
"sendAtRequested": "<sendAtRequested>",
"recipientCount": 1,
"goal": null,
"createdVia": "<createdVia>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"approvedBy": "<approvedBy>",
"createdBy": "<createdBy>",
"recipientHash": "<recipientHash>"
}
],
"next": "<next>"
}POST /v1/broadcasts#
Create a broadcast (draft)
Content is copied from templateId or given inline, and validated. A store's credential creates for its own store only (another store is 404), with a store audience only; it is always reviewed and marketing. sendAt inside quiet hours moves to the window's end (scheduleShiftedTo). P3-14a: a workspace's email is a draft that may be half-built: only its shape, size, rich text and HTML subsets and the HTML owner rule are checked here; contentIssues lists what the full checks found, and submit enforces them.
Request body
| Field | Type | Notes |
|---|---|---|
scopeId | string (uuid) or null | |
name required | string | min 1, max 200 |
channel required | "push" | "email" | "inapp" | |
templateId | string (uuid) | |
content | any | |
audience | any | |
sendAt | string (date-time) or null | |
requiresApproval | boolean | |
marketing | boolean | |
goal | object or null |
curl -X POST "$SAPAGAN_URL/v1/broadcasts" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed",
"channel": "push"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed",
"channel": "push"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"channel": "<channel>",
"templateId": "<templateId>",
"content": null,
"audience": null,
"status": "draft",
"statusReason": "<statusReason>",
"requiresApproval": true,
"marketing": true,
"approvedAt": "<approvedAt>",
"contentUpdatedAt": "<contentUpdatedAt>",
"contentVersion": 1,
"scheduledFor": "<scheduledFor>",
"sendAtRequested": "<sendAtRequested>",
"recipientCount": 1,
"goal": null,
"createdVia": "<createdVia>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"approvedBy": "<approvedBy>",
"createdBy": "<createdBy>",
"recipientHash": "<recipientHash>",
"history": [
{
"event": "<event>",
"fromStatus": "<fromStatus>",
"toStatus": "<toStatus>",
"note": "Looks good",
"detail": null,
"at": "<at>",
"actor": "<actor>"
}
],
"scheduleShiftedTo": "<scheduleShiftedTo>",
"contentIssues": [
{
"field": "<field>",
"code": "<code>",
"message": "<message>",
"line": 1
}
]
}GET /v1/broadcasts/{id}#
Read a broadcast with its history
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/broadcasts/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"channel": "<channel>",
"templateId": "<templateId>",
"content": null,
"audience": null,
"status": "draft",
"statusReason": "<statusReason>",
"requiresApproval": true,
"marketing": true,
"approvedAt": "<approvedAt>",
"contentUpdatedAt": "<contentUpdatedAt>",
"contentVersion": 1,
"scheduledFor": "<scheduledFor>",
"sendAtRequested": "<sendAtRequested>",
"recipientCount": 1,
"goal": null,
"createdVia": "<createdVia>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"approvedBy": "<approvedBy>",
"createdBy": "<createdBy>",
"recipientHash": "<recipientHash>",
"history": [
{
"event": "<event>",
"fromStatus": "<fromStatus>",
"toStatus": "<toStatus>",
"note": "Looks good",
"detail": null,
"at": "<at>",
"actor": "<actor>"
}
]
}PATCH /v1/broadcasts/{id}#
Change a broadcast
Name, goal and sendAt change in any status before sending. expectedContentVersion (the editor's last read) refuses a change when someone else saved since: 409 content_changed with the current contentVersion. A change of content, template, audience, requiresApproval or marketing is an edit: allowed in draft, rejected, approved and scheduled, it moves the broadcast back to draft (approval is needed again; history is kept). Otherwise 409 invalid_transition. A workspace's email content is stored half-built, with contentIssues (P3-14a). overwrite with the newer expectedContentVersion saves over someone else's save on purpose ("Keep mine"), recorded in the history as keptOver.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
name | string | min 1, max 200 |
content | any | |
templateId | string (uuid) | |
audience | any | |
sendAt | string (date-time) or null | |
requiresApproval | boolean | |
marketing | boolean | |
goal | object or null | |
expectedContentVersion | integer | min 1 |
overwrite | boolean |
curl -X PATCH "$SAPAGAN_URL/v1/broadcasts/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed",
"content": null,
"templateId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"audience": null
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/user-42`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed",
"content": null,
"templateId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"audience": null
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"channel": "<channel>",
"templateId": "<templateId>",
"content": null,
"audience": null,
"status": "draft",
"statusReason": "<statusReason>",
"requiresApproval": true,
"marketing": true,
"approvedAt": "<approvedAt>",
"contentUpdatedAt": "<contentUpdatedAt>",
"contentVersion": 1,
"scheduledFor": "<scheduledFor>",
"sendAtRequested": "<sendAtRequested>",
"recipientCount": 1,
"goal": null,
"createdVia": "<createdVia>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"approvedBy": "<approvedBy>",
"createdBy": "<createdBy>",
"recipientHash": "<recipientHash>",
"history": [
{
"event": "<event>",
"fromStatus": "<fromStatus>",
"toStatus": "<toStatus>",
"note": "Looks good",
"detail": null,
"at": "<at>",
"actor": "<actor>"
}
],
"scheduleShiftedTo": "<scheduleShiftedTo>",
"contentIssues": [
{
"field": "<field>",
"code": "<code>",
"message": "<message>",
"line": 1
}
]
}POST /v1/broadcasts/{id}/cancel#
Cancel a broadcast before it sends
Any status before sending to cancelled. note is kept in the history.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
note | string | max 500 |
curl -X POST "$SAPAGAN_URL/v1/broadcasts/user-42/cancel" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"note": "Looks good"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/user-42/cancel`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"note": "Looks good"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"channel": "<channel>",
"templateId": "<templateId>",
"content": null,
"audience": null,
"status": "draft",
"statusReason": "<statusReason>",
"requiresApproval": true,
"marketing": true,
"approvedAt": "<approvedAt>",
"contentUpdatedAt": "<contentUpdatedAt>",
"contentVersion": 1,
"scheduledFor": "<scheduledFor>",
"sendAtRequested": "<sendAtRequested>",
"recipientCount": 1,
"goal": null,
"createdVia": "<createdVia>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"approvedBy": "<approvedBy>",
"createdBy": "<createdBy>",
"recipientHash": "<recipientHash>",
"history": [
{
"event": "<event>",
"fromStatus": "<fromStatus>",
"toStatus": "<toStatus>",
"note": "Looks good",
"detail": null,
"at": "<at>",
"actor": "<actor>"
}
],
"scheduleShiftedTo": "<scheduleShiftedTo>",
"contentIssues": [
{
"field": "<field>",
"code": "<code>",
"message": "<message>",
"line": 1
}
]
}GET /v1/broadcasts/{id}/results#
A broadcast's results: sent, failed, held back with the reason
From the dispatcher's deliveries (P1-08; available: false before they exist). opened, clicked and conversions are null until P1-10.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/broadcasts/user-42/results" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/user-42/results`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"available": true,
"recipientCount": 1,
"queued": 1,
"sent": 1,
"failed": 1,
"suppressed": [
{
"reason": "Checked with the owner",
"count": 1
}
],
"opened": 1,
"clicked": 1,
"conversions": 1
}POST /v1/broadcasts/{id}/schedule#
Schedule an approved broadcast
approved to scheduled, at sendAt, else the send time already stored, else now. A marketing time inside quiet hours moves to the window's end (scheduleShiftedTo).
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
sendAt | string (date-time) or null |
curl -X POST "$SAPAGAN_URL/v1/broadcasts/user-42/schedule" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"sendAt": "2026-11-17T09:30:00+07:00"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/user-42/schedule`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"sendAt": "2026-11-17T09:30:00+07:00"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"channel": "<channel>",
"templateId": "<templateId>",
"content": null,
"audience": null,
"status": "draft",
"statusReason": "<statusReason>",
"requiresApproval": true,
"marketing": true,
"approvedAt": "<approvedAt>",
"contentUpdatedAt": "<contentUpdatedAt>",
"contentVersion": 1,
"scheduledFor": "<scheduledFor>",
"sendAtRequested": "<sendAtRequested>",
"recipientCount": 1,
"goal": null,
"createdVia": "<createdVia>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"approvedBy": "<approvedBy>",
"createdBy": "<createdBy>",
"recipientHash": "<recipientHash>",
"history": [
{
"event": "<event>",
"fromStatus": "<fromStatus>",
"toStatus": "<toStatus>",
"note": "Looks good",
"detail": null,
"at": "<at>",
"actor": "<actor>"
}
],
"scheduleShiftedTo": "<scheduleShiftedTo>",
"contentIssues": [
{
"field": "<field>",
"code": "<code>",
"message": "<message>",
"line": 1
}
]
}GET /v1/broadcasts/{id}/stats#
Statistics of a broadcast
Sent, not sent, opened, open rate, attributed orders and revenue. A store's credential reads its own store's broadcasts only (any other is 404), as aggregates, every number withheld below 5 sent and the not-sent count hidden (sent rounded) when it is 1 to 4; workspace credentials also read failures, unknown outcomes and suppressions by reason.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/broadcasts/user-42/stats" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/user-42/stats`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"broadcastId": "<broadcastId>",
"status": "<status>",
"withheld": true,
"rounded": true,
"sent": 1,
"notSent": 1,
"pending": 1,
"delivered": 1,
"opened": 1,
"openRate": 1,
"clicked": 1,
"clickRate": 1,
"shown": 1,
"dismissed": 1,
"conversions": 1,
"revenue": 1,
"currency": "<currency>",
"opensTracked": true,
"attribution": {
"event": "<event>",
"windowHours": 1,
"model": "<model>"
},
"deferredByWarmup": 1,
"bounced": 1,
"complained": 1,
"total": 1,
"failed": 1,
"unknown": 1,
"suppressed": {
"total": 1,
"byReason": {}
},
"conversionsByTouch": {
"opened": 1,
"sent": 1
},
"clicks": 1,
"machineOpened": 1
}POST /v1/broadcasts/{id}/submit#
Submit a draft for review
draft to submitted; a workspace broadcast that needs no approval goes to approved. 409 send_refused while the kill switches say no. A store's email campaign past its month's quota (counting campaigns already waiting) is 409 quota_exhausted, with details.overage: the top-up price and the next plan from the billing catalogue. A workspace's email is checked in full here and rendered as the send renders it: 400 invalid_content with every problem in details.issues.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X POST "$SAPAGAN_URL/v1/broadcasts/user-42/submit" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/user-42/submit`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"channel": "<channel>",
"templateId": "<templateId>",
"content": null,
"audience": null,
"status": "draft",
"statusReason": "<statusReason>",
"requiresApproval": true,
"marketing": true,
"approvedAt": "<approvedAt>",
"contentUpdatedAt": "<contentUpdatedAt>",
"contentVersion": 1,
"scheduledFor": "<scheduledFor>",
"sendAtRequested": "<sendAtRequested>",
"recipientCount": 1,
"goal": null,
"createdVia": "<createdVia>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"approvedBy": "<approvedBy>",
"createdBy": "<createdBy>",
"recipientHash": "<recipientHash>",
"history": [
{
"event": "<event>",
"fromStatus": "<fromStatus>",
"toStatus": "<toStatus>",
"note": "Looks good",
"detail": null,
"at": "<at>",
"actor": "<actor>"
}
],
"scheduleShiftedTo": "<scheduleShiftedTo>",
"contentIssues": [
{
"field": "<field>",
"code": "<code>",
"message": "<message>",
"line": 1
}
]
}POST /v1/broadcasts/{id}/test#
Send a test of a workspace campaign (push, in-app or email)
Email: renders the campaign's stored email (as the person profileId names, or someone with no attributes) and sends it to to, which must be one of the workspace's test addresses (PUT /v1/workspace/email-settings, owner); the subject starts with [Test], the footer's links open the preference center's neutral page, no List-Unsubscribe headers; a refused address is 403 test_send_refused, a suppressed one (a bounce or a complaint) 409 suppressed_address. Push and in-app (operator sessions only): profileId (an external id) must be one of the workspace's test people (GET /v1/setup/test-people; else 403 test_send_refused), not unsubscribed from marketing (409 test_person_unsubscribed); the message is rendered for them with [Test] before the title and goes at once: a push to each of their live devices (at most 5; 409 no_device without one), an in-app message at the app's next fetch (for a day). Tests ignore quiet hours, frequency caps and quotas, need no approval, never count in statistics, and are audited; a kill switch still stops them (409 sending_off). Limited per workspace and per campaign, counted before the person or address is checked.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
to | string | max 254 |
profileId | string | min 1, max 200 |
curl -X POST "$SAPAGAN_URL/v1/broadcasts/user-42/test" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "<to>",
"profileId": "user-42"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/user-42/test`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"to": "<to>",
"profileId": "user-42"
}),
});
const data = await res.json();Responses
{
"sent": true,
"channel": "push",
"providerMessageId": "<providerMessageId>",
"subject": "<subject>",
"title": "Pesanan dikirim",
"person": {
"externalId": "user-42",
"name": "order_placed"
},
"deliveries": [
{
"deliveryId": "<deliveryId>",
"status": "queued",
"code": "<code>"
}
],
"fakeChannel": true
}POST /v1/broadcasts/email-preview#
Preview a workspace email for one person, as the send renders it, with the review checks
Give content (inline: P2-04's {subject, preheader, blocks} plus layoutId) or broadcastId (a workspace email campaign's stored content). profileId is an external id: the email as that person gets it; without it, as someone with no attributes. The footer's links are sample links. A problem is valid: false with errors; checks are the review step's (subject length, preview text, the unsubscribe link, image hosts, links, the sender, the size).
Request body
| Field | Type | Notes |
|---|---|---|
content | any | |
broadcastId | string (uuid) | |
profileId | string | min 1, max 200 |
curl -X POST "$SAPAGAN_URL/v1/broadcasts/email-preview" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": null,
"broadcastId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"profileId": "user-42"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/email-preview`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"content": null,
"broadcastId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"profileId": "user-42"
}),
});
const data = await res.json();Responses
{
"valid": true,
"errors": [
{
"field": "<field>",
"code": "<code>",
"message": "<message>",
"line": 1
}
],
"warnings": [
{
"field": "<field>",
"code": "<code>",
"message": "<message>"
}
],
"email": {
"subject": "<subject>",
"preheader": "<preheader>",
"html": "<html>",
"text": "<text>",
"links": [
"<links>"
],
"sizeBytes": 1
},
"checks": [
{
"code": "<code>",
"ok": true,
"level": "ok",
"title": "Pesanan dikirim",
"detail": "<detail>"
}
],
"profileFound": true
}POST /v1/broadcasts/inapp-preview#
Preview a workspace in-app message's title and text for one person
content: the in-app message as the composer holds it. profileId is an external id: rendered as that person gets it (audited as a preview); without it, as someone with no attributes. A problem is valid: false with errors.
Request body
| Field | Type | Notes |
|---|---|---|
content | any | |
profileId | string | min 1, max 200 |
curl -X POST "$SAPAGAN_URL/v1/broadcasts/inapp-preview" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": null,
"profileId": "user-42"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/inapp-preview`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"content": null,
"profileId": "user-42"
}),
});
const data = await res.json();Responses
{
"valid": true,
"errors": [
{
"field": "<field>",
"code": "<code>",
"message": "<message>",
"line": 1
}
],
"rendered": {
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan."
},
"profileFound": true
}POST /v1/broadcasts/preview#
Preview a workspace campaign's push for one person, as the dispatcher renders it
Give content (inline) or broadcastId (a workspace broadcast's stored snapshot). profileId is an external id: the push as that person gets it; without it, as someone with no attributes. A render problem is valid: false with errors.
Request body
| Field | Type | Notes |
|---|---|---|
content | any | |
broadcastId | string (uuid) | |
profileId | string | min 1, max 200 |
curl -X POST "$SAPAGAN_URL/v1/broadcasts/preview" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": null,
"broadcastId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"profileId": "user-42"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/preview`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"content": null,
"broadcastId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"profileId": "user-42"
}),
});
const data = await res.json();Responses
{
"valid": true,
"errors": [
{
"field": "<field>",
"code": "<code>",
"message": "<message>",
"line": 1,
"column": 1
}
],
"warnings": [
{
"code": "<code>",
"field": "<field>",
"platform": "<platform>",
"limit": 1,
"length": 1,
"truncatedText": "<truncatedText>"
}
],
"rendered": {
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan.",
"imageUrl": "<imageUrl>",
"link": "<link>",
"type": "<type>"
},
"profileFound": true
}GET /v1/broadcasts/stats#
Statistics of several broadcasts
Up to 50 ids, comma-separated. Broadcasts the caller cannot see are left out. A store's credential reads aggregates only, with small numbers withheld.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
ids | query | string required |
curl -X GET "$SAPAGAN_URL/v1/broadcasts/stats?ids=%3Cids%3E" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/stats?ids=%3Cids%3E`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"stats": [
{
"broadcastId": "<broadcastId>",
"status": "<status>",
"withheld": true,
"rounded": true,
"sent": 1,
"notSent": 1,
"pending": 1,
"delivered": 1,
"opened": 1,
"openRate": 1,
"clicked": 1,
"clickRate": 1,
"shown": 1,
"dismissed": 1,
"conversions": 1,
"revenue": 1,
"currency": "<currency>",
"opensTracked": true,
"attribution": {
"event": "<event>",
"windowHours": 1,
"model": "<model>"
},
"deferredByWarmup": 1,
"bounced": 1,
"complained": 1,
"total": 1,
"failed": 1,
"unknown": 1,
"suppressed": {
"total": 1,
"byReason": {}
},
"conversionsByTouch": {
"opened": 1,
"sent": 1
},
"clicks": 1,
"machineOpened": 1
}
]
}POST /v1/media#
Upload a push image: cropped, resized to 1024 x 512 and re-encoded by the api
dataBase64: a JPEG, PNG, WebP, GIF or AVIF file (about 3.6 MB and 16 megapixels at most). crop: the part to keep, in pixels of the upright picture; it is then cropped to 2:1 around its centre. The answer's url goes into a push's imageUrl. 400 invalid_image with details.reason (not_image, too_small, too_large, bad_crop, unreadable); 429 rate_limited or media_quota; 503 busy or media_unavailable.
Request body
| Field | Type | Notes |
|---|---|---|
dataBase64 required | string | min 16, max 4900000 |
crop | object | |
crop.left required | number | min 0 |
crop.top required | number | min 0 |
crop.width required | number | min 0 |
crop.height required | number | min 0 |
curl -X POST "$SAPAGAN_URL/v1/media" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"dataBase64": "<dataBase64>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/media`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"dataBase64": "<dataBase64>"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"url": "https://example.com",
"contentType": "<contentType>",
"width": 1,
"height": 1,
"bytes": 1,
"sha256": "<sha256>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"withdrawnAt": "<withdrawnAt>",
"created": true,
"source": {
"width": 1,
"height": 1,
"format": "<format>"
},
"quality": 1
}GET /v1/media/{id}#
One of the workspace's uploaded images
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/media/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/media/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"url": "https://example.com",
"contentType": "<contentType>",
"width": 1,
"height": 1,
"bytes": 1,
"sha256": "<sha256>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"withdrawnAt": "<withdrawnAt>"
}POST /v1/media/{id}/withdraw#
Take an uploaded image down (owner): its public URL answers 404; audited with the reason
Pushes already delivered keep what the phone downloaded; new fetches get 404, and caches let go within a day (max-age=86400). Cannot be undone.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
reason required | string | min 3, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/media/user-42/withdraw" \
-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/media/user-42/withdraw`, {
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
{
"id": "user-42",
"url": "https://example.com",
"contentType": "<contentType>",
"width": 1,
"height": 1,
"bytes": 1,
"sha256": "<sha256>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"withdrawnAt": "<withdrawnAt>"
}GET /v1/workspace/campaign-settings#
The workspace's campaign settings and sending rules
curl -X GET "$SAPAGAN_URL/v1/workspace/campaign-settings" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/campaign-settings`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"secondApproval": true,
"links": {
"hosts": [
"<hosts>"
],
"schemes": [
"<schemes>"
]
},
"rules": {
"quietHours": {
"start": "<start>",
"end": "<end>",
"timeZone": "<timeZone>",
"note": "Looks good"
},
"storeCaps": {
"perStore": {
"count": 1,
"days": 1
},
"allStores": {
"count": 1,
"days": 1
}
},
"workspaceCampaignsCapped": true
},
"images": {
"hosts": [
"<hosts>"
],
"uploadHost": "<uploadHost>"
}
}PUT /v1/workspace/campaign-settings#
Change the campaign settings (owner); audited with the reason
secondApproval: the workspace's own campaigns need a person who did not write them (the AI never approves them). links: the https hosts and app schemes a campaign's link destination may open.
Request body
| Field | Type | Notes |
|---|---|---|
secondApproval | boolean | |
links | object | |
links.hosts | string[] | up to 50 items |
links.schemes | string[] | up to 20 items |
reason required | string | min 3, max 2000 |
curl -X PUT "$SAPAGAN_URL/v1/workspace/campaign-settings" \
-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/workspace/campaign-settings`, {
method: "PUT",
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
{
"secondApproval": true,
"links": {
"hosts": [
"<hosts>"
],
"schemes": [
"<schemes>"
]
},
"changed": true
}POST /v1/workspace/campaign-settings/link-hosts#
Allow one more link host (owner); audited with the reason
Adds host to the link allowlist under a row lock (two owners adding two hosts at once both land). Already listed: changed: false.
Request body
| Field | Type | Notes |
|---|---|---|
host required | string | min 1, max 253 |
reason required | string | min 3, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/workspace/campaign-settings/link-hosts" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"host": "<host>",
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/campaign-settings/link-hosts`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"host": "<host>",
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"secondApproval": true,
"links": {
"hosts": [
"<hosts>"
],
"schemes": [
"<schemes>"
]
},
"changed": true
}GET /v1/workspace/email-sender#
The From of the workspace's own email, and its test addresses
The active sending domain's default address and display name (missing says why there is none: no_sending_domain or no_sender), the Reply-To, and the workspace's test addresses (set by an owner in the email settings).
curl -X GET "$SAPAGAN_URL/v1/workspace/email-sender" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/email-sender`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"from": "<from>",
"displayName": "<displayName>",
"replyTo": "<replyTo>",
"domain": "<domain>",
"missing": "no_sending_domain",
"testRecipients": [
"<testRecipients>"
]
}