Labels
Every operation in this group: what it accepts, what it returns and the errors it can answer with.
Operations
The names a conversation can be filed under, several at once. Labels belong to the workspace, so every member and every key sees the same set, and renaming or deleting one changes it for everybody.
A label's id comes from the name it was created with and never changes, so a rename keeps every conversation labelled. Its colour is a hex value or one of seven gradient tokens, and GET /labels/colors lists the palette the app offers. Apply and remove labels on a conversation with PATCH /threads/{id}. GET /threads?folder=USER_BIG_CLIENTS lists every conversation carrying a label, and labelIds narrows a folder to the ones carrying it.
GET/labels
List labels
Every user label in the workspace, sorted by name and then by id, a page at a time: follow nextCursor while hasMore is true to read them all. Each row carries its colour, how many conversations carry it and when it was created and last changed, 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 PATCH /threads/{id} takes them, but they cannot be renamed, recoloured or deleted.
The order the app's sidebar shows is each person's own arrangement and is not exposed here.
Requires the labels:read scope.
Query parameters
limitintegerRows per page, 1 to 100.
At least 1At most 100Default25cursorstringThe previous page's
nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400invalid_cursor.
Returns
A page of labels, by name.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.labels.list()nextmail.labels.listAll()nextmail.labels.iterate()- Python
labels.list()labels.list_all()labels.iterate()- Ruby
labels.listlabels.list_alllabels.iterate- PHP
labels->listlabels->listAlllabels->iterate- Go
Labels.ListLabels.ListAllLabels.Iterate- Java
labels().listlabels().listAlllabels().iterate- C#
Labels.ListAsyncLabels.ListAllAsyncLabels.IterateAsync- CLI
openemail labels list- MCP
getLabelgetUserLabels
POST/labels
Create a label
Creates a label and answers with it. The id comes from the name (Big Clients becomes USER_BIG_CLIENTS) and never changes afterwards. A workspace holds at most 50 labels.
Leave color out for a label with no colour, or send color.backgroundColor as a hex value or a gradient token. GET /labels/colors lists the swatches the app offers.
Requires the labels:write scope.
Request body
namestringRequiredTrimmed, then 1 to 225 characters. Also decides the id, which never changes afterwards.
1 to 225 characterscolorLabelColorInputThe colour. Leave it out for a label with no colour.
aiInstructionsstringWhat the label is for, in plain words, up to 500 characters, such as
invoices and receipts.Can be nullUp to 500 charactersaiEnabledbooleanHave AI apply the label to arriving mail that fits
aiInstructions. It needs instructions and a paid plan, and a workspace may have 10 such labels.
Returns
Created, read back as it is stored.
Errors
- 409
label_name_taken: another label already has that name, compared without case, or already holds the id this name gives because it was created under it and renamed since.- 422
label_limit_reachedonce the workspace holds 50 labels, orinvalid_parameterfor a colour that is neither a hex value nor a gradient token.
The errors every operation can return400401403404429500Error catalog
Also available in
- TypeScript
nextmail.labels.create()- Python
labels.create()- Ruby
labels.create- PHP
labels->create- Go
Labels.Create- Java
labels().create- C#
Labels.CreateAsync- CLI
openemail labels create- MCP
createLabel
GET/labels/colors
List label colours
The fourteen solid colours and seven gradients the app offers when you make or edit a label, in the order it shows them. Each one says what to send as color.backgroundColor, the ink drawn on it, and for a gradient the colour at each end and one solid hex for places a gradient cannot go.
A fixed catalogue with no paging. Fetch it once and keep it. A label may also carry any other hex, set through this API, which the app keeps and offers back as its own swatch.
Requires the labels:read scope.
Returns
The whole palette.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
GET/labels/{id}
Retrieve a label
One label by id, in the same shape as a row of the list. Ids are matched exactly, and a system id such as INBOX is a 404.
Requires the labels:read scope.
Path parameters
idstringRequiredLabel id such as
USER_RECEIPTS, matched case sensitively.
Returns
The label.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.labels.get()- Python
labels.get()- Ruby
labels.get- PHP
labels->get- Go
Labels.Get- Java
labels().get- C#
Labels.GetAsync- CLI
openemail labels get- MCP
getLabelgetUserLabels
PATCH/labels/{id}
Rename or recolour a label
Renames a label, recolours it, or changes what AI does with it. Send any of name, color, aiInstructions and aiEnabled; a field left out stays as it is, and color: null or an empty backgroundColor clears the colour. The id never changes, so every conversation keeps the label through a rename.
With aiEnabled on, AI reads each arriving message against aiInstructions 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.
A key limited to particular addresses or domains, and the access token of an app anybody but the workspace owner connected, also need the settings:write scope, because a label belongs to the whole workspace.
Requires the labels:write scope.
Path parameters
idstringRequiredLabel id such as
USER_RECEIPTS.
Request body
namestringThe new name, trimmed, 1 to 225 characters. Left out, the name stays.
1 to 225 characterscolorobjectThe new colour.
nullclears it. Left out, the colour stays.Can be nullbackgroundColorstringRequiredA hex colour (
#RGB,#RGBA,#RRGGBBor#RRGGBBAA), stored upper-cased, or a gradient token:gradient:sunset,gradient:ember,gradient:meadow,gradient:lagoon,gradient:aurora,gradient:berry,gradient:midnight. The app's solid swatches are#EF4444,#F97316,#EA9602,#DCB30B,#79BB19,#2EB45C,#00AD9B,#09A9CA,#3B82F6,#6366F1,#8B5CF6,#D946EF,#EC4899,#64748B, and any other hex is kept as it is. An empty string means no colour. Anything else is a 422invalid_parameteroncolor.backgroundColor.Up to 32 characterstextColorstringAccepted and ignored. The ink is worked out from
backgroundColor.Up to 32 characters
aiInstructionsstringWhat the label is for, in plain words, up to 500 characters.
nullclears it, which also turnsaiEnabledoff. Left out, it stays.Can be nullUp to 500 charactersaiEnabledbooleanWhether AI applies the label to arriving mail that fits
aiInstructions. Turning it on needs instructions and a paid plan, and a workspace may have 10 such labels. Left out, it stays.
Returns
Saved, read back as it is stored.
Errors
- 403
plan_required: turningaiEnabledon needs a paid plan.- 409
label_name_taken: another label already has that name, compared without case.- 422
invalid_parameterfor a body with none ofname,color,aiInstructionsandaiEnabled, a colour that is neither a hex value nor a gradient token, oraiEnabledturned on with no instructions.ai_label_limit_reachedwhen the workspace already has as many labels that AI applies as it may.
The errors every operation can return400401404429500Error catalog
Also available in
- TypeScript
nextmail.labels.update()- Python
labels.update()- Ruby
labels.update- PHP
labels->update- Go
Labels.Update- Java
labels().update- C#
Labels.UpdateAsync- CLI
openemail labels update- MCP
updateLabel
DELETE/labels/{id}
Delete a label
Deletes the label and takes it off every conversation that carried it, in one step. The conversations stay in whatever folder they were in. There is no undo: creating the same name again gives the same id, but the conversations do not get the label back.
A key limited to particular addresses or domains, and the access token of an app anybody but the workspace owner connected, also need the settings:write scope, because a label belongs to the whole workspace.
Requires the labels:write scope.
Path parameters
idstringRequiredLabel id such as
USER_OLD_PROJECT.
Returns
Deleted.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.labels.delete()- Python
labels.delete()- Ruby
labels.delete- PHP
labels->delete- Go
Labels.Delete- Java
labels().delete- C#
Labels.DeleteAsync- CLI
openemail labels delete- MCP
deleteLabel
POST/labels/{id}/test
Try a label on recent mail
Runs the AI over the newest 20 inbox threads and says which ones the label would catch, without labelling anything. Send aiInstructions 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.
Requires the labels:write and threads:read scopes.
Path parameters
idstringRequiredThe label, as
GET /labelslists it.
Request body
aiInstructionsstringWhat the label is for, in plain words, 1 to 500 characters. Left out, the instructions saved on the label are tried.
1 to 500 characters
Returns
What the label would catch.
Errors
- 409
ai_not_configured: AI is unavailable right now.- 422
invalid_parameter: there are no instructions to try, neither in the request nor on the label.- 429
ai_quota_exceeded: today's AI actions are used up.rate_limited: the key or app made more than 600 requests in 60 seconds. Wait for the seconds inRetry-After.
The errors every operation can return400401403404500Error catalog
Also available in
- TypeScript
nextmail.labels.test()- Python
labels.test()- Ruby
labels.test- PHP
labels->test- Go
Labels.Test- Java
labels().test- C#
Labels.TestAsync- CLI
openemail labels test- MCP
testLabel
Objects
DeletedLabelobject
objectstring- One of
"label" idstringdeletedboolean- One of
true
Labelobject
objectstring- One of
"label" idstringFixed when the label is created:
USER_and the name upper-cased, with each run of spaces turned into_, soBig ClientsisUSER_BIG_CLIENTS. It never changes, so a renamed label keeps the id of its first name. Store the id rather than the name.namestringtypestringAlways
user. System labels such asINBOX,STARREDandUNREADare never listed, though a thread carries them andPATCH /threads/{id}takes them.One of"user"colorobjectHow the label is painted. Null on a label saved with no colour.
Can be nullbackgroundColorstringThe stored colour: a hex value such as
#3B82F6, stored upper-cased, or a gradient token such asgradient:sunset.GET /labels/colorslists the palette the app offers, with the two ends of every gradient.textColorstringThe ink the app draws on that colour,
#18181Bor#FFFFFF. Worked out here frombackgroundColorand never stored, so atextColoryou sent is not echoed.
threadCountintegerConversations carrying the label now, the number the Labels table in the app shows. A key limited to particular addresses counts only conversations delivered to them.
aiInstructionsstringWhat the label is for, in plain words, such as
invoices and receipts. WithaiEnabledon, AI reads each arriving message against it. Null when none was written.Can be nullaiEnabledbooleanWhether AI applies the label to arriving mail that fits
aiInstructions. It only ever adds the label, and never archives or moves mail.createdAtstringNull on a label made before these times were recorded.
Can be nullFormatdate-timeupdatedAtstringThe last rename or recolour. Null on a label made before these times were recorded.
Can be nullFormatdate-time
LabelColorEntryobject
objectstring- One of
"label_color" kindstring- One of
"solid""gradient" namestringThe swatch name, such as
redorsunset.valuestringWhat to send as
color.backgroundColorto use this swatch.One of"#EF4444""#F97316""#EA9602""#DCB30B""#79BB19""#2EB45C""#00AD9B""#09A9CA""#3B82F6""#6366F1""#8B5CF6""#D946EF""#EC4899""#64748B""gradient:sunset""gradient:ember""gradient:meadow""gradient:lagoon""gradient:aurora""gradient:berry""gradient:midnight"solidstringOne hex for places a gradient cannot be drawn, such as an icon. The same as
valueon a solid.fromstringWhere a gradient starts, drawn at 135 degrees. Null on a solid.
Can be nulltostringWhere a gradient ends. Null on a solid.
Can be nulltextColorstringThe ink the app draws on this swatch.
LabelColorInputobject
backgroundColorstringRequiredA hex colour (
#RGB,#RGBA,#RRGGBBor#RRGGBBAA), stored upper-cased, or a gradient token:gradient:sunset,gradient:ember,gradient:meadow,gradient:lagoon,gradient:aurora,gradient:berry,gradient:midnight. The app's solid swatches are#EF4444,#F97316,#EA9602,#DCB30B,#79BB19,#2EB45C,#00AD9B,#09A9CA,#3B82F6,#6366F1,#8B5CF6,#D946EF,#EC4899,#64748B, and any other hex is kept as it is. An empty string means no colour. Anything else is a 422invalid_parameteroncolor.backgroundColor.Up to 32 characterstextColorstringAccepted and ignored. The ink is worked out from
backgroundColor.Up to 32 characters
LabelColorListobject
objectstring- One of
"list"
LabelListobject
objectstring- One of
"list" dataLabel[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null
LabelTestobject
objectstringRequired- One of
"label_test" labelIdstringRequiredexaminedintegerRequiredHow many recent threads were read.
matchedobject[]RequiredThe threads the label would catch. A workspace may have 10 labels that AI applies.
threadIdstringRequiredsubjectstringRequiredsenderstringRequiredThe address the newest message is from.
receivedOnstringRequiredWhen that message arrived, as its Date header gives it.
Can be null