Skip to content
Notifications and messages

Notifications and messages

Notifications

A notification is one trigger for one recipient. All routes take an API key.

Method and pathPurpose
GET /v1/notificationsList. Query: workflowId, subscriberId, transactionId, status (pending, started, failed or cancelled), since (RFC 3339 lower bound on creation), limit (1 to 200, default 50), cursor. Returns {"items": […], "next": "…", "totalCount": n}; next is absent on the last page.
GET /v1/notifications/{id}One notification; 404 if absent.
GET /v1/notifications/{id}/messagesThe messages the notification produced, newest first.

A notification has the camelCase fields id, workflowId, subscriberId, transactionId, runId, payload, createdAt, digestKey, status and runStartedAt (when runId was recorded; empty while there is no run).

status is where the notification’s run stands. A trigger records the notification before it starts the run, so the notification can exist before the run does:

statusMeaning
pendingRecorded; the run has not been confirmed yet. runId is empty. A trigger whose start timed out leaves this, and retrying it with the same transactionId reuses the notification. One still pending with no run after 15 minutes is marked failed.
startedThe run started; runId names it. Notifications recorded before this field existed read started.
failedThe engine refused the run, or the notification stayed pending for 15 minutes with no run. runId is empty. Retrying the trigger with the same transactionId tries again on the same notification, and a run that does turn up late records itself and moves the notification to started.
cancelledThe trigger was cancelled before its run finished. runId names the run if one started. Nothing moves a notification out of cancelled.

The list returns every status unless status is given.

Status is not delivery

status tracks the run, not the messages. A notification stays started after its messages are sent, and it does not change when a message is delivered or fails. To check delivery, read the notification’s messages at GET /v1/notifications/{id}/messages. Each message has its own status. To be told as delivery happens, subscribe to the delivery events in Outbound webhooks.

Messages

The inbox routes accept an API key or a subscriber session. Behaviour is described under Inbox.

Method and pathPurpose
GET /v1/messagesList: the paginated envelope {data, next, unreadCount, unseenCount}, or with integrationId= a bare array for one integration.
GET /v1/messages/count{"count": n} for a badge.
POST /v1/messages/markBulk mark {subscriberId, ids | all, as}. 204.
POST /v1/messages/{id}/{action}seen, read, unread, archive, unarchive. 204; 404 for a missing or someone else’s message.
GET /v1/inbox/stream?subscriberId=Live SSE of new in-app messages. API key only.

Message object

Every message endpoint (GET /v1/messages and GET /v1/notifications/{id}/messages) returns this camelCase shape:

FieldMeaning
idMessage id (ULID).
workflowIdInternal workflow id.
workflowIdentifierThe workflow’s trigger identifier, when the workflow still exists.
notificationId, runId, stepIdThe notification, engine run and step that produced it.
subscriberIdRecipient.
channelin_app, email, push, chat, sms or stream.
providerId, integrationIdThe provider and integration that sent it.
subject, contentThe rendered subject and body. For stream, subject is the topic.
statussent, error, skipped or throttled. An sms message may later move from sent to delivered or error by delivery status.
providerMessageIdThe id the provider gave the message at send (an SMS MessageSid), when it gave one.
errorTextThe failure, when status is error.
errorClassWhy it failed, when status is error: auth (the provider refused the credentials), rate_limited, provider_down (5xx, timeout, unreachable), rejected_message (the provider refused this message) recipient (a bad or unknown address) or not_configured (the scope has no integration for the channel).
skipReasonWhy a step was skipped, when status is skipped: condition, condition_invalid, preference, no_verified_phone (sms), opted_out (sms: the number texted STOP), no_email (email), no_device (push) or no_channel (chat). A recipient with no address for the channel is skipped, not failed.
seen, read, archivedInbox state.
transactionIdThe transaction.
createdAtRFC 3339.
extrasFor in_app: avatar, primaryAction, secondaryAction, redirect, data. {} otherwise.

Earlier releases serialized messages and notifications with Go field names (ID, Status, ErrorText, …). That was a bug; the keys are now camelCase, and the scope ids (OrgID, EnvID) are no longer returned.

Analytics

Method and pathPurpose
GET /v1/analytics/deliveriesDelivery counts as {channel: {status: count}}.
GET /v1/analytics/timeseriesArray of {day, channel, status, count}.

Neither takes parameters. The console has per-workflow and date views that the API does not expose.