API reference
Messages
/messages
Messages are produced by rules when you post events. They are read only: there is no messages:write and no way to send one directly.
GET/messagesList · ?q ?contact_id ?subject_id ?status ?channelshown →GET/messages/{message_id}ReadGET/messages/{message_id}/emailRead the email as it went
GETList messages
Requires messages:read. By person: what this person has been told. By membership: what has been said about them. By status: what is still in flight, what failed and why.
Query parameters
limitinteger · default 50 · max 200
offsetinteger · default 0
qstring · optional · max 100
Matches the number it went to, the text, the status or the error. It goes on top of whichever filters are set.
contact_iduuid · optional
subject_iduuid · optional
statusoptional
queued · sending · sent · delivered · read · failed · cancelled.
channelwhatsapp | sms | email · optional
Returns
200 with an array of messages, each with its channel, rendered_body, status and timestamps.
Response body
A bare JSON array. Each item is one message: the same fields in every pack. Press Response on the sample to see one whole.
FieldTypeDescription
iduuid
tenant_iduuidThe instance.
send_iduuidThe send it belongs to: why it exists.
hold_iduuidThe budget reservation that pays for it.
chunk_nointegerWhich task sends it. The number also says the channel: SMS below 1000000, email from 1000000, WhatsApp from 2000000.
fallback_ofuuid | nullThe WhatsApp message this SMS replaced. A fallback is a new message, never a changed one, sent a little later under a budget reservation of its own.
connection_iduuidThe sender the person sees it from.
contact_iduuid
subject_iduuid | null
template_iduuid | null
kindtemplate | freeform
channelwhatsapp | sms | email
priority_classurgent | critical | normal | bulk
rendered_bodystringAs it went, with every placeholder filled.
statusstringqueued · sending · sent · delivered · read · failed · cancelled.
due_atdatetime
attemptsinteger
claimed_atdatetime | null
providerstring | nullThe route that carried it, such as meta for WhatsApp or gmail for email.
provider_message_idstring | null
error_codestring | nullWhy it did not go, as a short stable word: wa_not_on_whatsapp, sms_undeliverable, email_bad_address, hold_expired, unknown_outcome and the like. On a sent email, email_unconfirmed means the mailbox did not confirm in time.
counted_atdatetime | nullWhen it was counted against the budget.
queued_atdatetime
sent_atdatetime | null
delivered_atdatetime | null
failed_atdatetime | null
receipt_checked_atdatetime | null
is_copybooleanA copy to a copy recipient rather than a message to the audience.
sms_partsinteger
provider_partsinteger | null
provider_charge_centsinteger | nullWhat the provider said it billed, in cents.
to_addressstring | nullEmail only: the address it went to, kept as it was then.
rendered_subjectstring | nullEmail only: the subject as it went.
body_valuesstring[] | nullThe placeholder values in order, on WhatsApp template messages and emails.
email_design_revision_iduuid | nullEmail only: the exact revision of the design it went out in.
fallback_due_atdatetime | nullSet while a WhatsApp message that could not be delivered is waiting for its SMS.
provider_pricingobject | nullWhat WhatsApp's receipt said about billing: billable and category.
to_e164string | nullAlways null on a read.
On failure the body is { error, code } instead.