Skip to main content
GET
cURL

Authorizations

Authorization
string
header
required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Query Parameters

cursor
string

Opaque cursor from a previous response to fetch the next page

Pattern: ^[cC][^\s-]{8,}$
limit
integer
default:20

Maximum number of items to return per page (1–100, default 20)

Required range: 1 <= x <= 100
agentId
string

Filter messages by agent ID

Pattern: ^[cC][^\s-]{8,}$
threadId
string

Filter messages by conversation thread ID

Pattern: ^[cC][^\s-]{8,}$
channel
enum<string>

Filter messages by communication channel

Available options:
EMAIL,
SMS,
MMS,
VOICE
channels
enum<string>[]

Filter messages by several channels at once, e.g. SMS+MMS to see a full text conversation. Takes precedence over channel. A single value (?channels=SMS) is accepted as well as the repeated (?channels=SMS&channels=MMS) and bracketed (?channels[]=SMS) forms.

Maximum array length: 50

Communication channel used for the message

Available options:
EMAIL,
SMS,
MMS,
VOICE
direction
enum<string>

Filter messages by direction (inbound or outbound)

Available options:
INBOUND,
OUTBOUND
status
enum<string>

Filter messages by delivery status

Available options:
QUEUED,
SENT,
DELIVERED,
FAILED,
BOUNCED,
BLOCKED,
PENDING_APPROVAL
dateRange
object

Filter messages within a date range

inboxId
string

Filter to one inbox — messages delivered to it (inbound) or sent from it (outbound). The precise way to read a single mailbox when an agent owns several.

Pattern: ^[cC][^\s-]{8,}$
fromAddress
string

Filter by sender address, matched exactly (case-sensitive). On inbound mail this is the counterparty; on outbound it is the agent identity the mail was sent from.

toAddress
string

Filter by recipient address, matched exactly (case-sensitive). Note that outbound messages store every recipient in one comma-joined value, so an exact filter matches a multi-recipient send only when given that same joined string — prefer inboxId to scope outbound mail to a mailbox.

labels
string[]

Filter to messages carrying ALL of these labels (e.g. urgent + unread means urgent AND still unread). Case-insensitive. System labels: unread, read, archived, spam.

Maximum array length: 50
Required string length: 1 - 64
includeSpam
boolean
default:false

Include messages classified as spam on arrival. They are excluded by default. Naming spam in labels also counts as asking for it, so a deliberate spam query is never silently emptied by this default.

includeArchived
boolean
default:false

Include messages carrying the archived label. They are excluded by default, so archiving actually removes mail from a listing rather than only tagging it. Naming archived in labels also counts as asking for it (and returns ONLY archived mail); use this flag instead to see archived mail mixed in with the rest.

deleted
enum<string>
default:exclude

How to treat messages moved to Trash. exclude (default) hides them, so deleted mail disappears from every ordinary listing. only returns nothing but Trash. include ignores the distinction. Deletion is reversible — see DELETE /messages/{id} and POST /messages/{id}/restore.

Available options:
exclude,
include,
only

Response

200 - application/json

OK

Paginated list of messages

items
object[]
required

Array of message resources matching the query

pagination
object
required

Pagination metadata for retrieving additional pages