Skip to Content

Update flags and labels for multiple messages or whole conversations.

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.

openemail.messages.updateMany(
  mailboxId: string,
  body?: MessagesUpdateManyBody,
  options?: CallOptions,
): ApiPromise<BatchUpdateResult>

It calls PATCH /mailboxes/{mailboxId}/messages: Update flags and labels for multiple messages or whole conversations in the API reference.

Example

const batchUpdateResult = await openemail.messages.updateMany(mailboxId, {})

Arguments

ArgumentTypeDescription
mailboxIdstringMailbox ULID identifier. The path's {mailboxId}.
bodyMessagesUpdateManyBodyOptional. The request's body.

Options

It takes no options of its own. Every call also takes signal, timeout, retry and headers, which say how that one call is sent (call options).

Answer

Awaited, it is the API's JSON, BatchUpdateResult. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Errors

StatusWhat it means
400validation_failed (including flagLabel without deleted in either flag list, malformed ifInLabel, or ifInLabel with threadIds), invalid label/keyword, target_required (neither ids nor threadIds given), thread_context_required (threadLabelOnly without threadLabel), or thread_too_large
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
404Mailbox not found or not accessible to this principal
413too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing
503temporary_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)

A failed call rejects with a RequestError: its status, and its code, the API's error. Decide on the code: one status covers several.

Types

MessagesUpdateManyBody

/** The body of `messages.updateMany`. */
type MessagesUpdateManyBody = {
  /** 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. */
  flagLabel?: string
  /** Flags to remove */
  flagsClear?: ('seen' | 'answered' | 'flagged' | 'draft' | 'deleted')[]
  /** Flags to set */
  flagsSet?: ('seen' | 'answered' | 'flagged' | 'draft' | 'deleted')[]
  /** Array of message IDs to update */
  ids?: string[]
  /** 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. */
  ifInLabel?: MessagesUpdateManyBodyIfInLabel
  /** Custom keywords to remove */
  keywordsClear?: string[]
  /** Exact replacement list of custom keywords */
  keywordsExact?: string[]
  /** Custom keywords to add */
  keywordsSet?: string[]
  /** Label context for unchangedSince check */
  label?: string
  /** Labels to add */
  labelsAdd?: string[]
  /** Exact replacement list of labels */
  labelsExact?: string[]
  /** Labels to remove */
  labelsRemove?: 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. */
  orphans?: ('expunge' | 'archive')
  /** 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. */
  threadExcludeRoles?: ('inbox' | 'sent' | 'drafts' | 'trash' | 'archive' | 'junk')[]
  /** 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. */
  threadIds?: 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. */
  threadLabel?: string
  /** 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. */
  threadLabelOnly?: boolean
  /** Conditional update precondition: update only if modseq <= unchangedSince */
  unchangedSince?: number
}

MessagesUpdateManyBodyIfInLabel

/** 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. */
type MessagesUpdateManyBodyIfInLabel = {
  label: string
  uidValidity: number
  uids: Record<string, number>
  /** Optional per-ID modseq ceilings in this label (at most 200 entries). A newer membership answers modified with its currentModseq; a missing entry answers not_in_label. Zero refuses every existing membership. Checked in addition to the top-level unchangedSince, if supplied. */
  unchangedSince?: Record<string, number>
}

It names these types of the API, each on a page of its own: BatchUpdateResult.