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

## `PATCH /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)

### Request body (required)

`application/json`

- `color` (string | null, pattern `^#[0-9a-f]{6}$`) — Hex color code for the label badge/chip, or null to clear
- `isSubscribed` (boolean) — Whether folder is subscribed for client sync
- `name` (string, 1–255 chars) — New label name (custom labels only). May not start with `*`
- `sortOrder` (integer, ≥ 0, ≤ 2147483647) — Presentation display sort order index
- `withChildren` (boolean) — 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.

### Responses

**200** — Update successful

`application/json` → RenamedResult

- `renamed` (boolean, required) — True if the label was successfully renamed

**400** — validation_failed — malformed name/sortOrder or empty patch

`application/json` → ErrorOrValidation

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

`application/json` → ErrorBody

**404** — Mailbox or label not found

`application/json` → ErrorBody

**409** — Target label name already exists

`application/json` → ErrorBody

**413** — too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing

`application/json` → ErrorBody

**503** — temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After

`application/json` → ErrorBody

### Example request

```bash
curl -X PATCH 'https://api.open.email/api/v1/mailboxes/{mailboxId}/labels/{label}' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## TypeScript SDK

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

```ts
const renamedResult = await openemail.labels.update(mailboxId, label, {})
```
