List mailbox messages
Lists messages newest-first (or oldest-first with order=asc) with cursor pagination, optionally filtered to one label. sortBy=date orders by the Date header instead of arrival time. Set state=expunged to list trash/restorable messages. For UID-ordered listing use GET /mailboxes/:id/labels/:label/messages.
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?stringOnly messages carrying this label (folder)
excludeRoles?array<>System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.
cursor?stringOpaque page cursor from a previous response using the same sortBy. Arrival cursors must be canonical uppercase ULIDs; the cursor message need not still exist.
limit?integerPage size (max 200)
1 <= value <= 200hasFlags?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)
order?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"state?stringlive (default): ordinary listing, including messages on the Trash LABEL. expunged: the Recently-deleted TIER — a different place, whose rows have no labels at all and are purged after purgeAfter — carrying expungedAt/purgeAfter, the labels held at expunge, and restoresTo
"live""expunged"Messages page (live rows, or trash rows when state=expunged)
application/json- response
messages*array<>nextCursor?stringOpaque cursor for the next page; absent on the last page
curl -X GET 'https://api.open.email/api/v1/mailboxes/string/messages'{
"messages": [
{
"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
}
]
}
],
"nextCursor": "MTc4ODA4MTMwMC4wMUo5TVNHQThDMkU1SDFLNE0"
}Messages
The store: list/read (parsed content, raw MIME, individual parts), flags/labels/keywords updates, batch operations, trash and restore, incremental sync…
Update flags and labels for multiple messages… PATCH
Applies flag, label, and keyword updates across multiple messages in a single atomic operation. Name the targets by `ids`, by `threadIds`, or both: `threadIds`…