Skip to Content
GET
/api/v1/mailboxes/{mailboxId}/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.

Authorization

bearerAuth
headerAuthorizationBearer <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: [].

Path Parameters

mailboxId*string

Mailbox ULID identifier

Query Parameters

label?string

Filter 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?string

Pagination cursor from previous page

limit?integer

Maximum threads to return per page (max 100)

Range1 <= value <= 100
order?string

Listing 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

Value in"asc""desc"
sortBy?string

Sort 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

Value in"arrival""date"
hasFlags?string

Comma-separated flag names; a message matches only if ALL are set (e.g. flagged)

notFlags?string

Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)

Response Body

List of conversation threads

application/json
  1. response
nextCursor?string

Opaque cursor for the next page; absent on the last page

threads*array<>
Example Request
curl -X GET 'https://api.open.email/api/v1/mailboxes/string/threads'
Example Response
{
  "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
    }
  ]
}