SapaganDocs sapagan.com

API reference

Transactional

Send one message to one person now, and read what happened to it.

Send one message to one person now, and read what happened to it.

POST /v1/send#

Send a transactional message

One message to one person now (a new chat message, an order update). Give a transactional template (templateId) or inline push content, and data for Liquid as event. Sent on the first of channels that reaches the person, to every live device of that channel (at most 5); push (phones) and web_push (browsers) listed together both go, and devices always come before email, whatever the order (email only when no device reaches the person). Not held by quiet hours or marketing caps, and reaches a person who unsubscribed from marketing; never a deleted or erased person, a revoked topic, a suppressed address, or past 10 messages a minute and 100 an hour per person. collapseKey: messages for the same person and key within collapseWindowSeconds (default 15) become one push rendered from the latest, with delivery.count. skipIfActiveWithinSeconds: nothing is sent when the person used the app that recently. Workspace keys only. With Idempotency-Key, a retry never sends twice.

Accepted keys Server key

Request body

FieldTypeNotes
to requiredobject
to.externalId requiredstringmin 1, max 200
templateIdstring (uuid)
contentany
dataobject
safeDataobject
channels"push" | "web_push" | "email"[]up to 3 items
topicstring
collapseKeystringmin 1, max 200
collapseWindowSecondsintegermin 1, max 600
skipIfActiveWithinSecondsintegermin 1, max 3600
curl -X POST "$SAPAGAN_URL/v1/send" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "externalId": "user-42"
    },
    "content": {
      "title": "Pesan baru",
      "body": "Budi: apakah jadwal besok jadi?",
      "destination": {
        "kind": "app",
        "path": "/chat/1042"
      }
    },
    "channels": [
      "push",
      "web_push",
      "email"
    ],
    "collapseKey": "chat:1042",
    "data": {
      "sender_name": "Budi"
    }
  }'

Responses

200 OK, 202 Accepted, 400 Invalid request, 404 Not found, 429 Rate limited. Errors use the error body.

Example response 200

{
  "id": "user-42",
  "status": "pending",
  "statusReason": "<statusReason>",
  "templateId": "<templateId>",
  "channels": [
    "<channels>"
  ],
  "channel": "<channel>",
  "collapseKey": "<collapseKey>",
  "collapsedInto": "<collapsedInto>",
  "collapsedCount": 1,
  "runAt": "<runAt>",
  "createdAt": "<createdAt>",
  "finishedAt": "<finishedAt>",
  "replayed": true
}

GET /v1/send/{id}#

Read a transactional message

The message's status and its deliveries; a collapsed message lists the deliveries of the push it joined (collapsedInto).

Accepted keys Server key

Parameters

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

Responses

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

Example response 200

{
  "id": "user-42",
  "status": "pending",
  "statusReason": "<statusReason>",
  "templateId": "<templateId>",
  "channels": [
    "<channels>"
  ],
  "channel": "<channel>",
  "collapseKey": "<collapseKey>",
  "collapsedInto": "<collapsedInto>",
  "collapsedCount": 1,
  "runAt": "<runAt>",
  "createdAt": "<createdAt>",
  "finishedAt": "<finishedAt>",
  "deliveries": [
    {
      "id": "user-42",
      "channel": "<channel>",
      "status": "<status>",
      "suppressedReason": "<suppressedReason>",
      "sentAt": "<sentAt>"
    }
  ]
}

GET /v1/send/stats#

Transactional message totals

Messages by status, deliveries by status, suppressions by reason and opened deliveries for messages created in [since, until) (at most 31 days; default the last 7 days), optionally for one template.

Accepted keys Server key

Parameters

NameInTypeNotes
sincequerystring (date-time)
untilquerystring (date-time)
templateIdquerystring (uuid)
curl -X GET "$SAPAGAN_URL/v1/send/stats" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

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

Example response 200

{
  "since": "<since>",
  "until": "<until>",
  "messages": {},
  "deliveries": {},
  "suppressed": {},
  "opened": 1
}

GET /v1/workspace/transactional-settings#

The workspace's transactional settings

Accepted keys Server key

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

Responses

200 OK. Errors use the error body.

Example response 200

{
  "pushPreview": true,
  "genericTitle": "<genericTitle>",
  "genericBody": "<genericBody>",
  "dailyCap": 1
}

PUT /v1/workspace/transactional-settings#

Change the transactional settings (owner); audited with the reason

pushPreview (default false): whether a push may show the request's data on the lock screen; off, only safeData reaches Liquid and an empty title or body becomes genericTitle / genericBody. dailyCap: messages the workspace may accept in 24 hours (default 20,000).

Accepted keys Server key

Request body

FieldTypeNotes
pushPreviewboolean
genericTitlestringmax 200
genericBodystringmax 200
dailyCapintegermin 0, max 10000000
reason requiredstringmin 1, max 500
curl -X PUT "$SAPAGAN_URL/v1/workspace/transactional-settings" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Checked with the owner"
  }'

Responses

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

Example response 200

{
  "pushPreview": true,
  "genericTitle": "<genericTitle>",
  "genericBody": "<genericBody>",
  "dailyCap": 1,
  "changed": true
}