# Create a new custom label

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

## `POST /api/v1/mailboxes/{mailboxId}/labels`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier

### Request body (required)

`application/json`

- `name` (string, required, 1–255 chars) — Name for the new label. May not start with `*`, which clients reserve for their own views
- `color` (string | null, pattern `^#[0-9a-f]{6}$`) — Hex color code for the label badge/chip, or null

### Responses

**200** — Created label details

`application/json` → CreatedLabel

- `color` (string | null, required) — Hex color code for the label badge/chip, or null
- `id` (integer <int64>, required) — Assigned label ID
- `name` (string, required) — Created label name
- `uidValidity` (integer <int64>, required) — Initial UIDVALIDITY epoch for the label

**400** — validation_failed — malformed name or color

`application/json` → ErrorOrValidation

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

`application/json` → ErrorBody

**404** — Mailbox not found or not accessible to this principal

`application/json` → ErrorBody

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

`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 POST 'https://api.open.email/api/v1/mailboxes/{mailboxId}/labels' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string"
  }'
```

## TypeScript SDK

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

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