nextmail threads

Returns one page of threads from the mailbox index, ordered by each thread's latest message with the newest first unless sort says otherwise. A row is only object and id, so call get for the messages, labels and unread state.

sort, --date-from, --date-to and --from-contacts are the thread list's own controls: the four orders, a date range read against the newest message on each thread, and a filter to mail from saved contacts. Every order pages to the end, and a cursor carries on in the order it was handed out in, so send the same filters with it.

folder defaults to inbox and is matched against label ids after being upper cased, so sent, archive, spam, trash, draft, snoozed, starred and unread all work, bin is read as trash, and a user label id works as a folder too. A name that matches nothing returns an empty page rather than an error. --label-ids narrows the folder further: a thread must carry the folder label and every id you pass. category keeps one inbox tab, primary, promotions, updates, social or forums, where primary is every thread in no other tab.

query takes the mailbox search syntax. Plain words must all appear, and each matches loosely: case, accents and separators are ignored and part of a longer word counts, so min finds "Benjamin". A quoted phrase is matched as written apart from case and accents, so "ben jamin" does not find "Ben-Jamin" while "quarterly invoice" finds "Quarterly invoice". When nothing matches exactly, close spellings are returned instead, so benjimin finds "Benjamin": a plain word, or the value of from:, to:, cc:, subject:, body:, filename: or label:, may differ from the start of a word by one typo when it has four to seven letters and by two when it has eight or more, while a quoted phrase, a word containing a digit, a shorter word and an excluded word still match exactly, and the pages that follow keep matching the same way. Filler words such as the, about or emails are dropped from a list of plain words when something else is left to search for, so emails from john searches for john alone. Operators such as from:, to:, subject:, label:, is:unread, has:pdf, after:2026/01/31 and newer_than:7d narrow it, and OR, parentheses and a leading - combine them. is:muted finds muted threads, is:waiting the threads with a reminder nobody has answered yet, and category:promotions one inbox tab in any folder. Recipients are stored as one list without roles and never hold a Bcc, so cc: reads the same field as to: and bcc: matches nothing of its own. from:me is mail you sent, and to:me is mail carrying one of your own addresses, aliases included, among its recipients or as the address it was delivered to.

With semantic: true the plain words of query match by meaning rather than spelling. Describe the mail in a few words, flight to Berlin or invoices I still owe, in any language, and the threads closest in meaning come back best match first, together with every thread the words match as text, which ranks above one that only means the same. A thread is kept only when it is clearly closer to the words than the rest of the mailbox, so a description nothing fits returns only the text matches. Operators and filters narrow it as usual, sort does not apply, and a query with no plain words is a text search whatever semantic says. Meaning is read from the whole conversation, newest messages first, so an earlier message counts too, and a workspace that turned search by meaning off in its settings gets a text search instead.

Words and the from:, to:, cc:, subject: and body: operators read only the newest message on each thread: its sender, its recipients, its subject and the first 4,000 characters of its body with markup stripped. filename: and has: read every attachment on the whole conversation, and label:, in: and is: read the whole conversation. A plain word also matches the name of any attachment on the conversation, whichever message carried it. A sealed message has no body text to match. The search stays inside folder unless the query names a folder itself, with in: or a folder is: such as is:sent, and in:anywhere searches every folder, on its own as well as beside other terms. A drafts listing is the exception and stays in drafts whatever the query names.

Dates read the newest activity on the thread, in UTC. after: includes the day it names and before: excludes it, and a date can be written YYYY/MM/DD, YYYY-MM-DD, YYYYMMDD, as a bare year, or as epoch seconds or milliseconds. A short date reads day first (16/09/2026), unless the second number cannot be a month (09/16/2026), and a number above 12 settles it either way. The API pages with an opaque pageToken, which the SDK hands back as nextCursor and accepts as --cursor.

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.

Returns the whole conversation, oldest message first, with the labels the thread sits in and its unread state. Unsent draft replies are included in messages with isDraft: true, which is why messageCount, the length of messages, can be higher than totalReplies, which counts only real messages.

