SDK

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

namestringrequired: 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`.
colorLabelColor: 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.backgroundColorstringrequired: 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.textColorstringrequired: 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.
idstring: 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.
namestring: 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.
typestring: 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.
colorLabelColor | 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.backgroundColorstring: 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.textColorstring: 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.