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

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

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

Opaque 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?integer

Page size (max 200)

Range1 <= value <= 200
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)

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"
state?string

live (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

Value in"live""expunged"

Response Body

Messages page (live rows, or trash rows when state=expunged)

application/json
  1. response
messages*array<>
nextCursor?string

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

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