Labels
`labels->list`, `listAll`, `iterate`, `listColors`, `get`, `create`, `update` and `delete`.
Every method
$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
namestring- 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`.
colorarray 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.backgroundColorstringrequired- 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.textColorstring- 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.
objectstring- Always the string `label`. `create` and `update` return this same array, read back as it is stored.
idstring- The label’s id, and what `get`, `update`, `delete` and `threads->update` take. It never changes, even after a rename.
namestring- What the user sees.
typestring- Always `user`. System labels are never served here, and a system id on `get` is a 404, thrown as a `NotFoundException`.
colorarray or null- It is null when the label has no colour.
color.backgroundColorstring- The stored colour: a hex value or a gradient token. `listColors` gives a gradient’s two ends.
color.textColorstring- The ink the app draws on the colour, `#18181B` or `#FFFFFF`, worked out on the server rather than stored.
threadCountint- How many conversations carry the label now. For a key limited to particular addresses, only conversations delivered to them count.
createdAtstring or null- When the label was made, as ISO 8601, or null for a label made before these times were recorded.
updatedAtstring 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)
kindstring- Whether the swatch is one colour or a gradient: `solid` or `gradient`.
namestring- The swatch name, such as `red` or `sunset`.
valuestring- What to send as `color.backgroundColor` to use this swatch.
solidstring- One hex for places a gradient cannot be drawn. The same as `value` on a solid.
fromstring or null- Where a gradient starts, drawn at 135 degrees. It is null on a solid.
tostring or null- Where a gradient ends. It is null on a solid.
textColorstring- The ink the app draws on this swatch.