Skip to Content

Delete a custom label, by id.

Keyed on the label's numeric id — as GET /labels and POST /labels report it — rather than on its name. The id survives a rename (it is what JMAP Mailbox/set and folder-scoped shares key on), so a client that renames folders should hold it: the by-name route's key changes as the operation succeeds. It also never contains a /, so a folder name that does need not be encoded into a path segment. Otherwise identical to the by-name operation.

Deletes a custom label. Messages carrying this label will retain any other labels they have. Messages with no other labels are expunged (moved to Recently deleted) by default, or moved to Archive when ?orphans=archive is passed.

Folder-scoped shares follow the folder into deletion: the folder is removed from every grant that names it, and a grant left naming no folders is revoked outright — the person it was shared with stops seeing the mailbox at once, exactly as if the grant had been DELETEd. Whole-mailbox grants are unaffected.

openemail.labels.deleteById(
  mailboxId: string,
  labelId: number,
  options?: LabelsDeleteByIdOptions,
): ApiPromise<LabelDeleteResult>

It calls DELETE /mailboxes/{mailboxId}/labels/by-id/{labelId}: Delete a custom label, by id in the API reference.

Example

const labelDeleteResult = await openemail.labels.deleteById(mailboxId, labelId)

Arguments

ArgumentTypeDescription
mailboxIdstringMailbox ULID identifier. The path's {mailboxId}.
labelIdnumberThe label's numeric id, as GET /labels and POST /labels report it. The path's {labelId}.

Options

The last argument, options, a LabelsDeleteByIdOptions, takes:

OptionTypeSent asDescription
orphans('expunge' | 'archive')query orphansWhat to do if deleting this label leaves a message with no labels. expunge (default) moves it to the Recently-deleted tier; archive attaches the Archive label instead

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, LabelDeleteResult. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Errors

StatusWhat it means
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
403System labels cannot be deleted
404Mailbox or label not found
409folder_shared — folder-scoped grants name this label, so deleting it would revoke them, which is the a right: use a full-scope credential, or remove the grants first
503too_large — the label refilled past the one-commit ceiling while it was being drained; retry. Or 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)

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

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