<Intro>

<EndpointHeader />

<Description>

Returns a paginated list of conversations across the workspace's mailboxes, most recently active first. `label` selects the view: the inbox (the default when omitted), `archive`, `spam`, `blocked`, or any custom label. Filter by mailbox, linked contact, or last-activity time, or pass `q` to full-text search conversations by their messages' subject and text. Conversations whose every message has been trashed are omitted; restoring a message returns its conversation to the list. `before` and `after` filter by time; to page through results pass the response cursors back as `starting_after` or `ending_before`.

</Description>

</Intro>

<Parameters in="query">

<Parameter name="mailbox_id" type="string">

<Description>

Filter to conversations in a specific mailbox.

</Description>

</Parameter>

<Parameter name="contact_id" type="string">

<Description>

Filter to conversations linked to a specific contact.

</Description>

</Parameter>

<Parameter name="label" type="array">

<Description>

Filter to conversations carrying this label. Repeat the parameter to require several — only conversations carrying every listed label match. A placement label selects a folder (`inbox`, `archive`, `spam`, `blocked`); a custom label matches conversations in any folder. Defaults to `inbox` when omitted.

</Description>

</Parameter>

<Parameter name="has_unread" type="boolean">

<Description>

When `true`, only conversations with unread messages are returned. This filters on the conversation's unread state, so it combines with `label` — for example, unread conversations in the archive. (The `unread` label itself lives on messages, not conversations.)

</Description>

</Parameter>

<Parameter name="participant" type="string">

<Description>

Conversations involving this address — matches the sender or any recipient, as a case-insensitive contains-match, so a full address or any fragment of one works.

</Description>

</Parameter>

<Parameter name="subject" type="string">

<Description>

Conversations whose subject contains this text (case-insensitive).

</Description>

</Parameter>

<Parameter name="after" type="string">

<Description>

Filter to conversations whose most recent message is at or after this time. This is a time filter, not a cursor.

</Description>

</Parameter>

<Parameter name="before" type="string">

<Description>

Filter to conversations whose most recent message is at or before this time. This is a time filter, not a cursor.

</Description>

</Parameter>

<Parameter name="limit" type="integer">

<Description>

Maximum number of items to return per page.

</Description>

</Parameter>

<Parameter name="starting_after" type="string">

<Description>

Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.

</Description>

</Parameter>

<Parameter name="ending_before" type="string">

<Description>

Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="data" type="array of object" required>

<FieldChildren kind="response">

<Field name="id" type="string" prefix="data." required>

<Description>

Thread ID.

</Description>

</Field>

<Field name="mailbox_id" type="string" prefix="data." required>

<Description>

Mailbox this conversation belongs to.

</Description>

</Field>

<Field name="channel" type="string" prefix="data." required>

<Description>

Channel this conversation lives on. Always `email`.

</Description>

</Field>

<Field name="contact_id" type="nullable string" prefix="data." required>

<Description>

Contact linked to this conversation, or null when none is linked.

</Description>

</Field>

<Field name="subject" type="nullable string" prefix="data." required>

<Description>

Subject of the conversation, taken from its first message. Null when that message had no subject.

</Description>

</Field>

<Field name="participants" type="array of string" prefix="data." required>

<Description>

Addresses that appear on the retained messages in this conversation, including the mailbox's own address.

</Description>

</Field>

<Field name="message_count" type="integer" prefix="data." required>

<Description>

Number of retained messages in this conversation, both directions.

</Description>

</Field>

<Field name="unread_count" type="integer" prefix="data." required>

<Description>

Number of retained received messages that are still unread. Spam and blocked mail is not counted.

</Description>

</Field>

<Field name="last_message_at" type="string" prefix="data." required>

<Description>

When the most recent retained message in this conversation was received or sent.

</Description>

</Field>

<Field name="last_direction" type="string" prefix="data." required>

<Description>

Direction of the most recent message — `inbound` for a received message, `outbound` for a sent one.

</Description>

<Description>

Possible values: `inbound`, `outbound`

</Description>

</Field>

<Field name="labels" type="array of string" prefix="data." required>

<Description>

Labels on this conversation. Exactly one system placement label is always present — `inbox`, `archive` (filed away, done for now), `spam` (the opening message failed sender authentication), or `blocked` (rejected by the mailbox's receive policy or rules) — set by the message that started the conversation. Move a conversation by updating its labels: add `spam` to file it as spam, add `archive` to clean it out of the inbox, and add `inbox` — or remove `spam`, `blocked`, or `archive` — to bring it back. An archived conversation returns to the inbox by itself when a new message arrives. Custom labels share the same list; a conversation carries at most 20.

</Description>

</Field>

<Field name="created_at" type="string" prefix="data." required>

<Description>

When the thread was created.

</Description>

</Field>

<Field name="updated_at" type="string" prefix="data." required>

<Description>

When the thread last changed.

</Description>

</Field>

<Field name="highlights" type="object" prefix="data.">

<Description>

Matched search fragments, keyed by the field that matched. Returned only by thread search; omitted when listing threads.

</Description>

<FieldChildren kind="response">

<Field name="subject" type="array of string" prefix="data.highlights.">

<Description>

Matched fragments from the conversation's subject.

</Description>

</Field>

<Field name="text" type="array of string" prefix="data.highlights.">

<Description>

Matched fragments from a message's body text.

</Description>

</Field>

</FieldChildren>

</Field>

</FieldChildren>

</Field>

<Field name="next_cursor" type="nullable string" required>

<Description>

Cursor for the next page. Pass back as `starting_after` to advance forward. Null when no next page exists.

</Description>

</Field>

<Field name="prev_cursor" type="nullable string" required>

<Description>

Cursor for the previous page. Pass back as `ending_before` to step backward. Null when no previous page exists.

</Description>

</Field>

<Field name="refresh_cursor" type="nullable string" required>

<Description>

Refresh anchor. Pass back as `ending_before` later to fetch items that have appeared since this response. Non-null whenever `data` is non-empty; null only on an empty page. Distinct from `prev_cursor`.

</Description>

</Field>

</Payload>