Skip to Content

List a mailbox's messages and read one back as structured content.

Messages live inside a mailbox. Listing them gives you metadata and a snippet; reading one gives you decoded headers, bodies, and attachment references.

Paths are relative to https://api.open.email/api/v1, and every request carries a bearer credential — see Authentication.

List messages

GET /mailboxes/{mailboxId}/messages

curl "$API/mailboxes/$MAILBOX_ID/messages?limit=25" \
  -H "Authorization: Bearer $TOKEN"

Newest first by default, with cursor pagination. You can restrict to one label, filter on flags, and switch state to expunged to list the trash instead.

Hold order constant across a crawl. Cursors do not encode direction, so reusing one under the opposite order silently yields a differently-windowed page rather than an error.

{
  "messages": [
    {
      "id": "msg_...",
      "subject": "Hello from OpenEmail",
      "snippet": "Sent over HTTP.",
      "labels": [{ "name": "INBOX", "uid": 1, "uidValidity": 1 }],
      "receivedAt": 1786000000,
      "threadId": "thr_...",
      "uid": 1
    }
  ],
  "nextCursor": "..."
}

receivedAt and sentAt are Unix timestamps. Each entry in labels carries its own uid — labels are how OpenEmail models folders, and IMAP requires a per-folder UID.

Read a message

GET /mailboxes/{mailboxId}/messages/{messageId}/content

curl "$API/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID/content" \
  -H "Authorization: Bearer $TOKEN"

Returns the message decoded and structured — you do not have to parse MIME yourself:

{
  "headers": {
    "from": [{ "email": "you@example.com", "name": null }],
    "subject": "Hello from OpenEmail",
    "date": 1786000000
  },
  "text": "Sent over HTTP.",
  "html": null,
  "attachments": []
}

Attachments come back as references, not bytes. Each carries a section — the MIME part identifier you pass to the message parts endpoint to stream it — plus the filename, content type and size the sender declared. One field is easy to miss: degraded marks a part whose metadata could not be read in full, so treat its filename and size as unreliable rather than absent.

Two failures are terminal for a given message, and worth handling as such rather than retrying: 413 message_too_large when the blob exceeds the parse ceiling, and 422 unparseable_message or message_too_complex. The content endpoint will not succeed on a later attempt for either. Fall back to streaming the raw MIME blob instead.

The endpoint also honours If-None-Match against the content ETag, so a poller can take a 304 instead of the body.

In the TypeScript SDK

Each call above is a method of the TypeScript SDK: