--- title: "nextmail labels" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://nextmail.sh/docs/cli/reference/labels" area: "CLI" category: "Reference" --- # nextmail labels Every command in this namespace, with its arguments, flags and examples. ## Commands ### `nextmail labels list` List the workspace's labels, a page at a time ```bash nextmail 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 nextmail labels list ``` With optional flags ```bash nextmail labels list --limit 50 ``` Walk every page and stop after 100 items ```bash nextmail labels list --all --max 100 ``` One JSON object per line when piped ```bash nextmail labels list --all > labels.ndjson ``` Also available in: API [`GET /labels`](https://nextmail.sh/docs/api/reference/labels#get-labels); TypeScript [`nextmail.labels.list()`](https://nextmail.sh/docs/sdk/reference/labels#list); Python [`labels.list()`](https://nextmail.sh/docs/python/reference/labels#list); Ruby [`labels.list`](https://nextmail.sh/docs/ruby/reference/labels#list); PHP [`labels->list`](https://nextmail.sh/docs/php/reference/labels#list); Go [`Labels.List`](https://nextmail.sh/docs/go/reference/labels#list); Java [`labels().list`](https://nextmail.sh/docs/java/reference/labels#list); C# [`Labels.ListAsync`](https://nextmail.sh/docs/csharp/reference/labels#list). ### `nextmail labels list-colors` List the colours the app offers for labels ```bash nextmail 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 nextmail labels list-colors ``` Print the raw JSON ```bash nextmail labels list-colors --json ``` Also available in: API [`GET /labels/colors`](https://nextmail.sh/docs/api/reference/labels#get-labels-colors); TypeScript [`nextmail.labels.listColors()`](https://nextmail.sh/docs/sdk/reference/labels#listColors); Python [`labels.list_colors()`](https://nextmail.sh/docs/python/reference/labels#listColors); Ruby [`labels.list_colors`](https://nextmail.sh/docs/ruby/reference/labels#listColors); PHP [`labels->listColors`](https://nextmail.sh/docs/php/reference/labels#listColors); Go [`Labels.ListColors`](https://nextmail.sh/docs/go/reference/labels#listColors); Java [`labels().listColors`](https://nextmail.sh/docs/java/reference/labels#listColors); C# [`Labels.ListColorsAsync`](https://nextmail.sh/docs/csharp/reference/labels#listColors). ### `nextmail labels get` Read one user label by id ```bash nextmail 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 nextmail labels get USER_RECEIPTS ``` Print the raw JSON ```bash nextmail labels get USER_RECEIPTS --json ``` Also available in: API [`GET /labels/{id}`](https://nextmail.sh/docs/api/reference/labels#get-labels-id); TypeScript [`nextmail.labels.get()`](https://nextmail.sh/docs/sdk/reference/labels#get); Python [`labels.get()`](https://nextmail.sh/docs/python/reference/labels#get); Ruby [`labels.get`](https://nextmail.sh/docs/ruby/reference/labels#get); PHP [`labels->get`](https://nextmail.sh/docs/php/reference/labels#get); Go [`Labels.Get`](https://nextmail.sh/docs/go/reference/labels#get); Java [`labels().get`](https://nextmail.sh/docs/java/reference/labels#get); C# [`Labels.GetAsync`](https://nextmail.sh/docs/csharp/reference/labels#get). ### `nextmail labels create` Create a user label ```bash nextmail labels create --name [flags] nextmail 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. `--ai-instructions` says what the label is for in plain words, such as `invoices and receipts`. With `--ai-enabled` on, AI reads each arriving message against them and adds the label when it fits. It skips spam, the Bin, encrypted mail and muted threads, and it only labels: it never archives or moves anything. Turning `--ai-enabled` on needs instructions and a paid plan, and a workspace may have 10 such labels. Without instructions it is a 422 `invalid_parameter` on `--ai-instructions`, on the free plan a 403 `plan_required`, and past the tenth a 422 `ai_label_limit_reached`. - 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`. - `--ai-instructions `: What the label is for, in plain words, up to 500 characters, such as `invoices and receipts`. - `--ai-enabled`: Have AI apply the label to arriving mail that fits `--ai-instructions`. It needs instructions and a paid plan, and a workspace may have 10 such labels. - `--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 nextmail labels create --name 'Big Clients' ``` With optional flags ```bash nextmail labels create --name 'Big Clients' --color-background-color gradient:aurora ``` Read the whole body from a JSON file ```bash nextmail labels create --data @label.json ``` Also available in: API [`POST /labels`](https://nextmail.sh/docs/api/reference/labels#post-labels); TypeScript [`nextmail.labels.create()`](https://nextmail.sh/docs/sdk/reference/labels#create); Python [`labels.create()`](https://nextmail.sh/docs/python/reference/labels#create); Ruby [`labels.create`](https://nextmail.sh/docs/ruby/reference/labels#create); PHP [`labels->create`](https://nextmail.sh/docs/php/reference/labels#create); Go [`Labels.Create`](https://nextmail.sh/docs/go/reference/labels#create); Java [`labels().create`](https://nextmail.sh/docs/java/reference/labels#create); C# [`Labels.CreateAsync`](https://nextmail.sh/docs/csharp/reference/labels#create). ### `nextmail labels update` Rename or recolour a user label ```bash nextmail labels update [flags] ``` Renames a label, recolours it, or changes what AI does with it, and resolves with it as it is stored. Send any of `name`, `color`, `--ai-instructions` and `--ai-enabled`: a field left out stays as it is, and a patch with none of them 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. With `--ai-enabled` on, AI reads each arriving message against `--ai-instructions` and adds the label when it fits. It skips spam, the Bin, encrypted mail and muted threads, and it only labels: it never archives or moves anything. Turning it on needs instructions and a paid plan, and a workspace may have 10 such labels. Without instructions it is a 422 `invalid_parameter` on `--ai-instructions`, on the free plan a 403 `plan_required`, and past the tenth a 422 `ai_label_limit_reached`. `aiInstructions: null` clears the instructions, which also turns `--ai-enabled` off. - 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`. - `--ai-instructions `: What the label is for, in plain words, up to 500 characters. `null` clears it, which also turns `--ai-enabled` off. Left out, it stays. - `--ai-enabled`: Whether AI applies the label to arriving mail that fits `--ai-instructions`. Turning it on needs instructions and a paid plan, and a workspace may have 10 such labels. Left out, it stays. - `--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 nextmail labels update USER_RECEIPTS --color-background-color '#EA9602' ``` Print the raw JSON ```bash nextmail labels update USER_RECEIPTS --color-background-color '#EA9602' --json ``` Also available in: API [`PATCH /labels/{id}`](https://nextmail.sh/docs/api/reference/labels#patch-labels-id); TypeScript [`nextmail.labels.update()`](https://nextmail.sh/docs/sdk/reference/labels#update); Python [`labels.update()`](https://nextmail.sh/docs/python/reference/labels#update); Ruby [`labels.update`](https://nextmail.sh/docs/ruby/reference/labels#update); PHP [`labels->update`](https://nextmail.sh/docs/php/reference/labels#update); Go [`Labels.Update`](https://nextmail.sh/docs/go/reference/labels#update); Java [`labels().update`](https://nextmail.sh/docs/java/reference/labels#update); C# [`Labels.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/labels#update). ### `nextmail labels test` Try a label on recent mail ```bash nextmail labels test [flags] ``` Runs the AI over the newest 20 inbox threads and resolves with the ones the label would catch, without labelling anything. Send `--ai-instructions` to try wording you have not saved yet, or leave it out to try what the label holds. It spends one AI action of the caller, which the labelling of arriving mail never does. A message that arrived encrypted is skipped, and a key limited to particular addresses reads only the threads delivered to them. - Scopes: `labels:write`, `threads:read`. - Needs a sign-in. **Arguments** - `` (required): Label id such as `USER_RECEIPTS`, as `list` returns it. **Flags** - `--ai-instructions `: What the label is for, in plain words, 1 to 500 characters. Left out, the instructions saved on the label are tried. - `--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 nextmail labels test USER_RECEIPTS ``` With optional flags ```bash nextmail labels test USER_RECEIPTS --ai-instructions 'invoices and receipts' ``` Also available in: API [`POST /labels/{id}/test`](https://nextmail.sh/docs/api/reference/labels#post-labels-id-test); TypeScript [`nextmail.labels.test()`](https://nextmail.sh/docs/sdk/reference/labels#test); Python [`labels.test()`](https://nextmail.sh/docs/python/reference/labels#test); Ruby [`labels.test`](https://nextmail.sh/docs/ruby/reference/labels#test); PHP [`labels->test`](https://nextmail.sh/docs/php/reference/labels#test); Go [`Labels.Test`](https://nextmail.sh/docs/go/reference/labels#test); Java [`labels().test`](https://nextmail.sh/docs/java/reference/labels#test); C# [`Labels.TestAsync`](https://nextmail.sh/docs/csharp/reference/labels#test). ### `nextmail labels delete` Delete a user label and remove it from every thread ```bash nextmail 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 nextmail labels delete USER_OLD_PROJECT ``` Skip the confirmation, for scripts ```bash nextmail labels delete USER_OLD_PROJECT --yes ``` Also available in: API [`DELETE /labels/{id}`](https://nextmail.sh/docs/api/reference/labels#delete-labels-id); TypeScript [`nextmail.labels.delete()`](https://nextmail.sh/docs/sdk/reference/labels#delete); Python [`labels.delete()`](https://nextmail.sh/docs/python/reference/labels#delete); Ruby [`labels.delete`](https://nextmail.sh/docs/ruby/reference/labels#delete); PHP [`labels->delete`](https://nextmail.sh/docs/php/reference/labels#delete); Go [`Labels.Delete`](https://nextmail.sh/docs/go/reference/labels#delete); Java [`labels().delete`](https://nextmail.sh/docs/java/reference/labels#delete); C# [`Labels.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/labels#delete).