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

## `PATCH /api/v1/mailboxes/{mailboxId}/messages/{messageId}`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier
- `messageId` (string, required) — Message ULID identifier

### Request body (optional)

`application/json`

- `flagLabel` (string, min 1 chars) — 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.
- `flagsClear` ("seen" | "answered" | "flagged" | "draft" | "deleted"[]) — Flags to remove
- `flagsSet` ("seen" | "answered" | "flagged" | "draft" | "deleted"[]) — Flags to set
- `keywordsClear` (string[]) — Custom keywords to remove
- `keywordsExact` (string[]) — Exact replacement list of custom keywords
- `keywordsSet` (string[]) — Custom keywords to add
- `labelsAdd` (string[]) — Labels to add
- `labelsExact` (string[]) — Exact replacement list of labels
- `labelsRemove` (string[]) — Labels to remove
- `mime` (object)
- `orphans` ("expunge" | "archive") — 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.

### Responses

**200** — Updated message metadata

`application/json` → MessageUpdateResult

- _option 1: MessageUpdated_
  - `auth` (MessageAuth, required) — 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.
    - `arc` (string | null, required) — ARC verdict, or null
    - `dkim` (string | null, required) — DKIM verdict, or null
    - `dmarc` (string | null, required) — DMARC verdict, or null
    - `junk` (boolean | null, required) — The inbound spam verdict (X-OpenEmail-Junk), or null when none was stamped
    - `spf` (string | null, required) — SPF verdict (pass/fail/softfail/none/...), or null
  - `bcc` (array | null, required) — Parsed Bcc header addresses for composed drafts, or null
  - `blobGen` (string, required) — Storage generation identifier
  - `blobHash` (string, required) — SHA-256 hash of raw MIME content in storage
  - `cc` (array | null, required) — Parsed Cc header addresses, or null if unparseable
  - `deliveryMeta` (object | null, required) — Inbound delivery audit metadata
  - `deliveryState` ("queued" | "relayed" | "delivered" | "failed" | "mixed" | null, required) — 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.
    - _option 1: "queued" | "relayed" | "delivered" | "failed" | "mixed"_
    - _option 2: null_
    - _option 3: null_
  - `envelopeFrom` (string, required) — SMTP envelope sender address
  - `envelopeTo` (string, required) — SMTP envelope recipient address
  - `flags` (string[], required) — System flags (seen, answered, flagged, draft, deleted)
  - `from` (array | null, required) — Parsed From header addresses, or null if unparseable
  - `hasAttachment` (boolean | null, required) — True if message has file attachments, null if not yet determined
  - `id` (string, required) — Unique message identifier (ULID)
  - `inReplyTo` (string | null, required) — In-Reply-To header Message-ID, or null
  - `keywords` (string[], required) — Custom JMAP keywords (e.g. $forwarded)
  - `labels` (MessageLabel[], required) — Labels attached to this message with per-label UIDs
    - `deleted` (boolean, required) — This membership's IMAP \Deleted mark (set with `flagLabel` on PATCH, acted on by POST /labels/{label}/expunge). Always present; false when unmarked. Per label, so the same message can be marked in one folder and clean in another
    - `modseq` (integer <int64>, required) — RFC 7162 MODSEQ change sequence number
    - `name` (string, required) — Label name
    - `uid` (integer <int64>, required) — Message UID inside this label
    - `uidValidity` (integer <int64>, required) — UID validity epoch of the label
  - `messageIdHeader` (string | null, required) — Message-ID header value, or null
  - `receivedAt` (integer <int64>, required) — Timestamp when message was received by server in epoch seconds
  - `referencesIds` (string[], required) — List of Message-IDs from References header
  - `sentAt` (integer | null, required) — Sent timestamp from Date header in epoch seconds, or null
  - `size` (integer <int64>, required) — Total message size in bytes
  - `snippet` (string | null, required) — Short plain-text preview of message body
  - `subject` (string | null, required) — Message subject line, or null
  - `threadId` (string | null, required) — Conversation thread identifier (ULID), or null
  - `to` (array | null, required) — Parsed To header addresses, or null if unparseable
  - `labelsAdded` (string[]) — Labels this write attached, including an Archive fallback under `orphans`
  - `labelsRemoved` (string[]) — Labels this write detached
  - `modseq` (integer <int64>) — Per-label MODSEQ (present in label UID listings)
  - `restoresTo` (array | null) — 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.
  - `uid` (integer <int64>) — Per-label UID (present in label UID listings)
- _option 2: ExpungeNotice_
  - `expunged` (boolean, required) — True if the message was expunged (Recently deleted tier)
  - `expungedAt` (integer <int64>, required) — Timestamp when the message was expunged, in epoch seconds
  - `purgeAfter` (integer <int64>, required) — Timestamp when permanent wipe will occur in epoch seconds

**400** — validation_failed (including flagLabel without `deleted` in either flag list) or invalid label/keyword name

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Mailbox or message not found

`application/json` → ErrorBody

**409** — not_in_label — flagLabel names a label the message is not filed in; nothing written

`application/json` → ErrorBody

**413** — too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X PATCH 'https://api.open.email/api/v1/mailboxes/{mailboxId}/messages/{messageId}' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## TypeScript SDK

[`openemail.messages.update`](/docs/sdks/typescript/messages/update)

```ts
const messageUpdateResult = await openemail.messages.update(mailboxId, messageId, {})
```
