Update message flags and labels
Updates message flags, adds or removes labels, and modifies custom keywords. Removing a message's LAST label expunges it to the Recently-deleted tier (restorable until purgeAfter) — it does not attach the Trash label. A label write that leaves the message carrying only Trash is a delete: its previous filing is recorded as restoresTo, and POST /messages/untrash reverses it. One that leaves it carrying only Junk is a spam report, recorded the same way and reversed by POST /messages/unjunk.
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
application/json- body
flagLabel?stringThe label (IMAP mailbox) the client had selected. When present, deleted in flagsSet/flagsClear marks the message's membership in THAT label only, leaves the message-wide bit untouched, and every other flag in the same patch keeps its message-wide meaning. Label-scoped listings (/labels/{label}/uids, /labels/{label}/messages, the label-filtered search) report this per-membership bit, deletedCount counts it, and POST /labels/{label}/expunge detaches exactly the memberships carrying it. A label the message is not filed in answers not_in_label with nothing written. Requires deleted in one of the two flag lists (validation_failed otherwise). Without flagLabel, deleted means every folder: the message-wide bit (JMAP's visibility rule; JMAP has no \Deleted) and every membership move together. A scoped clear that unmarks the last marked membership clears the message-wide bit as well.
1 <= lengthflagsClear?array<>Flags to remove
flagsSet?array<>Flags to set
keywordsClear?array<string>Custom keywords to remove
keywordsExact?array<string>Exact replacement list of custom keywords
keywordsSet?array<string>Custom keywords to add
labelsAdd?array<string>Labels to add
labelsExact?array<string>Exact replacement list of labels
labelsRemove?array<string>Labels to remove
mime?unknownorphans?stringWhat to do if this write would leave the message with no label. 'expunge' (the default) sends the message to Recently deleted. 'archive' keeps the message live by attaching the Archive system label (attaching Archive needs no right beyond the grant's 't' for a scoped viewer). If the write removes Archive itself and would leave no labels, Archive is kept without error. A SCOPED viewer whose write lands the message in Archive has moved it out of their own scope: the answer is still updated, and the hydrated message carries an EMPTY labels list rather than naming a label the grant never included. labelsAdded omits Archive for the same reason.
"expunge""archive"Updated 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
labelsAdded?array<string>Labels this write attached, including an Archive fallback under orphans
labelsRemoved?array<string>Labels this write detached
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 PATCH 'https://api.open.email/api/v1/mailboxes/string/messages/string' \
-H 'Content-Type: application/json' \
-d '{
"flagsSet": [
"seen"
]
}'{
"auth": null,
"bcc": null,
"blobGen": "g1",
"blobHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"cc": [],
"deliveryMeta": null,
"deliveryState": null,
"envelopeFrom": "ada@example.com",
"envelopeTo": "grace@acme.example",
"flags": [
"seen",
"flagged"
],
"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
}
]
}