labels.update
Rename a label or update folder settings.
Renames a custom label and/or updates its display sort order, subscription state, and color. System labels cannot be renamed, but their sortOrder, isSubscribed, and color settings can still be updated.
withChildren: true carries every Old/… sub-label with the rename, in one commit that is validated whole before it writes — so the tree cannot be left half-renamed. Filter rules naming any moved label follow it, and so do pickup sources that deliver into one. Raw user Sieve scripts are NOT rewritten.
openemail.labels.update(
mailboxId: string,
label: string,
body: LabelsUpdateBody,
options?: CallOptions,
): ApiPromise<RenamedResult>It calls PATCH /mailboxes/{mailboxId}/labels/{label}: Rename a label or update folder settings in the API reference.
Example
const renamedResult = await openemail.labels.update(mailboxId, label, {})Arguments
| Argument | Type | Description |
|---|---|---|
mailboxId | string | Mailbox ULID identifier. The path's {mailboxId}. |
label | string | Label or folder name (e.g. INBOX, Archive, custom). The path's {label}. |
body | LabelsUpdateBody | 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, RenamedResult. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.
Errors
| Status | What it means |
|---|---|
400 | validation_failed — malformed name/sortOrder or empty patch |
401 | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge |
403 | System labels cannot be renamed |
404 | Mailbox or label not found |
409 | Target label name already exists |
413 | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
503 | temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After |
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
LabelsUpdateBody
/** The body of `labels.update`. */
type LabelsUpdateBody = {
/** Hex color code for the label badge/chip, or null to clear */
color?: string | null
/** Whether folder is subscribed for client sync */
isSubscribed?: boolean
/** New label name (custom labels only). May not start with `*` */
name?: string
/** Presentation display sort order index */
sortOrder?: number
/** With `name`, carry every `Old/…` sub-label along in the same commit. The whole move is validated before any of it is written, so it cannot half-apply. Default false, which leaves sub-labels under their old prefix. */
withChildren?: boolean
}It names these types of the API, each on a page of its own: RenamedResult.