Skip to Content
GET
/api/v1/mailboxes/{mailboxId}/messages/{messageId}

Returns metadata for a specific message including subject, sender/recipients, labels, flags, UIDs, and timestamps.

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

messageId*string

Message ULID identifier

Response Body

Message metadata

application/json
  1. response
auth*|

Stored SMTP authentication and original inbound junk verdicts. Missing verdicts are null; the object is null when none were recorded (including APPEND and local Sent copies). Junk does not follow later label changes.

bcc*array<>|

Parsed Bcc header addresses for composed drafts, or null

blobGen*string

Storage generation identifier

blobHash*string

SHA-256 hash of raw MIME content in storage

cc*array<>|

Parsed Cc header addresses, or null if unparseable

deliveryMeta*|

Inbound delivery audit metadata

deliveryState*|||

What became of this message after it was SENT, for a message this mailbox sent: 'queued' (handed to the relay), 'relayed' (the receiving mail system accepted it — never 'read'), 'delivered' (committed to a local mailbox), 'failed', or 'mixed' (some recipients failed, others did not). Null for received mail, and for sent mail whose delivery record has aged out — render null as no indicator, never as a state. Per-recipient detail and the SMTP reply behind a failure are at /messages/{messageId}/delivery.

envelopeFrom*string

SMTP envelope sender address

envelopeTo*string

SMTP envelope recipient address

flags*array<string>

System flags (seen, answered, flagged, draft, deleted)

from*array<>|

Parsed From header addresses, or null if unparseable

hasAttachment*|

True if message has file attachments, null if not yet determined

id*string

Unique message identifier (ULID)

inReplyTo*|

In-Reply-To header Message-ID, or null

keywords*array<string>

Custom JMAP keywords (e.g. $forwarded)

labels*array<>

Labels attached to this message with per-label UIDs

messageIdHeader*|

Message-ID header value, or null

modseq?integer

Per-label MODSEQ (present in label UID listings)

Formatint64
receivedAt*integer

Timestamp when message was received by server in epoch seconds

Formatint64
referencesIds*array<string>

List of Message-IDs from References header

restoresTo?array<string>|

Where a recovery would file this message, as label names. Present only when the message is recoverable: one carrying the Trash label (POST /messages/untrash), one carrying the Junk label with a recorded origin (POST /messages/unjunk), or one on the expunged tier (POST /messages/restore). A message in both Trash and Junk's records answers for Trash, the verb a client offers it first. Null otherwise, meaning the message is filed rather than recoverable. This is the effective destination including the Inbox fallback, not a raw snapshot, so a client can name it on a Put back or Not spam control without reimplementing the rule.

sentAt*|

Sent timestamp from Date header in epoch seconds, or null

Formatint64
size*integer

Total message size in bytes

Formatint64
snippet*|

Short plain-text preview of message body

subject*|

Message subject line, or null

threadId*|

Conversation thread identifier (ULID), or null

to*array<>|

Parsed To header addresses, or null if unparseable

uid?integer

Per-label UID (present in label UID listings)

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