---
title: "Labels"
description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with."
url: "https://openemail.uk/docs/api/reference/labels"
area: "API"
category: "Reference"
---

# Labels

Every operation in this group: what it accepts, what it returns and the errors it can answer with.

## Operations

The names a conversation can be filed under, several at once. Labels belong to the workspace, so every member and every key sees the same set, and renaming or deleting one changes it for everybody.

A label's id comes from the name it was created with and never changes, so a rename keeps every conversation labelled. Its colour is a hex value or one of seven gradient tokens, and `GET /labels/colors` lists the palette the app offers. Apply and remove labels on a conversation with `PATCH /threads/{id}`. `GET /threads?folder=USER_BIG_CLIENTS` lists every conversation carrying a label, and `labelIds` narrows a folder to the ones carrying it.

### `GET /labels`

List labels

Every user label in the workspace, sorted by name and then by id, a page at a time: follow `nextCursor` while `hasMore` is true to read them all. Each row carries its colour, how many conversations carry it and when it was created and last changed, which is everything the Labels table in the app shows.

System labels such as `INBOX`, `STARRED` and `UNREAD` are not listed. A thread carries them and `PATCH /threads/{id}` takes them, but they cannot be renamed, recoloured or deleted.

The order the app's sidebar shows is each person's own arrangement and is not exposed here.

Requires the `labels:read` scope.

- Scopes: `labels:read`.

**Query parameters**

- `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100.
- `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`.

**Returns**

- `200` `LabelList`: A page of labels, by name.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`labels.list()`](https://openemail.uk/docs/sdk/reference/labels#list), [`labels.listAll()`](https://openemail.uk/docs/sdk/reference/labels#listAll), [`labels.iterate()`](https://openemail.uk/docs/sdk/reference/labels#iterate); CLI [`openemail labels list`](https://openemail.uk/docs/cli/reference/labels#labels-list); MCP [`getLabel`](https://openemail.uk/docs/mcp/tools/organising#getLabel), [`getUserLabels`](https://openemail.uk/docs/mcp/tools/organising#getUserLabels).

### `POST /labels`

Create a label

Creates a label and answers with it. The id comes from the name (`Big Clients` becomes `USER_BIG_CLIENTS`) and never changes afterwards. A workspace holds at most 50 labels.

Leave `color` out for a label with no colour, or send `color.backgroundColor` as a hex value or a gradient token. `GET /labels/colors` lists the swatches the app offers.

Requires the `labels:write` scope.

- Scopes: `labels:write`.

**Request body**

- `name` (`string`, required, 1 to 225 characters): Trimmed, then 1 to 225 characters. Also decides the id, which never changes afterwards.
- `color` (`LabelColorInput`): The colour. Leave it out for a label with no colour.

**Returns**

- `201` `Label`: Created, read back as it is stored.

**Errors**

- `409`: `label_name_taken`: another label already has that name, compared without case, or already holds the id this name gives because it was created under it and renamed since.
- `422`: `label_limit_reached` once the workspace holds 50 labels, or `invalid_parameter` for a colour that is neither a hex value nor a gradient token.
- The errors every operation can return: `400`, `401`, `403`, `404`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`labels.create()`](https://openemail.uk/docs/sdk/reference/labels#create); CLI [`openemail labels create`](https://openemail.uk/docs/cli/reference/labels#labels-create); MCP [`createLabel`](https://openemail.uk/docs/mcp/tools/organising#createLabel).

### `GET /labels/colors`

List label colours

The fourteen solid colours and seven gradients the app offers when you make or edit a label, in the order it shows them. Each one says what to send as `color.backgroundColor`, the ink drawn on it, and for a gradient the colour at each end and one solid hex for places a gradient cannot go.

A fixed catalogue with no paging. Fetch it once and keep it. A label may also carry any other hex, set through this API, which the app keeps and offers back as its own swatch.

Requires the `labels:read` scope.

- Scopes: `labels:read`.

**Returns**

- `200` `LabelColorList`: The whole palette.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`labels.listColors()`](https://openemail.uk/docs/sdk/reference/labels#listColors); CLI [`openemail labels list-colors`](https://openemail.uk/docs/cli/reference/labels#labels-list-colors).

### `GET /labels/{id}`

Retrieve a label

One label by id, in the same shape as a row of the list. Ids are matched exactly, and a system id such as `INBOX` is a 404.

Requires the `labels:read` scope.

- Scopes: `labels:read`.

**Path parameters**

- `id` (`string`, required): Label id such as `USER_RECEIPTS`, matched case sensitively.

**Returns**

- `200` `Label`: The label.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`labels.get()`](https://openemail.uk/docs/sdk/reference/labels#get); CLI [`openemail labels get`](https://openemail.uk/docs/cli/reference/labels#labels-get); MCP [`getLabel`](https://openemail.uk/docs/mcp/tools/organising#getLabel), [`getUserLabels`](https://openemail.uk/docs/mcp/tools/organising#getUserLabels).

### `PATCH /labels/{id}`

Rename or recolour a label

Renames a label, recolours it, or both. Send `name`, `color` or both; a field left out stays as it is, and `color: null` or an empty `backgroundColor` clears the colour. The id never changes, so every conversation keeps the label through a rename.

Requires the `labels:write` scope.

- Scopes: `labels:write`.

**Path parameters**

- `id` (`string`, required): Label id such as `USER_RECEIPTS`.

**Request body**

- `name` (`string`, 1 to 225 characters): The new name, trimmed, 1 to 225 characters. Left out, the name stays.
- `color` (`object`, nullable): The new colour. `null` clears it. Left out, the colour stays.
  - `backgroundColor` (`string`, required, up to 32 characters): A hex colour (`#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`), stored upper-cased, or a gradient token: `gradient:sunset`, `gradient:ember`, `gradient:meadow`, `gradient:lagoon`, `gradient:aurora`, `gradient:berry`, `gradient:midnight`. The app's solid swatches are `#EF4444`, `#F97316`, `#EA9602`, `#DCB30B`, `#79BB19`, `#2EB45C`, `#00AD9B`, `#09A9CA`, `#3B82F6`, `#6366F1`, `#8B5CF6`, `#D946EF`, `#EC4899`, `#64748B`, and any other hex is kept as it is. An empty string means no colour. Anything else is a 422 `invalid_parameter` on `color.backgroundColor`.
  - `textColor` (`string`, up to 32 characters): Accepted and ignored. The ink is worked out from `backgroundColor`.

