--- title: "openemail labels" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/labels" area: "CLI" category: "Reference" --- # openemail labels Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail labels list` List the workspace's labels, a page at a time ```bash openemail labels list [flags] ``` Resolves one page of the workspace's user labels, sorted by name and then by id. Each label carries its colour, `threadCount` (how many conversations carry it now) and `createdAt` and `updatedAt`, which is everything the Labels table in the app shows. System labels such as `INBOX`, `STARRED` and `UNREAD` are not listed. A thread carries them and `threads.update` takes them, but they cannot be renamed, recoloured or deleted. `color` is null on a label saved with no colour. Otherwise `color.backgroundColor` is a hex value or a gradient token such as `gradient:sunset`, and `color.textColor` is the ink the app draws on it, worked out on the server rather than stored. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `labels:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--limit ` (default `25`): Page size, from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` of the previous page, passed back as it came. Leave it out for the first page. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash openemail labels list ``` With optional flags ```bash openemail labels list --limit 50 ``` Walk every page and stop after 100 items ```bash openemail labels list --all --max 100 ``` One JSON object per line when piped ```bash openemail labels list --all > labels.ndjson ``` Also available in: API [`GET /labels`](https://openemail.uk/docs/api/reference/labels#get-labels); SDK [`labels.list()`](https://openemail.uk/docs/sdk/reference/labels#list). ### `openemail labels list-colors` List the colours the app offers for labels ```bash openemail labels list-colors [flags] ``` Resolves the whole label palette as a plain array: the fourteen solid colours and seven gradients the app offers when you make or edit a label, in the order it shows them. It is a fixed catalogue, so there is no paging. Fetch it once and keep it. `value` is what to send as `color.backgroundColor`: a hex such as `#3B82F6` for a solid, a token such as `gradient:sunset` for a gradient. `textColor` is the ink drawn on it. A gradient also carries `from` and `to`, drawn at 135 degrees, and `solid`, one hex for places a gradient cannot go. A label may carry a colour outside this list. Any hex set through the API is kept as it is, and the app offers it back as its own swatch. - Scopes: `labels:read`. - Needs a sign-in. **Examples** ```bash openemail labels list-colors ``` Print the raw JSON ```bash openemail labels list-colors --json ``` Also available in: API [`GET /labels/colors`](https://openemail.uk/docs/api/reference/labels#get-labels-colors); SDK [`labels.listColors()`](https://openemail.uk/docs/sdk/reference/labels#listColors). ### `openemail labels get` Read one user label by id ```bash openemail labels get [flags] ``` Looks up a single user label and returns it in the same shape as a row of `list`, with its colour, `threadCount`, `createdAt` and `updatedAt`. Only user labels are served. `INBOX`, `TRASH` and the other system ids are a 404 here even though threads carry them. Ids are matched exactly, so `user_receipts` does not find `USER_RECEIPTS`. - Scopes: `labels:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): Label id such as `USER_RECEIPTS`, matched case sensitively. **Examples** ```bash openemail labels get USER_RECEIPTS ``` Print the raw JSON ```bash openemail labels get USER_RECEIPTS --json ``` Also available in: API [`GET /labels/{id}`](https://openemail.uk/docs/api/reference/labels#get-labels-id); SDK [`labels.get()`](https://openemail.uk/docs/sdk/reference/labels#get). ### `openemail labels create` Create a user label ```bash openemail labels create --name [flags] openemail labels create --data [flags] ``` Creates a label and resolves with it as it is stored. `name` is trimmed and must then be 1 to 225 characters. The id is derived from the name as `USER_` followed by the name upper cased, with each run of whitespace turned into `_`, so `Big Clients` becomes `USER_BIG_CLIENTS`, and it never changes afterwards. A name another label already has, compared without case, is refused with 409 `label_name_taken`, and so is a name whose id another label holds because it was created under that name and renamed since. An existing label is never silently overwritten. A workspace holds at most 50 user labels, and the call past that is a 422 `label_limit_reached` on `name`. `color` is optional. `color.backgroundColor` is a hex colour (`#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`, stored upper cased) or a gradient token such as `gradient:sunset`, and anything else is a 422 `invalid_parameter` on `color.backgroundColor`. `listColors` returns the palette the app offers. `textColor` may be sent but is ignored: the ink is worked out from the background. Leaving `color` out stores no colour. - Scopes: `labels:write`. - Needs a sign-in. - Aliases: `new`, `add`. **Flags** - `--name `: Display name, trimmed, 1 to 225 characters. Also decides the id. Required, here or in `--data`. - `--label-color `: The colour. Leave it out for a label with no colour. JSON shaped as `LabelColorInput`, inline or from a file with @path. - `--color-background-color `: A hex colour such as `#3B82F6` or a gradient token such as `gradient:sunset`, at most 32 characters. Required once `color` is given. - `--color-text-color `: Accepted and ignored. The ink is worked out from `backgroundColor`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash openemail labels create --name 'Big Clients' ``` With optional flags ```bash openemail labels create --name 'Big Clients' --color-background-color gradient:aurora ``` Read the whole body from a JSON file ```bash openemail labels create --data @label.json ``` Also available in: API [`POST /labels`](https://openemail.uk/docs/api/reference/labels#post-labels); SDK [`labels.create()`](https://openemail.uk/docs/sdk/reference/labels#create). ### `openemail labels update` Rename or recolour a user label ```bash openemail labels update [flags] ``` Renames a label, recolours it, or both, and resolves with it as it is stored. Send `name`, `color` or both: a field left out stays as it is, and a patch with neither is a 422. `color: null`, or an empty `backgroundColor`, clears the colour. The id never changes. A label created as `Receipts` keeps `USER_RECEIPTS` after a rename to `Invoices`, and every thread keeps the label. A new name another label already has, compared without case, is refused with 409 `label_name_taken`. Colours follow the rules on `create`: a hex value or a gradient token, and anything else is a 422 `invalid_parameter`. Only user labels can be changed, and a system label id is a 404. - Scopes: `labels:write`. - Needs a sign-in. - Aliases: `edit`. **Arguments** - `` (required): Label id such as `USER_RECEIPTS`. **Flags** - `--name `: New display name, trimmed, 1 to 225 characters. Left out, the name stays. - `--label-color `: New colour. `null` clears it, and leaving it out keeps the stored colour. JSON shaped as `LabelColorInput | null`, inline or from a file with @path. - `--color-background-color `: A hex colour or a gradient token, at most 32 characters. An empty string clears the colour. - `--color-text-color `: Accepted and ignored. The ink is worked out from `backgroundColor`. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash openemail labels update USER_RECEIPTS --color-background-color '#EA9602' ``` Print the raw JSON ```bash openemail labels update USER_RECEIPTS --color-background-color '#EA9602' --json ``` Also available in: API [`PATCH /labels/{id}`](https://openemail.uk/docs/api/reference/labels#patch-labels-id); SDK [`labels.update()`](https://openemail.uk/docs/sdk/reference/labels#update). ### `openemail labels delete` Delete a user label and remove it from every thread ```bash openemail labels delete [flags] ``` Deletes a user label and, in the same transaction, takes it off every thread that carried it. The threads are otherwise untouched, so a thread that was only filed under this label stays in whatever folder it was in. There is no undo. Creating a label with the same name again produces the same id, but the threads it was removed from do not get it back. Only user labels can be deleted, and a system label id is a 404. - Scopes: `labels:write`. - Needs a sign-in. - Asks you to confirm. - Aliases: `rm`, `del`, `remove`. **Arguments** - `` (required): Label id such as `USER_OLD_PROJECT`. **Examples** ```bash openemail labels delete USER_OLD_PROJECT ``` Skip the confirmation, for scripts ```bash openemail labels delete USER_OLD_PROJECT --yes ``` Also available in: API [`DELETE /labels/{id}`](https://openemail.uk/docs/api/reference/labels#delete-labels-id); SDK [`labels.delete()`](https://openemail.uk/docs/sdk/reference/labels#delete).