client.labels
Every method in this namespace: its signature, its parameters, what it returns and an example.
Methods
The labels a thread can carry.
labels.list
List the workspace's labels, a page at a time
list(limit: nil, cursor: nil, api_key: nil) -> Nextmail::PageReturns one page of the workspace's user labels, sorted by name and then by id. list_all collects every page and iterate walks them lazily. 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 nil 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.
Parameters
limitIntegerPage size, from 1 to 100. The server defaults to 25.
cursorStringThe
next_cursorof the previous page, passed back as it came. Leave it out for the first page.api_keyStringOverrides the client API key for this call only.
Returns
The Nextmail::Page of Hashes, with items, has_more? and next_cursor. Each item has id, name, type, color, threadCount, createdAt and updatedAt.
Example
page = client.labels.list(limit: 50) page.items.each { |label| puts "#{label[:name]} #{label[:threadCount]}" } puts "more after #{page.next_cursor}" if page.has_more?Notes
Labels belong to the workspace, so a narrowed key still sees every label.
threadCountis the exception: it counts only conversations delivered to the addresses the key holds.An id is fixed when the label is created and survives a rename, so match on
idrather thannamein stored configuration.The sidebar order in the app is each person's own arrangement and is not exposed.
The cursor is opaque and holds where the last row sat in this order, so a row deleted or edited between pages never breaks the walk: the next page starts at the first row that sorts after it. A cursor this list did not hand out is a 400
invalid_cursor.
Also available in
- API
GET /labels- TypeScript
nextmail.labels.list()- Python
labels.list()- PHP
labels->list- Go
Labels.List- Java
labels().list- C#
Labels.ListAsync- CLI
openemail labels list
labels.list_all
Collect every label into one array
list_all(limit: nil, cursor: nil, api_key: nil) -> Array<Hash>Walks every page of list and returns all labels, sorted by name and then by id. One request per page.
Parameters
limitIntegerPage size for each request, from 1 to 100. The server defaults to 25.
cursorStringStarts the walk after this cursor instead of the first page.
api_keyStringOverrides the client API key for every page of this walk.
Returns
An Array of Hashes holding every label.
Example
labels = client.labels.list_all(limit: 100)receipts = labels.find { |label| label[:name] == "Receipts" } client.threads.update("CAHk7pQ2x9LmZ4-mail.example.com", addLabelIds: [receipts[:id]]) if receiptsNotes
If any page fails the call raises and the labels already fetched are discarded.
Also available in
- API
GET /labels- TypeScript
nextmail.labels.listAll()- Python
labels.list_all()- PHP
labels->listAll- Go
Labels.ListAll- Java
labels().listAll- C#
Labels.ListAllAsync
labels.iterate
Stream the labels one at a time
iterate(limit: nil, cursor: nil, api_key: nil, &block) -> Enumerator<Hash>Returns an Enumerator that yields labels one at a time, sorted by name and then by id, and requests the next page only once the current one is drained. Given a block, it yields each label to the block instead. Nothing is fetched until you consume it, and breaking out of the loop stops the requests.
Parameters
limitIntegerPage size for each request, from 1 to 100. The server defaults to 25.
cursorStringStarts the walk after this cursor instead of the first page.
api_keyStringOverrides the client API key for every page of this walk.
Returns
An Enumerator of Hashes, one label per step (or yields each one to a block).
Example
client.labels.iterate do |label| puts "unused #{label[:name]}" if label[:threadCount] == 0endNotes
The Enumerator is lazy, so an abandoned loop costs only the pages you consumed.
Also available in
- API
GET /labels- TypeScript
nextmail.labels.iterate()- Python
labels.iterate()- PHP
labels->iterate- Go
Labels.Iterate- Java
labels().iterate- C#
Labels.IterateAsync
labels.list_colors
List the colours the app offers for labels
list_colors(api_key: nil) -> Array<Hash>Returns 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.
Parameters
api_keyStringOverrides the client API key for this call only.
Returns
An Array of Hashes, each with kind, name, value, solid, from, to and textColor.
Example
colors = client.labels.list_colorssunset = colors.find { |color| color[:name] == "sunset" } client.labels.create(name: "Launch", color: {backgroundColor: sunset ? sunset[:value] : "#EF4444"})Notes
kindissolidorgradient.fromandtoare nil on a solid.
Also available in
labels.get
Read one user label by id
get(id, api_key: nil) -> HashLooks 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.
Parameters
idStringRequiredLabel id such as
USER_RECEIPTS, matched case sensitively.api_keyStringOverrides the client API key for this call only.
Returns
A Hash with id, name, type set to user, color, threadCount, createdAt and updatedAt.
Example
label = client.labels.get("USER_RECEIPTS") puts label[:name], label.dig(:color, :backgroundColor) || "no colour", label[:threadCount]Notes
A missing label raises
Nextmail::NotFoundError,Nextmail::ApiErrorwithnot_found?true and coderesource_not_found.
Also available in
- API
GET /labels/{id}- TypeScript
nextmail.labels.get()- Python
labels.get()- PHP
labels->get- Go
Labels.Get- Java
labels().get- C#
Labels.GetAsync- CLI
openemail labels get
labels.create
Create a user label
create(body = nil, api_key: nil, **fields) -> HashCreates a label and returns 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. list_colors 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.
aiInstructions says what the label is for in plain words, such as invoices and receipts. With aiEnabled 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 aiEnabled on needs instructions and a paid plan, and a workspace may have 10 such labels. Without instructions it is a 422 invalid_parameter on aiInstructions, on the free plan a 403 plan_required, and past the tenth a 422 ai_label_limit_reached.
Parameters
nameStringRequiredDisplay name, trimmed, 1 to 225 characters. Also decides the id.
colorHashThe colour. Leave it out for a label with no colour.
color.backgroundColorStringA hex colour such as
#3B82F6or a gradient token such asgradient:sunset, at most 32 characters. Required oncecoloris given.color.textColorStringAccepted and ignored. The ink is worked out from
backgroundColor.aiInstructionsString or nilWhat the label is for, in plain words, up to 500 characters, such as
invoices and receipts.aiEnabledBooleanHave 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.api_keyStringOverrides the client API key for this call only.
Returns
A Hash with the new id, the trimmed name, color, threadCount of 0, aiInstructions, aiEnabled, createdAt and updatedAt.
Example
label = client.labels.create(name: "Big Clients", color: {backgroundColor: "gradient:aurora"}) puts label[:id], label.dig(:color, :textColor)Notes
The SDK does not retry a create after a network failure. If you retry by hand after a lost response, a 409
label_name_takenmeans the first attempt succeeded.The label is created before its AI settings are saved, so a create refused with
plan_required,ai_label_limit_reachedorinvalid_parameteronaiInstructionsleaves the label in place with no instructions andaiEnabledoff. Set them withupdaterather than creating it again.testruns the instructions over recent mail and shows what they would catch, without labelling anything.
Also available in
labels.update
Rename or recolour a user label
update(id, patch = nil, api_key: nil, **fields) -> HashRenames a label, recolours it, or changes what AI does with it, and returns it as it is stored. Send any of name, color, aiInstructions and aiEnabled: a field left out stays as it is, and a patch with none of them is a 422. color: nil, 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 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. 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 aiInstructions, on the free plan a 403 plan_required, and past the tenth a 422 ai_label_limit_reached. aiInstructions: nil clears the instructions, which also turns aiEnabled off.
Parameters
idStringRequiredLabel id such as
USER_RECEIPTS.nameStringNew display name, trimmed, 1 to 225 characters. Left out, the name stays.
colorHash or nilNew colour.
nilclears it, and leaving it out keeps the stored colour.color.backgroundColorStringA hex colour or a gradient token, at most 32 characters. An empty string clears the colour.
color.textColorStringAccepted and ignored. The ink is worked out from
backgroundColor.aiInstructionsString or nilWhat the label is for, in plain words, up to 500 characters.
nilclears it, which also turnsaiEnabledoff. Left out, it stays.aiEnabledBooleanWhether 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.api_keyStringOverrides the client API key for this call only.
Returns
A Hash with the unchanged id and the new name, color, aiInstructions and aiEnabled.
Example
saved = client.labels.update("USER_RECEIPTS", color: {backgroundColor: "#EA9602"}) puts saved[:id], saved[:name], saved.dig(:color, :backgroundColor)Notes
The SDK retries this call after a network failure, since the same patch sent twice leaves the same label.
testruns instructions over recent mail and shows what they would catch, so you can try wording before you save it here.
Also available in
labels.test
Try a label on recent mail
test(id, body = nil, api_key: nil, **fields) -> HashRuns the AI over the newest 20 inbox threads and returns the 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, and a key limited to particular addresses reads only the threads delivered to them.
Parameters
idStringRequiredLabel id such as
USER_RECEIPTS, aslistreturns it.aiInstructionsStringWhat the label is for, in plain words, 1 to 500 characters. Left out, the instructions saved on the label are tried.
api_keyStringOverrides the client API key for this call only.
Returns
A Hash with object set to label_test, labelId, examined and matched. examined is how many recent threads were read, and each match is a Hash with threadId, subject, sender and receivedOn, with sender the address the newest message is from and receivedOn when it arrived, as its Date header gives it, or nil.
Example
result = client.labels.test("USER_RECEIPTS", aiInstructions: "invoices and receipts") puts "#{result[:matched].size} of #{result[:examined]} would get the label" result[:matched].each { |match| puts "#{match[:sender]} #{match[:subject]}" }Notes
Needs both
labels:writeandthreads:read. An unknown label id is a 404.With no instructions to try, neither in the call nor on the label, it is a 422
invalid_parameter. A spent AI allowance is a 429ai_quota_exceeded, and a 409ai_not_configuredwhile AI is unavailable.Nothing is saved: the label keeps the instructions it had. Save the wording with
updateonce it catches what you want.The SDK does not retry it, because each call spends an AI action.
Also available in
- API
POST /labels/{id}/test- TypeScript
nextmail.labels.test()- Python
labels.test()- PHP
labels->test- Go
Labels.Test- Java
labels().test- C#
Labels.TestAsync- CLI
openemail labels test
labels.delete
Delete a user label and remove it from every thread
delete(id, api_key: nil) -> HashDeletes 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.
Parameters
idStringRequiredLabel id such as
USER_OLD_PROJECT.api_keyStringOverrides the client API key for this call only.
Returns
A Hash with object set to label, the id and deleted set to true.
Example
removed = client.labels.delete("USER_OLD_PROJECT") puts removed[:id], removed[:deleted]Notes
The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
getfirst if you want to say how many conversations will lose the label: itsthreadCountis that number.