SapaganDocs sapagan.com

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.

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
scopeIdquerystring (uuid) or "none"
statusquery"draft" | "submitted" | "ai_flagged" | "approved" | "rejected" | "scheduled" | "sending" | "sent" | "failed" | "cancelled"
afterquerystring (uuid)
limitqueryinteger
curl -X GET "$SAPAGAN_URL/v1/broadcasts" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key Store key Store token

Request body

FieldTypeNotes
scopeIdstring (uuid) or null
name requiredstringmin 1, max 200
channel required"push" | "email" | "inapp"
templateIdstring (uuid)
contentany
audienceany
sendAtstring (date-time) or null
requiresApprovalboolean
marketingboolean
goalobject 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"
  }'

Responses

201 Created, 400 Invalid request, 404 Not found, 409 Conflict. Errors use the error body.

Example response 201

{
  "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

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/broadcasts/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
namestringmin 1, max 200
contentany
templateIdstring (uuid)
audienceany
sendAtstring (date-time) or null
requiresApprovalboolean
marketingboolean
goalobject or null
expectedContentVersionintegermin 1
overwriteboolean
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
  }'

Responses

200 OK, 400 Invalid request, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
notestringmax 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"
  }'

Responses

200 OK, 400 Invalid request, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/broadcasts/user-42/results" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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).

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
sendAtstring (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"
  }'

Responses

200 OK, 400 Invalid request, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/broadcasts/user-42/stats" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idpathstring required
curl -X POST "$SAPAGAN_URL/v1/broadcasts/user-42/submit" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200 OK, 400 Invalid request, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
tostringmax 254
profileIdstringmin 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"
  }'

Responses

202 Accepted, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict, 429 Rate limited, 502 Send failed, 503 Unavailable. Errors use the error body.

Example response 202

{
  "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).

Accepted keys Server key

Request body

FieldTypeNotes
contentany
broadcastIdstring (uuid)
profileIdstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Request body

FieldTypeNotes
contentany
profileIdstringmin 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"
  }'

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Request body

FieldTypeNotes
contentany
broadcastIdstring (uuid)
profileIdstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idsquerystring required
curl -X GET "$SAPAGAN_URL/v1/broadcasts/stats?ids=%3Cids%3E" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 400 Invalid request. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Request body

FieldTypeNotes
dataBase64 requiredstringmin 16, max 4900000
cropobject
crop.left requirednumbermin 0
crop.top requirednumbermin 0
crop.width requirednumbermin 0
crop.height requirednumbermin 0
curl -X POST "$SAPAGAN_URL/v1/media" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataBase64": "<dataBase64>"
  }'

Responses

200 OK, 201 Created, 400 Invalid request, 403 Forbidden, 429 Rate limited, 503 Unavailable. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/media/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
reason requiredstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/workspace/campaign-settings" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Request body

FieldTypeNotes
secondApprovalboolean
linksobject
links.hostsstring[]up to 50 items
links.schemesstring[]up to 20 items
reason requiredstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Request body

FieldTypeNotes
host requiredstringmin 1, max 253
reason requiredstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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).

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/workspace/email-sender" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "from": "<from>",
  "displayName": "<displayName>",
  "replyTo": "<replyTo>",
  "domain": "<domain>",
  "missing": "no_sending_domain",
  "testRecipients": [
    "<testRecipients>"
  ]
}