**Returns**

- `200` `Label`: Saved, read back as it is stored.

**Errors**

- `409`: `label_name_taken`: another label already has that name, compared without case.
- `422`: `invalid_parameter` for a body with neither `name` nor `color`, or a colour that is neither a hex value nor a gradient token.
- The errors every operation can return: `400`, `401`, `403`, `404`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`labels.update()`](https://openemail.uk/docs/sdk/reference/labels#update); CLI [`openemail labels update`](https://openemail.uk/docs/cli/reference/labels#labels-update); MCP [`updateLabel`](https://openemail.uk/docs/mcp/tools/organising#updateLabel).

### `DELETE /labels/{id}`

Delete a label

Deletes the label and takes it off every conversation that carried it, in one step. The conversations stay in whatever folder they were in. There is no undo: creating the same name again gives the same id, but the conversations do not get the label back.

Requires the `labels:write` scope.

- Scopes: `labels:write`.

**Path parameters**

- `id` (`string`, required): Label id such as `USER_OLD_PROJECT`.

**Returns**

- `200` `DeletedLabel`: Deleted.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`labels.delete()`](https://openemail.uk/docs/sdk/reference/labels#delete); CLI [`openemail labels delete`](https://openemail.uk/docs/cli/reference/labels#labels-delete); MCP [`deleteLabel`](https://openemail.uk/docs/mcp/tools/organising#deleteLabel).

### Objects

#### `DeletedLabel`

`object`

- `object` (`string`, one of `"label"`)
- `id` (`string`)
- `deleted` (`boolean`, one of `true`)

#### `Label`

`object`

- `object` (`string`, one of `"label"`)
- `id` (`string`): Fixed when the label is created: `USER_` and the name upper-cased, with each run of spaces turned into `_`, so `Big Clients` is `USER_BIG_CLIENTS`. It never changes, so a renamed label keeps the id of its first name. Store the id rather than the name.
- `name` (`string`)
- `type` (`string`, one of `"user"`): Always `user`. System labels such as `INBOX`, `STARRED` and `UNREAD` are never listed, though a thread carries them and `PATCH /threads/{id}` takes them.
- `color` (`object`, nullable): How the label is painted. Null on a label saved with no colour.
  - `backgroundColor` (`string`): The stored colour: a hex value such as `#3B82F6`, stored upper-cased, or a gradient token such as `gradient:sunset`. `GET /labels/colors` lists the palette the app offers, with the two ends of every gradient.
  - `textColor` (`string`): The ink the app draws on that colour, `#18181B` or `#FFFFFF`. Worked out here from `backgroundColor` and never stored, so a `textColor` you sent is not echoed.
- `threadCount` (`integer`): Conversations carrying the label now, the number the Labels table in the app shows. A key limited to particular addresses counts only conversations delivered to them.
- `createdAt` (`string`, nullable, format `date-time`): Null on a label made before these times were recorded.
- `updatedAt` (`string`, nullable, format `date-time`): The last rename or recolour. Null on a label made before these times were recorded.

#### `LabelColorEntry`

`object`

- `object` (`string`, one of `"label_color"`)
- `kind` (`string`, one of `"solid"`, `"gradient"`)
- `name` (`string`): The swatch name, such as `red` or `sunset`.
- `value` (`string`, one of `"#EF4444"`, `"#F97316"`, `"#EA9602"`, `"#DCB30B"`, `"#79BB19"`, `"#2EB45C"`, `"#00AD9B"`, `"#09A9CA"`, `"#3B82F6"`, `"#6366F1"`, `"#8B5CF6"`, `"#D946EF"`, `"#EC4899"`, `"#64748B"`, `"gradient:sunset"`, `"gradient:ember"`, `"gradient:meadow"`, `"gradient:lagoon"`, `"gradient:aurora"`, `"gradient:berry"`, `"gradient:midnight"`): What to send as `color.backgroundColor` to use this swatch.
- `solid` (`string`): One hex for places a gradient cannot be drawn, such as an icon. The same as `value` on a solid.
- `from` (`string`, nullable): Where a gradient starts, drawn at 135 degrees. Null on a solid.
- `to` (`string`, nullable): Where a gradient ends. Null on a solid.
- `textColor` (`string`): The ink the app draws on this swatch.

#### `LabelColorInput`

`object`

- `backgroundColor` (`string`, required, up to 32 characters): A hex colour (`#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`), stored upper-cased, or a gradient token: `gradient:sunset`, `gradient:ember`, `gradient:meadow`, `gradient:lagoon`, `gradient:aurora`, `gradient:berry`, `gradient:midnight`. The app's solid swatches are `#EF4444`, `#F97316`, `#EA9602`, `#DCB30B`, `#79BB19`, `#2EB45C`, `#00AD9B`, `#09A9CA`, `#3B82F6`, `#6366F1`, `#8B5CF6`, `#D946EF`, `#EC4899`, `#64748B`, and any other hex is kept as it is. An empty string means no colour. Anything else is a 422 `invalid_parameter` on `color.backgroundColor`.
- `textColor` (`string`, up to 32 characters): Accepted and ignored. The ink is worked out from `backgroundColor`.

#### `LabelColorList`

`object`

- `object` (`string`, one of `"list"`)
- `data` (`LabelColorEntry[]`)

#### `LabelList`

`object`

- `object` (`string`, one of `"list"`)
- `data` (`Label[]`)
- `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it.
- `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged.