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.
Request body
| Field | Type | Notes |
|---|---|---|
to required | object | |
to.externalId required | string | min 1, max 200 |
templateId | string (uuid) | |
content | any | |
data | object | |
safeData | object | |
channels | "push" | "web_push" | "email"[] | up to 3 items |
topic | string | |
collapseKey | string | min 1, max 200 |
collapseWindowSeconds | integer | min 1, max 600 |
skipIfActiveWithinSeconds | integer | min 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"
}
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/send`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"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"
}
}),
});
const data = await res.json();Responses
{
"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).
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/send/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/send/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"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.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
since | query | string (date-time) | |
until | query | string (date-time) | |
templateId | query | string (uuid) |
curl -X GET "$SAPAGAN_URL/v1/send/stats" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/send/stats`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"since": "<since>",
"until": "<until>",
"messages": {},
"deliveries": {},
"suppressed": {},
"opened": 1
}GET /v1/workspace/transactional-settings#
The workspace's transactional settings
curl -X GET "$SAPAGAN_URL/v1/workspace/transactional-settings" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/transactional-settings`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"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).
Request body
| Field | Type | Notes |
|---|---|---|
pushPreview | boolean | |
genericTitle | string | max 200 |
genericBody | string | max 200 |
dailyCap | integer | min 0, max 10000000 |
reason required | string | min 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"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/transactional-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
{
"pushPreview": true,
"genericTitle": "<genericTitle>",
"genericBody": "<genericBody>",
"dailyCap": 1,
"changed": true
}