---
title: "Labels"
description: "`labels.list`, `list_all`, `iterate`, `list_colors`, `get`, `create`, `update` and `delete`."
url: "https://openemail.uk/docs/python/labels"
area: "Python"
category: "Mailbox"
---

# Labels

`labels.list`, `list_all`, `iterate`, `list_colors`, `get`, `create`, `update` and `delete`.

## Every method

**usage.py**

```
from openemail import openemail

page = openemail.labels.list(limit=50)
every = openemail.labels.list_all()
colors = openemail.labels.list_colors()

created = openemail.labels.create({
    'name': 'Invoices',
    'color': {'backgroundColor': 'gradient:sunset'},
})

openemail.labels.update(created['id'], {'name': 'Invoices 2027'})
openemail.labels.update(created['id'], {'color': {'backgroundColor': '#3B82F6'}})
openemail.labels.delete(created['id'])
```

`list` returns one `Page` of labels sorted by name, and `list_all` and `iterate` walk every page. Each label carries its colour, `threadCount` and when it was created and last changed. `list_colors` returns the palette the app offers, fourteen solids and seven gradients, as a plain list. `type` is always `user`. The id comes from the name the label was created with, so `Invoices` is `USER_INVOICES`, and it never changes.

> A label belongs to the workspace, so a rename, a recolour or a delete changes it for every member and every key. `threads.update` puts labels on a conversation and takes them off, and `threads.list(folder='USER_INVOICES')` lists every conversation carrying one.

- [Threads](https://openemail.uk/docs/python/threads.md): Put labels on a conversation, take them off and list by label.

## Parameters: labels.create and labels.update

- `name` (str): The label's display name, trimmed before it is measured, so the limit is 1 to 225 characters after trimming. Required on `create` and optional on `update`, where leaving it out keeps the name. Whitespace alone is a 422. A name another label already has, compared without case, is a 409 `label_name_taken`, and `create` refuses once the workspace holds 50 labels, with a 422 `label_limit_reached`.
- `color` (LabelColorInput | None): Optional on both calls. Leaving it out on `update` keeps the stored colour, and `None` clears it. The body is strict, so a near-miss key such as `colour` is a 422 rather than a silent no-op.
- `color.backgroundColor` (str, required): 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` or `gradient:midnight`. An empty string means no colour, and anything else is a 422 `invalid_parameter`.
- `color.textColor` (str): Accepted and ignored. The ink is worked out from `backgroundColor`, the same way the app does it.

## Response: LabelResource

- `object` (Literal['label']): Always the string `label`. `create` and `update` return this same type, read back as it is stored.
- `id` (str): The label's id, and what `get`, `update`, `delete` and `threads.update` take. It never changes, even after a rename.
- `name` (str): What the user sees.
- `type` (str): Always `user`. System labels are never served here, and a system id on `get` is a 404.
- `color` (LabelColor | None): `None` when the label has no colour.
- `color.backgroundColor` (str): The stored colour: a hex value or a gradient token. `list_colors` gives a gradient's two ends.
- `color.textColor` (str): The ink the app draws on the colour, `#18181B` or `#FFFFFF`, worked out on the server rather than stored.
- `threadCount` (int): How many conversations carry the label now. For a key limited to particular addresses, only conversations delivered to them count.
- `createdAt` (str | None): When the label was made, as ISO 8601, or `None` for a label made before these times were recorded.
- `updatedAt` (str | None): The last rename or recolour, as ISO 8601, or `None` for a label made before these times were recorded.

## Response: LabelColorResource

- `kind` (Literal['solid', 'gradient']): Whether the swatch is one colour or a gradient.
- `name` (str): The swatch name, such as `red` or `sunset`.
- `value` (str): What to send as `color.backgroundColor` to use this swatch.
- `solid` (str): One hex for places a gradient cannot be drawn. The same as `value` on a solid.
- `from` (str | None): Where a gradient starts, drawn at 135 degrees. `None` on a solid.
- `to` (str | None): Where a gradient ends. `None` on a solid.
- `textColor` (str): The ink the app draws on this swatch.

## Reference

- [`labels.list()`](https://openemail.uk/docs/python/reference/labels#list): full reference
- [`labels.list_all()`](https://openemail.uk/docs/python/reference/labels#listAll): full reference
- [`labels.iterate()`](https://openemail.uk/docs/python/reference/labels#iterate): full reference
- [`labels.list_colors()`](https://openemail.uk/docs/python/reference/labels#listColors): full reference
- [`labels.get()`](https://openemail.uk/docs/python/reference/labels#get): full reference
- [`labels.create()`](https://openemail.uk/docs/python/reference/labels#create): full reference
- [`labels.update()`](https://openemail.uk/docs/python/reference/labels#update): full reference
- [`labels.delete()`](https://openemail.uk/docs/python/reference/labels#delete): full reference