---
title: "Labels"
description: "`labels.list`, `get`, `create`, `update` and `delete`."
url: "https://openemail.uk/docs/sdk/labels"
area: "SDK"
category: "Mailbox"
---

# Labels

`labels.list`, `get`, `create`, `update` and `delete`.

## Every method

**usage.ts**

```
const labels = await openemail.labels.list()
const label = await openemail.labels.get('USER_INVOICES')

const created = await openemail.labels.create({
  name: 'Invoices',
  color: { backgroundColor: '#e8eaed', textColor: '#3c4043' },
})

await openemail.labels.update(created.id!, { name: 'Invoices 2027' })
await openemail.labels.delete(created.id!)
```

`list` resolves to a plain array, since labels are not paged. `color` is returned on reads rather than dropped, so a client can render a label the way the user sees it. `type` is always `user`, so there is nothing to branch on. Ids are derived from the name, so `Invoices` is `USER_INVOICES`.

## Parameters: labels.create and labels.update

- `name` (string, required): The label's display name, trimmed before it is measured, so the limit is 1 to 225 characters after trimming. Whitespace alone is a 422 rather than a nameless row with a colour dot and nothing to read or click. `create` additionally refuses once the mailbox already holds 50 user labels, with a 422 `label_limit_reached` naming `name`.
- `color` (LabelColor): Optional on both calls, and omitting it on `update` leaves the stored colour alone rather than clearing 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): Required once `color` is given, and at most 32 characters. On the native mailbox this is the only half kept: the row stores a single colour.
- `color.textColor` (string, required): Required once `color` is given, and at most 32 characters.

## Response: Label

- `object` ('label'): Always the string `label`. A write returns it too, on a `SavedLabelResource` rather than on this type.
- `id` (string): The mailbox's own id, and what `get`, `update` and `delete` take. On a write it arrives as `SavedLabelResource.id`, which is nullable. When it is null, find the label by listing.
- `name` (string): What the user sees, and an empty string rather than null when the mailbox hands back a label without one. On the native mailbox the id is derived from this name (`Follow up` becomes `USER_FOLLOW_UP`), so a second label that normalises to the same id is refused with a 409 `label_name_taken` rather than overwriting the first.
- `type` (string): Always `user`. Only user labels are served here: the standard folder ids are filtered out before the response is built, and a system id on `get` is a 404. The route falls back to `user` when the mailbox omits the field, and nothing in `LabelInput` sets it.
- `color` (LabelColor | null): Null when the mailbox reports no colour for the label. Test the strings rather than the object before rendering. An empty pair is not the same as an absent one.
- `color.backgroundColor` (string): The label's background as the mailbox holds it. Returned rather than dropped, so a client can render the label the way the user sees it in the app.
- `color.textColor` (string): The foreground colour. The native mailbox has no column for it: reads return `#ffffff` whatever was written, so a pale background comes back with unreadable text against it.