# 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.

## `DELETE /api/v1/mailboxes/{mailboxId}/labels/{label}`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier
- `label` (string, required) — Label or folder name (e.g. INBOX, Archive, custom)

### Query parameters

- `orphans` ("expunge" | "archive") — 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

### Responses

**200** — Deletion outcome

`application/json` → LabelDeleteResult

- `deleted` (true, required)
- `archived` (integer) — Messages left with no other label that fell back to the Archive label

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**403** — System labels cannot be deleted

`application/json` → ErrorBody

**404** — Mailbox or label not found

`application/json` → ErrorBody

**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

`application/json` → ErrorBody

**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)

`application/json` → ErrorBody

### Example request

```bash
curl -X DELETE 'https://api.open.email/api/v1/mailboxes/{mailboxId}/labels/{label}' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.labels.delete`](/docs/sdks/typescript/labels/delete)

```ts
const labelDeleteResult = await openemail.labels.delete(mailboxId, label)
```
