# labels.create

Create a new custom label.

Creates a new user folder or label with a fresh UID validity epoch.

```ts
openemail.labels.create(
  mailboxId: string,
  body: LabelsCreateBody,
  options?: CallOptions,
): ApiPromise<CreatedLabel>
```

It calls `POST /mailboxes/{mailboxId}/labels`: [Create a new custom label](/docs/api/labels/post_LabelCreate) in the API reference.

## Example

```ts
const createdLabel = await openemail.labels.create(mailboxId, { name: 'Ada' })
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |
| `body` | [`LabelsCreateBody`](#labelscreatebody) | 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, [`CreatedLabel`](/docs/sdks/typescript/types/created-label). 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 or color |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `404` | Mailbox not found or not accessible to this principal |
| `409` | label_exists — a label with this name already exists; or too_many_labels — the mailbox is at its ceiling of 500 labels (system labels are not counted), and a retry under another name cannot help. Delete one first |
| `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

### LabelsCreateBody

```ts
/** The body of `labels.create`. */
type LabelsCreateBody = {
  /** Hex color code for the label badge/chip, or null */
  color?: string | null
  /** Name for the new label. May not start with `*`, which clients reserve for their own views */
  name: string
}
```

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