nextmail labels

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 <n> stops after that many items.

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.

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.

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.

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.

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.

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.