Skip to main content
GET
cURL

Authorizations

Authorization
string
header
required

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

Query Parameters

channel
enum<string>
default:EMAIL

Channel to list conversations for. EMAIL is currently the only supported value — SMS/MMS conversations are listed by GET /sms/threads, which models them as a phone-number pair rather than a reply chain.

Available options:
EMAIL
agentId
string

Filter conversations to one agent. Optional for master keys (omit for every agent in the org); ignored for agent keys, which always see only their own.

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

Filter conversations to one inbox — the precise way to read a single mailbox.

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

Only conversations containing a message in this direction. OUTBOUND is a Sent view. Note that the returned counts then describe the MATCHING messages, not the thread's full length.

Available options:
INBOUND,
OUTBOUND
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
limit
integer
default:20

Maximum conversations to return per page (1–100, default 20)

Required range: 1 <= x <= 100
offset
integer
default:0

Conversations to skip, for paging through the list

Required range: x >= 0

Response

200 - application/json

OK

Paginated list of email conversations

items
object[]
required

Conversation summaries, most recent activity first

total
integer
required

Total conversations matching the query

hasMore
boolean
required

Whether more conversations exist past this page