Messages are passed through as the mailbox stored them, so MessageResource is an open record rather than a fixed field list. The one field the API commits to is encryption. When encryption.format is pgp-mime, pgp-inline or smime-encrypted, the message is sealed and its body is empty or holds armour. pgp-signed and smime-signed are ordinary readable mail. A message with no encryption at all was stored before detection existed, so its absence says nothing about whether it was plaintext.

Each message's tags and unread are overwritten on read with the thread's current labels and unread flag, so they describe the thread and not that one message.

Adds and removes labels on a thread in one call. read is shorthand for the UNREAD label: true removes it and false adds it. At least one of read, a non empty --add-label-ids or a non empty --remove-label-ids is required, each list takes at most 50 ids, and any other key is a 422 because the body is strict.

Folders are labels too, so archiving is addLabelIds: ['ARCHIVE'] with removeLabelIds: ['INBOX'], the same pair the app uses. TRASH, SNOOZED and DRAFT are refused in either list with 422 label_not_directly_settable, because each needs a step this route cannot take. Use trash and snooze for those.

User label ids come from labels.list, and the system ids such as ARCHIVE, STARRED and UNREAD are taken in any case. An id in --add-label-ids that names no label is refused with 422 label_not_found and nothing on the thread changes, so create the label with labels.create first. An unknown id in --remove-label-ids is not an error, since the thread cannot carry it. Removals are applied before additions, so an id in both lists ends up on the thread.

Adds TRASH and removes INBOX, SPAM, SNOOZED and ARCHIVE in one step, which is what the app's delete does. Doing half of that through update would leave the thread listed in both the Bin and its old folder, which is why update refuses TRASH.

Nothing is deleted. The thread stays readable with get and lists under folder: 'trash'. Calling this on a thread that is already in the Bin changes nothing and returns the same body, which is why the SDK retries it.

Adds SNOOZED, removes INBOX and stores a wake time, all in one call. Both halves matter: the label hides the thread and the stored wake time is what brings it back. A thread labelled SNOOZED any other way would never return, which is why update refuses that label.

wakeAt takes a Date or an ISO 8601 string. The SDK converts a Date with toISOString(), and the server answers 422 invalid_parameter on wakeAt when the value does not parse or is not in the future. Snoozing a thread that is already snoozed replaces its wake time.

Threads are woken by an hourly sweep, so one comes back at the first sweep after wakeAt, up to about an hour late. Opening the Snoozed folder in the app wakes overdue threads straight away. A thread always wakes into the inbox.

Adds INBOX, removes SNOOZED and deletes the stored wake time, so the thread returns immediately and the hourly sweep leaves it alone afterwards.

A thread that is not snoozed is left where it is, so an archived thread stays archived, and the response still reports snoozedUntil: null.

Mutes a conversation, as Mute does in the app. A thread in the inbox moves to the archive, and from then on new mail in it goes straight to the archive, unread, with no push, sound or desktop notice. A webhook for that mail carries muted: true.

Thread state belongs to the whole workspace, so the thread is muted for everyone on it, and mail addressed only to you does not bring it back. Calling it again changes nothing, which is why the SDK retries it. update with MUTE in addLabelIds does the same.

Takes the mute off, so the next message in the thread arrives in the inbox and alerts people again.

The thread stays where it is. Move it back with update and INBOX in addLabelIds if you want it in the inbox now. A thread that is not muted is left as it is, which is why the SDK retries this call.

Returns every message on the thread, oldest first, as MailboxMessageResource: from, to, cc, bcc and replyTo as { name, email }, date as an ISO 8601 instant, messageId, inReplyTo and references, the body as text and html, the attachments without their bytes, the headers Nextmail keeps and encryption. Unsent draft replies are in the list with draft: true.

These fields are a contract: they are added to, never renamed or taken away, whatever the mailbox stores underneath. threads.get still returns each message the way the mailbox stored it, so use this when your code reads messages field by field.

