Labels
`labels.list`, `list_all`, `iterate`, `list_colors`, `get`, `create`, `update` and `delete`.
Every method
page = client.labels.list(limit: 50)every = client.labels.list_allcolors = client.labels.list_colorsputs 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
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`, raised as `OpenEmail::ConflictError`. `create` refuses once the workspace holds 50 labels, with a 422 `label_limit_reached`, raised as `OpenEmail::ValidationError`.
colorHash 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.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 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.
objectString- Always the string `label`. `create` and `update` return this same Hash, 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, raised as `OpenEmail::NotFoundError`.
colorHash or nil- It is nil when the label has no colour.
color.backgroundColorString- The stored colour: a hex value or a gradient token. `list_colors` 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.
threadCountInteger- How many conversations carry the label now. For a key limited to particular addresses, only conversations delivered to them count.
createdAtString or nil- When the label was made, as ISO 8601, or nil for a label made before these times were recorded.
updatedAtString 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)
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 nil- Where a gradient starts, drawn at 135 degrees. It is nil on a solid.
toString or nil- Where a gradient ends. It is nil on a solid.
textColorString- The ink the app draws on this swatch.