# labels.updateById

Rename a label or update folder settings, 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.

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.

```ts
openemail.labels.updateById(
  mailboxId: string,
  labelId: number,
  body: LabelsUpdateByIdBody,
  options?: CallOptions,
): ApiPromise<RenamedResult>
```

It calls `PATCH /mailboxes/{mailboxId}/labels/by-id/{labelId}`: [Rename a label or update folder settings, by id](/docs/api/labels/patch_LabelRenameById) in the API reference.

## Example

```ts
const renamedResult = await openemail.labels.updateById(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}`. |
| `body` | [`LabelsUpdateByIdBody`](#labelsupdatebyidbody) | The request's body. |

## Options

It takes no options of its own. 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, [`RenamedResult`](/docs/sdks/typescript/types/renamed-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 |
| --- | --- |
| `400` | validation_failed — malformed name/sortOrder or empty patch |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `403` | System labels cannot be renamed |
| `404` | Mailbox or label not found |
| `409` | Target label name already exists |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `503` | temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After |

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

### LabelsUpdateByIdBody

```ts
/** The body of `labels.updateById`. */
type LabelsUpdateByIdBody = {
  /** Hex color code for the label badge/chip, or null to clear */
  color?: string | null
  /** Whether folder is subscribed for client sync */
  isSubscribed?: boolean
  /** New label name (custom labels only). May not start with `*` */
  name?: string
  /** Presentation display sort order index */
  sortOrder?: number
  /** 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. */
  withChildren?: boolean
}
```

It names these types of the API, each on a page of its own: [`RenamedResult`](/docs/sdks/typescript/types/renamed-result).
