Get message metadata
Returns metadata for a specific message including subject, sender/recipients, labels, flags, UIDs, and timestamps.
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
messageId*stringMessage ULID identifier
Message metadata
application/json- 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*stringStorage generation identifier
blobHash*stringSHA-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*stringSMTP envelope sender address
envelopeTo*stringSMTP 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*stringUnique 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?integerPer-label MODSEQ (present in label UID listings)
int64receivedAt*integerTimestamp when message was received by server in epoch seconds
int64referencesIds*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
int64size*integerTotal message size in bytes
int64snippet*|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?integerPer-label UID (present in label UID listings)
int64curl -X GET 'https://api.open.email/api/v1/mailboxes/string/messages/string'{
"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
}
]
}Empty trash, or delete a batch of messages or… DELETE
Permanently purges every row on the Recently-deleted tier with state=expunged, or deletes the messages named by `ids` and/or the conversations named by…
Update message flags and labels PATCH
Updates message flags, adds or removes labels, and modifies custom keywords. Removing a message's LAST label expunges it to the Recently-deleted tier…