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

# Labels

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

## Every method

**labels.rb**

```
page = client.labels.list(limit: 50)
every = client.labels.list_all
colors = client.labels.list_colors
puts page.items.size, every.size, colors.size

client.labels.iterate do |row|
  puts "#{row[:name]} #{row[:threadCount]}"
end

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])
puts label[:name], label.dig(:color, :backgroundColor)

client.labels.delete(created[:id])
```

`list` returns one `OpenEmail::Page` of labels sorted by name, and `list_all` and `iterate` walk every page. `list_all` returns one Array, and `iterate` yields one label at a time to a block, or returns an Enumerator without one. Each label is a Hash with Symbol keys that 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 Array of Hashes 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 keyword arguments or one Hash, and keep 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`, raised as `OpenEmail::ConflictError`. `create` refuses once the workspace holds 50 labels, with a 422 `label_limit_reached`, raised as `OpenEmail::ValidationError`.
- `color` (Hash or nil): Optional on both calls. Leaving it out on `update` keeps the stored colour, and `color: nil` 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 a Hash with Symbol keys, so `label[:threadCount]` reads the count, and `label.dig(:color, :backgroundColor)` reads the colour and gives nil when the label has none.

- `object` (String): Always the string `label`. `create` and `update` return this same Hash, 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, raised as `OpenEmail::NotFoundError`.
- `color` (Hash or nil): It is nil when the label has no colour.
- `color.backgroundColor` (String): The stored colour: a hex value or a gradient token. `list_colors` 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` (Integer): How many conversations carry the label now. For a key limited to particular addresses, only conversations delivered to them count.
- `createdAt` (String or nil): When the label was made, as ISO 8601, or nil for a label made before these times were recorded.
- `updatedAt` (String or nil): The last rename or recolour, as ISO 8601, or nil for a label made before these times were recorded.

## Response: a colour swatch (labels.list_colors)

- `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 nil): Where a gradient starts, drawn at 135 degrees. It is nil on a solid.
- `to` (String or nil): Where a gradient ends. It is nil on a solid.
- `textColor` (String): The ink the app draws on this swatch.