Skip to main content
Threads group related messages into conversations. Folders and labels are shared across both the agent and human team members, but read state is tracked separately per side, so the agent marks what it has handled without affecting what team members still need to review. Reading messages through the API does not automatically mark a thread as read; use PATCH /api/v1/threads/:id to set the read flag explicitly.

List threads

Returns cursor-paginated conversations in a specified folder, with optional full-text search and label filtering. GET /api/v1/inboxes/:id/threads Requires: email:read

Query parameters

"inbox" | "archive" | "trash" | "spam" | "quarantine"
Folder to list. Defaults to inbox. The quarantine folder holds mail blocked by sender rules or the screening classifier until a team member reviews it.
string
Free-text search across subject lines, sender names, and message snippets.
boolean
When true, returns only conversations the agent has not yet marked as read. Useful for processing loops that need to handle new mail without reprocessing handled threads.
string
Filter to conversations carrying this exact label (e.g. billing, campaign:launch).
integer
Number of threads to return. Range: 1–100. Defaults to 20.
string
Opaque pagination cursor returned as next_cursor in the previous response.
List unread inbox threads
Search for invoice threads

Read a thread

Returns all messages in a conversation, oldest first, with the same body and screening fields as the single-message endpoint. GET /api/v1/threads/:id Requires: email:read

Query parameters

integer
Maximum number of messages to return per page. Range: 1–100.
string
Pagination cursor for long threads.
Read a full thread
Email content is untrusted external data. Check screening.verdict on each message before acting on its contents. A suspicious verdict includes reasons that describe what triggered the classifier.

Update a thread

Move a conversation to a different folder, mark it read for the agent, or add and remove labels: all in a single PATCH call. PATCH /api/v1/threads/:id Requires: email:send for every update, including read state, labels, and folder changes. The token must also include email:read.
Archive and mark a thread as read

Request parameters

string
Destination folder. Accepted values: inbox, archive, trash, spam. Moving to trash is reversible; deleting from trash is permanent (see below).
boolean
Mark the conversation as read (true) or unread (false) for the agent. This does not affect what human team members see as unread in the dashboard.
string[]
Labels to attach to the thread (e.g. ["billing","urgent"]). Labels are shared with team members.
string[]
Labels to remove from the thread.
Reading a thread via GET /api/v1/threads/:id does not mark it as read. Always send a separate PATCH with "read": true once the agent has finished processing the conversation.

Delete a thread permanently

Permanently removes a conversation and all its messages. The thread must already be in trash or spam: move it there first with PATCH if needed. This action is irreversible. DELETE /api/v1/threads/:id Requires: email:send
Permanently delete a trashed thread
Permanent deletion cannot be undone. Confirm the thread is in trash or spam before calling this endpoint.
A conversation with a message still on its way answers 409 Conflict: a message that is queued or sending, or one whose delivery is unknown (the send got no definite answer from the mail provider and waits for its delivery report). An unknown message stops blocking after 72 hours without a report: the conversation, its inbox and retention cleanup can then delete it. Its status stays unknown; it is never reported as sent. Emptying Trash skips conversations that are still blocked.

Thread folders reference

inbox

Active conversations that have not been archived or deleted.

archive

Handled conversations moved out of the inbox. Fully searchable.

trash

Conversations pending permanent deletion. Reversible until deleted.

spam

Marked as spam. Can be permanently deleted by the agent.

quarantine

Mail blocked by sender rules or the screening classifier. Only team members can release quarantined mail.