SapaganDocs sapagan.com

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

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/templates and purpose: "transactional". The purpose is set at creation and never changes. A marketing template is refused with template_not_transactional.
  • title and body are Liquid. The request's data is available as event, for example {{ event.sender_name }}. customer holds the person's attributes and id. delivery has id and count.
  • safeData holds values you do not want in the stored message.

Channels#

channels is a list of up to three of push, web_push and email.

  • push is the person's phones and web_push is 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#

AppliesDoes not apply
Kill switchesQuiet hours
The development test listMarketing frequency caps
Deleted and erased peopleThe 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/stats gives 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 is 409 no_device.