Guides
Transactional messages
Send one message to one person now, such as a new chat message or an order update.
A transactional message is one message to one person that you trigger from your backend. Use it for things the person is waiting for: a new chat message, an order update, a code. Send it with POST /v1/send and a server key.
A first send#
curl -X POST "$SAPAGAN_URL/v1/send" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: chat-1042-msg-77" \
-d '{
"to": { "externalId": "user-42" },
"templateId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"data": { "sender_name": "Budi", "preview": "Apakah jadwal besok jadi?" },
"channels": ["push", "web_push", "email"],
"collapseKey": "chat:1042"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/send`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "chat-1042-msg-77",
},
body: JSON.stringify({
to: { externalId: "user-42" },
templateId: "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
data: { sender_name: "Budi", preview: "Apakah jadwal besok jadi?" },
channels: ["push", "web_push", "email"],
collapseKey: "chat:1042",
}),
});The answer is 202 with the message id and its status. Read it later with GET /v1/send/{id}.
Content#
Give either a transactional template (templateId) or inline push content (title, body, optional imageUrl, and a destination). Never both.
- Create a template with
POST /v1/templatesandpurpose: "transactional". The purpose is set at creation and never changes. A marketing template is refused withtemplate_not_transactional. titleandbodyare Liquid. The request'sdatais available asevent, for example{{ event.sender_name }}.customerholds the person's attributes andid.deliveryhasidandcount.safeDataholds values you do not want in the stored message.
Channels#
channels is a list of up to three of push, web_push and email.
pushis the person's phones andweb_pushis their browsers. Listed together, both go.- Devices always come before
email, whatever the order. Email is used only when no device reaches the person. - A send goes to every live device of the chosen channel, at most 5, most recently seen first.
- A channel that is not available is skipped, so you can list a channel before you set it up.
- A provider failure on the chosen channel does not fall back to another channel.
Collapse chatty messages#
With collapseKey, messages for the same person and key within collapseWindowSeconds (1 to 600, default 15) become one push, rendered from the latest message. delivery.count says how many it stands for. The cost is delay: the first message waits for the window to end.
Skip if the person is active#
skipIfActiveWithinSeconds (1 to 3600) sends nothing when the person had any event in that many seconds. Events from the store connector do not count. The Flutter SDK flushes every 30 seconds, so use 60 or more.
What applies, and what does not#
| Applies | Does not apply |
|---|---|
| Kill switches | Quiet hours |
| The development test list | Marketing frequency caps |
| Deleted and erased people | The person's marketing unsubscribe |
| Suppressed addresses and invalid devices | |
The topic you name, when the person revoked it |
Per person, at most 60 messages are accepted a minute (429 recipient_rate_limited with Retry-After), and at most 10 a minute and 100 an hour reach them. A message past that is suppressed with the reason rate_limited.
Idempotency#
Send an Idempotency-Key header. A retry with the same key and the same body within 24 hours replays the first answer (Idempotent-Replayed). The key is kept on the message, so a retry after 24 hours returns the first message with 200 and replayed: true, and sends nothing. The same key with a different body is 422 idempotency_key_reused. Without a key, every request is a new message.
Reading results#
GET /v1/send/{id}shows the message and its deliveries.GET /v1/send/statsgives messages and deliveries by status, suppressions by reason and opens, for up to 31 days.- A recipient that does not exist is
404 recipient_not_found. A person with no device and no address is409 no_device.