text is the plain text body, or the text drawn from the HTML when the message came as HTML only. html is null for a plain text message. headers holds From, To, Cc, Reply-To, Subject, Date, Message-ID, In-Reply-To, References, List-Unsubscribe and List-Unsubscribe-Post when the message had them, and nothing else, because the rest of what it arrived with is not kept.

Returns one message as MailboxMessageResource, the shape listMessages lists. The thread is checked first and then the message, so a messageId that is not on that thread is a 404 even when it exists elsewhere in the mailbox.

The emailId of an email.received webhook is the messageId to pass here, beside its threadId.

Returns the attachments of one message with each file's bytes inlined as base64 in content. The thread is checked first and then the message, so a messageId that is not on that thread is a 404 even when it exists elsewhere in the mailbox. Take message ids from the messages of threads.get.

This is the display list. The ciphertext of an encrypted envelope is in it and downloads like any other file, named encrypted-message.asc when it arrived without a name. The PGP/MIME version part and any detached signature are held out on purpose. Every part keeps its id in the message's encryption.parts, and for those two the id is a correlation key only: no route returns their bytes.

Every file comes back whole in a single response, with no size cap and no range reads, so a message carrying large files makes a large response.

Resolves every note on one thread, the Notes panel of the reading pane: pinned notes first, then the rest in the order they were arranged.

Notes are private to a person. A key reads and writes the notes of the workspace owner, and an app those of the person who connected it. A key limited to particular addresses reaches only the notes on threads that arrived at them.

Pins a private note to a thread, as the Notes panel does. A new note goes after the others, and pinned keeps it at the top.

Notes are private to a person. A key reads and writes the notes of the workspace owner, and an app those of the person who connected it. A key limited to particular addresses reaches only the notes on threads that arrived at them.

Changes the text of a note, its colour or whether it is pinned. Give at least one of the three. A note id that is not on this thread is a 404, even when the note exists on another thread.

Deletes a note for good. There is no bin for notes.

Sets the order of every note on a thread at once, first to last, as dragging them in the Notes panel does. Pinned notes still come first.

ids has to name every note on the thread exactly once. Anything else is a 422 invalid_parameter on ids, and nothing moves.

Resolves what the sidebar of the app shows: how many conversations each folder holds and how many of them are unread, how many drafts are waiting, how many conversations each of your labels has in each folder, how many inbox conversations sit in each inbox tab, and how many inbox conversations arrived at each address of the workspace.

folders has one row per folder, named by its label id in lower case: inbox, sent, spam, archive, trash and snoozed, then draft, whose count is the drafts waiting to be sent and whose unread is always 0, then unread, whose count is the unread conversations in the inbox. labels has one row for each of your labels and each folder it has conversations in, { id, folder, count, unread }, so a label with nothing in a folder has no row for it. categories has one row for each inbox tab, { category, count, unread }, counting inbox conversations only: primary, promotions, updates, social and forums, where primary is everything not sorted into another tab. unlabelled counts the inbox conversations that carry none of your labels, with count, unread and the same count for each tab under categories, which is what the inbox of the app lists unless Labelled mail is ticked in its Filters menu. addresses counts the inbox per address the mail was delivered to, with null for mail that recorded none. team counts the team views of a shared inbox for the person the key or app acts for: assigned the open conversations assigned to them, unassigned the open conversations nobody has, each with count and unread, and mentions the conversations outside Spam and the bin where a team comment mentions them, with count, unread and unseen, the conversations with a mention newer than the last time they opened its comments in the app. A conversation is open while it is in the inbox.

A key limited to particular addresses counts only the mail that arrived at them and the drafts written from them. address narrows every count to one address, and one the key does not reach counts nothing rather than failing.

Resolves the short AI summary the reading pane shows above a thread. A summary is written the first time it is asked for and then kept, and the first request after a newer message arrives writes it again, so reading one is cheap.

state is ready with the text in summary, pending while the first one is being written, failed when the last try did not work, or none when there is nothing to summarise, such as a thread holding a message that arrived encrypted, whose body Nextmail never reads. While a newer summary is being written, the one before it comes back as ready. A pending answer starts the writing, so ask again a few seconds later, and after a failed one asking again tries once more.

