labels.delete
Delete a custom label.
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.delete(
mailboxId: string,
label: string,
options?: LabelsDeleteOptions,
): ApiPromise<LabelDeleteResult>It calls DELETE /mailboxes/{mailboxId}/labels/{label}: Delete a custom label in the API reference.
Example
const labelDeleteResult = await openemail.labels.delete(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}. |
Options
The last argument, options, a LabelsDeleteOptions, takes:
| Option | Type | Sent as | Description |
|---|---|---|---|
orphans | ('expunge' | 'archive') | query orphans | What 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
| Status | What it means |
|---|---|
401 | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge |
403 | System labels cannot be deleted |
404 | Mailbox or label not found |
409 | folder_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 |
503 | too_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.