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

Applies flag, label, and keyword updates across multiple messages in a single atomic operation. Name the targets by ids, by threadIds, or both: threadIds is expanded to the conversation's members server-side, in the same transaction as the write, so a reply that arrives while the request is in flight is either wholly in the gesture or wholly outside it. That is the difference from expanding it client-side, which also truncates at whatever page of members the client happened to hold. Expansion is the set GET /threads/{threadId} returns: live members in your grant, Trash and Junk excluded. ids may name a trashed, junked or otherwise excluded message directly — the operand chooses targets, it does not restrict them.

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

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

ids?array<string>

Array of message IDs to update

Items1 <= items <= 200
ifInLabel?

Apply each explicit ID only while it has the given UID in this label and UIDVALIDITY epoch. Checked atomically with the write; the identity condition alone permits intervening flag changes. Missing UID entries, absent or replaced memberships, and inaccessible labels answer not_in_label per entry, with nothing written. Cannot be combined with threadIds.

keywordsClear?array<string>

Custom keywords to remove

keywordsExact?array<string>

Exact replacement list of custom keywords

keywordsSet?array<string>

Custom keywords to add

label?string

Label context for unchangedSince check

Length1 <= length
labelsAdd?array<string>

Labels to add

labelsExact?array<string>

Exact replacement list of labels

labelsRemove?array<string>

Labels to remove

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"
threadExcludeRoles?array<>

Roles to exclude from thread expansion (e.g. ['sent', 'drafts']). Members carrying any label with one of these roles are omitted from the expanded conversation. Trash and Junk members are already left out by the default expansion, so naming them here changes nothing unless threadLabel is that folder, where it empties the set. Explicit ids are unaffected. If every member is excluded, the conversation contributes nothing, which is not an error.

threadIds?array<string>

Conversation IDs whose members to update, expanded server-side. A stale ID from before a thread merge resolves transparently, as on GET /threads/{threadId}. Refused with thread_too_large past 1000 expanded messages, rather than acting on some of them.

Items1 <= items <= 50
threadLabel?string

The folder each conversation in threadIds was being viewed in — the same value passed to GET /threads/{threadId}?label=, so the patch reaches exactly the members that view rendered. Omitted, the expansion is the default view: live members in your grant with Trash and Junk excluded. Pass the Trash folder to patch a conversation's trashed members instead, or the Junk folder for its junked ones; the default deliberately leaves both alone. Optional here and REQUIRED on DELETE /messages, where guessing wrong destroys a member the user was not looking at rather than re-filing one they can see.

Length1 <= length
threadLabelOnly?boolean

Narrow each conversation in threadIds to the members FILED UNDER threadLabel, which is then REQUIRED (thread_context_required without it). threadLabel alone is a view, not a filter: a conversation viewed in the Inbox includes the Sent copy of your replies and any member filed elsewhere, so a label patch over it re-files those too. Pass this for FILING gestures (archive, move, junk, delete-to-Trash) so they act on what the folder listing showed; leave it off for flags and keywords, which mean the whole conversation. ids are unaffected.

unchangedSince?integer

Conditional update precondition: update only if modseq <= unchangedSince

Range0 <= value

Response Body

Batch update results per message. An entry answers not_in_label when flagLabel names a label that message is not filed in, or ifInLabel does not match its current accessible membership (nothing written for it)

application/json
  1. response
results*array<>

List of update outcomes for each requested message

Example Request
curl -X PATCH 'https://api.open.email/api/v1/mailboxes/string/messages' \
  -H 'Content-Type: application/json' \
  -d '{}'
Example Response
{
  "results": [
    {
      "currentModseq": 0,
      "expungedAt": 0,
      "id": "string",
      "labelsAdded": [
        "string"
      ],
      "labelsRemoved": [
        "string"
      ],
      "message": {
        "auth": {
          "arc": "string",
          "dkim": "string",
          "dmarc": "string",
          "junk": true,
          "spf": "string"
        },
        "bcc": [
          {
            "email": "string",
            "name": "string"
          }
        ],
        "blobGen": "string",
        "blobHash": "string",
        "cc": [
          {
            "email": "string",
            "name": "string"
          }
        ],
        "deliveryMeta": {
          "property1": null,
          "property2": null
        },
        "deliveryState": "queued",
        "envelopeFrom": "string",
        "envelopeTo": "string",
        "flags": [
          "string"
        ],
        "from": [
          {
            "email": "string",
            "name": "string"
          }
        ],
        "hasAttachment": true,
        "id": "string",
        "inReplyTo": "string",
        "keywords": [
          "string"
        ],
        "labels": [
          {
            "deleted": true,
            "modseq": 0,
            "name": "string",
            "uid": 0,
            "uidValidity": 0
          }
        ],
        "messageIdHeader": "string",
        "modseq": 0,
        "receivedAt": 0,
        "referencesIds": [
          "string"
        ],
        "restoresTo": [
          "string"
        ],
        "sentAt": 0,
        "size": 0,
        "snippet": "string",
        "subject": "string",
        "threadId": "string",
        "to": [
          {
            "email": "string",
            "name": "string"
          }
        ],
        "uid": 0
      },
      "modified": true,
      "modseq": 0,
      "purgeAfter": 0,
      "status": "updated"
    }
  ]
}