Messages
Retrieve messages
Returns a paginated list of messages filtered by provided parameters. Default order is by created_at in descending order. Requires the API key scope messages:read.
query Parameters
contextContext to filter messages by
context_idID of the context to filter messages by
transportTransport used to send the message
time_fieldTime field the from/to filter applies to. Required when from or to is present.
fromLower bound of the time_field filter. Europe/Rome timezone, RFC 3339 format (e.g. 2026-06-26T00:00:00+02:00)
toUpper bound of the time_field filter. Europe/Rome timezone, RFC 3339 format (e.g. 2026-06-26T23:59:59+02:00)
sort_fieldSort column. With sent_at only the messages that have been sent are listed (a draft has no sent time). Keep the same sort_field on every page of a read: a next_cursor obtained with one sort field returns 400 with another.
sort_orderIf sort_field is specified but sort_order is not, the default order is 'asc'
paging_limitLimit items returned in response. Must be between 1 and 50
next_cursorRetrieve messages › Responses
Retrieve a single message
Requires the API key scope messages:read.
path Parameters
messageIdRetrieve a single message › Responses
Message found
idstatuscreated_atMessage creation time.
subjecttransportdirectionsent_atMessage send time.
last_read_atLast read time.
readsEvery time the message was read, in ascending order (the last one is last_read_at). Only in the detail of a message (GET /api/v1/messages/{messageId}), null everywhere else (the list and the replies) because reading it costs a query per message. An empty list when the message was never read.
language^[a-z]{2}$Language of the first recipient. null if not set.
Create a draft reply to a message
Creates a draft reply to an existing message. The draft is saved with status: draft and is
not sent. To attach files use POST /api/v1/messages/{messageId}/attachments (messageId here
is the id of the draft returned by this call, not the original message), to remove one use
DELETE /api/v1/messages/{messageId}/attachments/{fileName}, and to actually send the draft use
POST /api/v1/messages/{messageId}/send. Before sending, the draft's subject/message can be
amended with PATCH /api/v1/messages/{messageId}.
Requires the API key scope messages:write.
path Parameters
messageIdCreate a draft reply to a message › Responses
Draft created
idstatuscreated_atMessage creation time.
subjecttransportdirectionsent_atMessage send time.
last_read_atLast read time.
readsEvery time the message was read, in ascending order (the last one is last_read_at). Only in the detail of a message (GET /api/v1/messages/{messageId}), null everywhere else (the list and the replies) because reading it costs a query per message. An empty list when the message was never read.
language^[a-z]{2}$Language of the first recipient. null if not set.
Amend a draft reply
Updates subject/message of a reply that is still in draft status. Requires the API key scope messages:write.
path Parameters
messageIdAmend a draft reply › Responses
Draft updated
idstatuscreated_atMessage creation time.
subjecttransportdirectionsent_atMessage send time.
last_read_atLast read time.
readsEvery time the message was read, in ascending order (the last one is last_read_at). Only in the detail of a message (GET /api/v1/messages/{messageId}), null everywhere else (the list and the replies) because reading it costs a query per message. An empty list when the message was never read.
language^[a-z]{2}$Language of the first recipient. null if not set.
Upload an attachment to a draft reply
Uploads one file to a reply that is still in draft status. One file per call. Attachment rules
depend on the transport of the original message:
| Transport | Attachments allowed | Accepted MIME types | Size limit |
|---|---|---|---|
sms | No | — | — |
email | Yes | image/png, image/jpeg, image/gif, application/pdf | Total ≤ 10 MB (all attachments of the draft combined) |
airbnb | Yes | image/png, image/jpeg, image/gif | Each file ≤ 5 MB |
If an attachment with the same file name already exists on the draft, the uploaded file is renamed
(e.g. photo-1.jpg) — the client must read the actual name back from the response.
Requires the API key scope messages:write.
path Parameters
messageIdUpload an attachment to a draft reply › Request Body
fileUpload an attachment to a draft reply › Responses
Attachment uploaded
nameurlmime_typeRemove an attachment from a draft reply
Removes a file previously uploaded to a reply that is still in draft status. Requires the API key scope messages:delete.
path Parameters
messageIdfileName.+ · requiredMust be URL-encoded, since the original file name may contain characters not valid in a path segment (spaces, %, non-ASCII, etc.). Cannot contain < > : " / \ | ? * (invalid in file names) or control characters.
Remove an attachment from a draft reply › Responses
Attachment removed
Send a draft reply
Queues a reply that is in draft status for sending. This call is asynchronous: it moves the
draft to status: queued and returns immediately, the actual delivery through the transport happens
afterwards. Returns 409 if the message is not currently in draft status (for example it was already sent).
For the airbnb transport, text and media cannot be sent together:
if the draft has attachments, the message text and each attachment are delivered as
separate messages on the conversation thread, text first.
Requires the API key scope messages:send.
path Parameters
messageIdSend a draft reply › Responses
Message queued for send
idstatuscreated_atMessage creation time.
subjecttransportdirectionsent_atMessage send time.
last_read_atLast read time.
readsEvery time the message was read, in ascending order (the last one is last_read_at). Only in the detail of a message (GET /api/v1/messages/{messageId}), null everywhere else (the list and the replies) because reading it costs a query per message. An empty list when the message was never read.
language^[a-z]{2}$Language of the first recipient. null if not set.

