---
title: "Labels"
description: "`labels->list`, `listAll`, `iterate`, `listColors`, `get`, `create`, `update` and `delete`."
url: "https://openemail.uk/docs/php/labels"
area: "PHP"
category: "Mailbox"
---

# Labels

`labels->list`, `listAll`, `iterate`, `listColors`, `get`, `create`, `update` and `delete`.

## Every method

**labels.php**

```
$page = $client->labels->list(limit: 50);
$every = $client->labels->listAll();
$colors = $client->labels->listColors();
echo count($page), ' ', count($every), ' ', count($colors), PHP_EOL;

foreach ($client->labels->iterate() as $row) {
    echo $row['name'], ' ', $row['threadCount'], PHP_EOL;
}

$created = $client->labels->create([
    'name' => 'Invoices',
    'color' => ['backgroundColor' => 'gradient:sunset'],
]);

$client->labels->update($created['id'], ['name' => 'Invoices 2027']);
$client->labels->update($created['id'], ['color' => ['backgroundColor' => '#3B82F6']]);

$label = $client->labels->get($created['id']);
echo $label['name'], ' ', $label['color']['backgroundColor'] ?? 'no colour', PHP_EOL;

$client->labels->delete($created['id']);
```

`list` returns one `OpenEmail\Result\Page` of labels sorted by name, and `listAll` and `iterate` walk every page. `listAll` returns one array, and `iterate` returns a `Generator` that yields one label at a time. Each label is an array keyed in camelCase that carries its colour, `threadCount` and when it was created and last changed. `listColors` returns the palette the app offers, fourteen solids and seven gradients, as a plain list of arrays with no paging. `type` is always `user`. The id comes from the name the label was created with, so `Invoices` is `USER_INVOICES`, and it never changes.

The fields of `create` and `update` are the keys of one array under the API’s names, so a colour is `'color' => ['backgroundColor' => '#3B82F6']`.

> 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 `$client->threads->list(folder: 'USER_INVOICES')` lists every conversation carrying one. The Threads page covers both.

## Parameters: labels->create and labels->update

- `name` (string): 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`, thrown as a `ConflictException`. `create` refuses once the workspace holds 50 labels, with a 422 `label_limit_reached`, thrown as a `ValidationException`.
- `color` (array or null): Optional on both calls. Leaving it out on `update` keeps the stored colour, and `'color' => null` 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` (string, 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` (string): Accepted and ignored. The ink is worked out from `backgroundColor`, the same way the app does it.

## Response: a label

A label is an array keyed in camelCase, so `$label['threadCount']` reads the count, and `$label['color']['backgroundColor'] ?? null` reads the colour and gives null when the label has none.

- `object` (string): Always the string `label`. `create` and `update` return this same array, read back as it is stored.
- `id` (string): The label’s id, and what `get`, `update`, `delete` and `threads->update` take. It never changes, even after a rename.
- `name` (string): What the user sees.
- `type` (string): Always `user`. System labels are never served here, and a system id on `get` is a 404, thrown as a `NotFoundException`.
- `color` (array or null): It is null when the label has no colour.
- `color.backgroundColor` (string): The stored colour: a hex value or a gradient token. `listColors` gives a gradient’s two ends.
- `color.textColor` (string): 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` (string or null): When the label was made, as ISO 8601, or null for a label made before these times were recorded.
- `updatedAt` (string or null): The last rename or recolour, as ISO 8601, or null for a label made before these times were recorded.

## Response: a colour swatch (labels->listColors)

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