Resolves up to three short replies to the latest message of the thread, the ones the reading pane offers under it. Each has a label, a few words that say what it answers, and a body, the reply itself in plain text, ready to send with emails.send or to keep with drafts.create. They are written in the language of that message and the voice of the mail this workspace sends, from the conversation, what was written to this correspondent before, what is known about their organisation and, when the message asks for a time, the busy times of the calendar.

Suggestions are written once for each new message and kept, so asking again is free until another message arrives. state is ready with the suggestions, pending while they are being written, so ask again a few seconds later, or none when the message needs no reply: your own reply came last, or it is a newsletter, an automated notice, mail from a no-reply address, spam or an encrypted message. Every thread is none in a workspace that turned replySuggestions off with settings.update.

sources names the knowledge base items the suggestions drew on: the pinned notes at the levels of the receiving address and the items whose passages matched the message, each a KnowledgeSourceRef with id, title, kind, scope and url. It is empty when none were used.

Puts a thread back in the inbox, out of the Bin and out of Spam, which is what Restore from Bin and Move to inbox do in the app. It is the undo of trash.

Calling it on a thread that is already in the inbox changes nothing and returns the same body, which is why the SDK retries it.

Deletes every message in a thread, with its attachments, which is what Delete from Bin does in the app. It cannot be undone.

It works on a thread in any folder, so call trash instead when you only mean to throw the thread away: a trashed thread stays readable and restore brings it back.

Does what the Unsubscribe button of the reading pane does: finds the subscription behind the newest message of the thread that carries a List-Unsubscribe header and unsubscribes from it the way the sender asks for, with a one-click request or an unsubscribe email. A sender that only offers a page cannot be unsubscribed by a program, so method is link and url is the page a person has to open.

A thread with no unsubscribe header is a 422 unsubscribe_unsupported, and a thread delivered to no address the key covers is a 404.

Returns the calendar event that came with an invitation in the thread, as the invitation card of the reading pane shows it. Answer it with calendar.respondToEvent.

Resolves the senders whose mail always goes to one inbox tab, by address. New mail is sorted into Primary, Promotions, Updates, Social or Forums by plain rules, and a choice saved here wins over them. list takes category to read one tab.

The choices belong to the workspace and apply to every address in it. A workspace holds at most 2,000 of them, and they come back as one plain array with no paging.

Saves the tab for one sender and moves the inbox threads whose newest message is from them, up to the newest 1,000, into it. Mail from them is sorted there from now on, whatever the rules would say. Saving again replaces the choice.

A workspace holds at most 2,000 choices, and the call past that is a 422 sender_category_limit_reached. They apply to every address in the workspace, so a key or an app limited to particular addresses or domains can read them but not change them, and gets a 422 capability_unsupported.

Removes the choice, so new mail from the sender is sorted by the rules again. Threads already sorted stay where they are.

Resolves the thread as the team sees it: who it is assigned to, who marked it done, how many comments it has, who else is writing a reply in the app right now, and everyone who can see it.

Only people who can see a thread can be given it or mentioned on it: the workspace owner, members who reach every address, and members who hold its address or its domain. A key acts for the workspace owner.

Gives the thread to one person, who is emailed unless they assigned it to themselves.

Only people who can see a thread can be given it or mentioned on it: the workspace owner, members who reach every address, and members who hold its address or its domain. A key acts for the workspace owner.

Leaves the thread with nobody.

Archives the thread for everyone and records who marked it done. A new reply brings it back to the inbox, and reopen moves it back by hand.

Moves a done thread back to the inbox for everyone.

Resolves the team comments on one thread, oldest first. Everyone who can see the thread reads them, and the sender never does.

Adds a comment for the team. Everybody in mentions is emailed.

Only people who can see a thread can be given it or mentioned on it: the workspace owner, members who reach every address, and members who hold its address or its domain. A key acts for the workspace owner.

Replaces the text and the mentions of a comment. Only its author can change it, and anybody newly mentioned is emailed.

Deletes a comment for good. Its author can delete it, and so can the workspace owner, which a key acts for.