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

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.

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

Request Body

application/json
  1. body
flagLabel?string

The 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.

Length1 <= length
flagsClear?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?unknown
orphans?string

What 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.

Value in"expunge""archive"

Response Body

Updated 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

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?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
curl -X PATCH 'https://api.open.email/api/v1/mailboxes/string/messages/string' \
  -H 'Content-Type: application/json' \
  -d '{
  "flagsSet": [
    "seen"
  ]
}'
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",
    "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
    }
  ]
}