List conversation threads
Returns conversation threads, newest activity first, one row per conversation: participants, message and unread counts, and an exemplar message carrying the subject and snippet a row renders. Grouping is by REPLY CHAIN (In-Reply-To/References), never by subject — two unrelated messages sharing a subject are two conversations, and a renamed reply stays in the one it answers. Filtering by label and by unread/starred flags uses Gmail semantics: a conversation matches when ANY of its live members does, and the counts then span the whole conversation — but the exemplar is the newest member that MATCHED, so a label-filtered row is faced with the message that folder actually holds. See ThreadListItem.exemplar. Trash and Junk are HIDDEN ROLES: outside their own views a conversation is its live members carrying neither label — they do not qualify a row, are not counted, faced or listed in participants/labels. label=Trash lists conversations by their trashed members and label=Junk by their junked ones; a member in both is in the bin (shown in Trash, hidden in Junk). excludeRoles adds to that rule and never lifts it.
bearerAuthAuthorizationBearer <token>Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.
oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.
oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.
Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].
mailboxId*stringMailbox ULID identifier
label?stringFilter threads containing messages with this label (e.g. INBOX)
excludeRoles?array<>System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.
cursor?stringPagination cursor from previous page
limit?integerMaximum threads to return per page (max 100)
1 <= value <= 100order?stringListing direction: desc (default) = newest first, asc = oldest first. Hold it constant across a cursor crawl — cursors do not encode direction, so switching mid-crawl re-windows the page rather than erroring
"asc""desc"sortBy?stringSort key: arrival (default) = the order mail reached this mailbox (message id); date = the Date header, falling back to arrival where it is absent or unparseable (RFC 5256 SORT DATE). Cursors follow the key, so hold it constant across a crawl — unlike order, a mismatched cursor is refused with 400 invalid_cursor rather than silently re-windowing. Note that under arrival an imported message (APPEND with ?internaldate=) lists where it was imported, not at its receivedAt; date orders imported mail by its own header
"arrival""date"hasFlags?stringComma-separated flag names; a message matches only if ALL are set (e.g. flagged)
notFlags?stringComma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)
List of conversation threads
application/json- response
nextCursor?stringOpaque cursor for the next page; absent on the last page
threads*array<>curl -X GET 'https://api.open.email/api/v1/mailboxes/string/threads'{
"threads": [
{
"exemplar": {
"auth": null,
"bcc": null,
"blobGen": "g1",
"blobHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"cc": [],
"deliveryMeta": null,
"deliveryState": null,
"envelopeFrom": "ada@example.com",
"envelopeTo": "grace@acme.example",
"flags": [
"seen"
],
"from": [
{
"email": "ada@example.com",
"name": "Ada Lovelace"
}
],
"hasAttachment": true,
"id": "01J9MSGA8C2E5H1K4M00000000",
"inReplyTo": null,
"keywords": [],
"labels": [
{
"deleted": false,
"modseq": 91842,
"name": "INBOX",
"uid": 4213,
"uidValidity": 1722470400
}
],
"messageIdHeader": "<7f2a1c9e4b8d@mail.example.com>",
"receivedAt": 1788081300,
"referencesIds": [],
"sentAt": 1788081272,
"size": 48213,
"snippet": "Hi Grace, attached is the Q3 report draft we discussed on Friday…",
"subject": "Q3 report draft",
"threadId": "01J9THRD5E8G1J4M7P00000000",
"to": [
{
"email": "grace@acme.example",
"name": null
}
]
},
"flaggedCount": 0,
"labels": [
"INBOX"
],
"lastReceivedAt": 1788081300,
"messageCount": 3,
"participants": [
{
"email": "ada@example.com",
"name": "Ada Lovelace"
},
{
"email": "grace@acme.example",
"name": "Grace Hopper"
}
],
"threadId": "01J9THRD5E8G1J4M7P00000000",
"unseenCount": 1
}
]
}