# labels.deleteById

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.

```ts
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](/docs/api/labels/delete_LabelDeleteById) in the API reference.

## Example

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

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |
| `labelId` | `number` | The label's numeric `id`, as `GET /labels` and `POST /labels` report it. The path's `{labelId}`. |

## Options

The last argument, `options`, a `LabelsDeleteByIdOptions`, 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](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`LabelDeleteResult`](/docs/sdks/typescript/types/label-delete-result). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.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`](/docs/sdks/typescript/errors): 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`](/docs/sdks/typescript/types/label-delete-result).
