Threads, drafts and labels

The mail commands, such as inbox, read, archive and label add, are written for people: they take several thread ids at once, format what they print and keep the label ids out of sight. Each of them runs commands from this page, which are the SDK methods for threads, drafts and labels, one command per method, so threads.listAttachments is nextmail threads list-attachments.

Use these when you need what the mail commands leave out: a thread exactly as the API returns it, the files on a message, drafts, and making, renaming, recolouring or deleting labels.

• —nextmail thread and nextmail draft work as well as the plural names. nextmail labels has no singular form: nextmail label is the mail command that puts labels on threads.
• —The verbs take the usual aliases: ls for list, show and view for get, new and add for create, edit for update, and rm, del and remove for delete.
• —Every flag is in nextmail <namespace> <verb> --help, such as nextmail threads list --help.

Conversations in the mailbox. A thread id such as CAHk7pQ2x9LmZ4 comes from threads list, nextmail inbox or nextmail search.

• —--folder defaults to inbox and is matched as a label id, so sent, archive, spam, trash, draft, snoozed, starred and unread work, bin reads as trash, and a user label id such as USER_RECEIPTS works too. A folder that matches nothing returns an empty page, not an error.
• —--query takes the search syntax of the app, and in:anywhere searches every folder. --label-ids narrows further, since a thread must carry the folder and every id you pass. --date-from and --date-to read the newest message on each thread, and both ends are included.
• —threads get includes unsent draft replies among the messages, marked isDraft: true, and it opens a draft id too.
• —threads update needs --read, --no-read or a label to add or remove. Removals are applied before additions. A label id that names no label is refused with label_not_found and nothing on the thread changes, so create the label first. TRASH, SNOOZED and DRAFT are refused with label_not_directly_settable: use threads trash and threads snooze.
• —threads trash deletes nothing: the thread stays readable with threads get, and threads restore takes it back out of the Bin. Trashing a snoozed thread also cancels its wake, and threads delete removes a thread for good from any folder.
• —threads snooze sends <wake-at> as it is, so give it a future ISO 8601 instant with Z or an offset, since a time without one is read in the time zone of the server. A delay such as 3h is refused as invalid. nextmail snooze --until 3h takes a delay. Threads wake at an hourly sweep, up to about an hour late, and always into the inbox.
• —threads list-attachments returns every file whole in one response. Take the message id from the messages of threads get. content is an empty string when the stored bytes cannot be found, so check its length before decoding.
• —Notes are private to a person. With an API key the note commands read and write the notes of the workspace owner, and after a browser sign-in your own. --color is one of default, red, orange, yellow, green, blue, purple and pink.
• —Comments and assignments belong to the team, and the sender never sees them. 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. Take their ids from threads get-team. With an API key the commands act as the workspace owner, so a comment is theirs. Only its author can change it, and its author or the owner can delete it.
• —A mute applies to everyone on the workspace, and mail addressed only to you does not bring a muted thread back. threads update --add-label-ids MUTE does the same as threads mute, and threads list --query "is:muted in:anywhere" finds the muted threads in every folder.
• —threads list --category promotions reads one inbox tab, and threads counts has a row for each tab under categories. A choice saved with threads set-sender-category wins over the sorting rules. A workspace holds at most 2,000 choices, and a sign-in or key limited to particular addresses can read them but not change them.

Unsent messages saved in the mailbox. A draft id starts with draft-.

• —drafts list --query searches the subject, the sender and the start of the body, and never leaves drafts. older_than:30d and the other date operators read when the draft was last saved, and to:, cc: and bcc: match nothing on a draft.
• —A draft is stored as a thread labelled DRAFT, so threads get opens one and nextmail inbox draft lists them. drafts get, update and delete refuse an ordinary thread id with a 404.
• —A bare nextmail drafts create saves a blank draft. Only lengths are checked: a subject up to 998 characters, and --html and --text up to 1,000,000 each, with --html kept when both are set. There is no flag for attachments.
• —drafts update replaces each field you send. A list replaces the stored one whole, so --to with one address drops the others. The attachment list stays as it is, and a draft that forwards a message keeps forwarding it unless --thread-id moves it to another thread.
• —--thread-id records the thread a draft replies to, but the draft is still stored as a thread of its own.
• —Running drafts create again saves a second draft, because it takes no idempotency key. A display name with a comma in it splits into two broken recipients, so leave the comma out.
• —nextmail send --draft <id> --to <address> sends a draft. The body comes from the draft, and so does the subject unless you pass --subject, while the recipients are the ones you name. It cannot be combined with a body, --template or --translate.
• —drafts create --thread-id <id> --forward-of <message-id> saves a forward of a message in that thread, with Fwd: in front of its subject unless you pass --subject. Without --thread-id, or with a message the thread does not hold, it is 422 invalid_parameter. Sending it with nextmail send --draft <id> --to <address> quotes the message below the body and attaches its files.

The labels a thread can carry. A user label id is USER_ followed by the name it was created with, upper cased, with each run of whitespace turned into _, so Big Clients is USER_BIG_CLIENTS.

• —An id never changes, even after a rename, so store ids rather than names.
• —System labels such as INBOX, STARRED and UNREAD are not listed and cannot be changed or deleted, though threads update takes them. labels get on one is a 404.
• —A workspace holds up to 50 user labels. A name another label already has, compared without case, is refused with label_name_taken.
• —A colour is a hex value such as #3B82F6 or a gradient token such as gradient:sunset. --label-color takes the whole colour as JSON, and --label-color null clears it.
• —A label belongs to the workspace, so renaming, recolouring or deleting it changes it for everyone in it.
• —labels delete has no undo. Creating a label with the same name again gives the same id, but the threads do not get it back. Its threadCount in labels get says how many conversations will lose it.
• —labels create and labels update take --ai-instructions, what the label is for in plain words and at most 500 characters, and --ai-enabled, which has AI add the label to arriving mail that fits. It needs a paid plan, or the command is refused with 403 plan_required, and a workspace may have 10 such labels, with 422 ai_label_limit_reached past that.
• —labels test spends one AI action of the caller, which the labelling of arriving mail never does. With none left today it stops with 429 ai_quota_exceeded.

• —A mail command takes several thread ids and reports on each one, and with --json it prints { results, succeeded, failed }. A command on this page takes one id and prints what the API returns.
• —nextmail inbox reads every thread it lists to show who wrote last and the subject. threads list makes one request per page and prints only ids, which is all a pipeline needs.
• —nextmail read turns an HTML message into text and marks the thread read. threads get prints the thread as the API returns it and changes nothing.

Mark a thread read, archive it and label it in one request, where mark read, archive and label add would make three:

nextmail threads update CAHk7pQ2x9LmZ4 --read --add-label-ids ARCHIVE,USER_RECEIPTS --remove-label-ids INBOX --json

Make a label and file every matching thread under it. Piped, --all prints one JSON object per line:

nextmail labels create --name Receipts --color-background-color gradient:meadownextmail threads list --query "in:anywhere subject:receipt newer_than:1y" --all | jq -r .id | xargs nextmail label add --label USER_RECEIPTS

Save one file from a message. The message ids are on the messages of threads get:

nextmail threads get CAHk7pQ2x9LmZ4 --json | jq -r ".messages[].id"nextmail threads list-attachments CAHk7pQ2x9LmZ4 message_4c1b257a --json | jq -r '.[] | select(.filename == "invoice.pdf") | .content' | base64 --decode > invoice.pdf

Write a draft, change it, read it back, then send it:

DRAFT=$(nextmail drafts create --to grace@example.com --subject "Engine notes for Thursday" --html "<p>Agenda below.</p>" --json | jq -r .id)nextmail drafts update "$DRAFT" --to grace@example.com,charles@example.comnextmail drafts get "$DRAFT"nextmail send --draft "$DRAFT" --from you@acme.com --to grace@example.com,charles@example.com

Clear out drafts nobody has saved for 30 days. The dry run prints each DELETE without sending it, and --yes answers the confirmation:

nextmail drafts list --query older_than:30d --all | jq -r .id > stale.txtxargs -n 1 nextmail drafts delete --dry-run < stale.txtxargs -n 1 nextmail drafts delete --yes < stale.txt

Pick a gradient from the palette, preview the change, make it, and later take the colour off again:

nextmail labels list-colors --json | jq -r '.[] | select(.kind == "gradient") | .value'nextmail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:aurora --dry-runnextmail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:auroranextmail labels update USER_RECEIPTS --label-color null

A missing scope stops with exit code 4. None of these commands asks for a verification code, with a browser sign-in or with an API key.

A sign-in or key limited to some addresses sees only the threads delivered to them, and any other thread is a 404, as if it did not exist. Labels belong to the workspace, so it still sees every label, but threadCount counts only the conversations it can see.

• —threads list, drafts list and labels list read one page, 25 unless --limit says otherwise, up to 100. --cursor carries on from the cursor a page printed. A thread cursor keeps the order it was handed out in, so send the same filters with it.
• —--all reads every page and --max <n> stops after that many. Piped or with --ndjson it prints one JSON object per line, and with --json one { items, hasMore, nextCursor } document.
• —hasMore can be true on what turns out to be the last page, and the next call then returns no items. A thread that gets new mail while you page moves ahead of the cursor and is not returned by later pages, and so does a draft saved while you page.
• —threads trash, threads delete, drafts delete and labels delete ask you to confirm. Unattended, with --json, --no-input or no terminal, they stop with exit code 2 and change nothing unless you pass --yes.
• —--dry-run prints the request a command would send, with the credential redacted, and exits with code 0 without sending it or asking to confirm. With --json it prints { dryRun, request }.
• —threads clear-sender-category and follow-ups cancel ask you to confirm as well, and stop the same way unattended unless you pass --yes.

--data takes the whole body as JSON, inline, from a file with @path, or from stdin with -, and a flag you pass as well overrides its key.

An empty flag value is a usage error, so a field that an empty value clears goes through --data instead. --label-color null clears a label’s colour.

nextmail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"from":""}'nextmail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"threadId":""}'nextmail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"to":[]}'nextmail drafts create --data @draft.json --subject "Overrides the file"

The first saves the draft with no sender, the second detaches it from the thread it replied to, and the third clears its recipients.

nextmail threads --helpnextmail threads list --helpnextmail drafts create --help --json

nextmail <namespace> <verb> --help shows each argument and flag with its type, the scopes the call needs, its method and path, what it returns and the notes from the API reference. Add --json for the same help as data.

nextmail encryption manages the OpenPGP public keys that let senders seal mail to your addresses, the Encryption page of the app. Only public keys pass through it: the private key stays on the device that made it.

• —--public-key @key.asc reads the armored key from a file, and - reads it from stdin.
• —With an API key the commands act on the keys of the workspace owner, and after a browser sign-in on your own.

• —Each person reaches only their own chats: an API key reaches the chats of the workspace owner, and a browser sign-in reaches the chats of the person who signed in.

The newsletters and mailing lists the mailbox receives, what is known about the organisation behind a sender, and the numbers behind the Analytics page of the app.

• —subscriptions list, list-domains, senders get, senders research and analytics mailbox need threads:read, and analytics sending needs emails:read. Unsubscribing and moving need threads:write, and the rule subscriptions move makes needs rules:write too.
• —A sender that only offers an unsubscribe page answers with method link and the page in url, which a person has to open.
• —subscriptions unsubscribe, unsubscribe-domain and threads unsubscribe ask you to confirm, since an unsubscribe cannot be taken back. Unattended they stop with exit code 2 unless you pass --yes.
• —Only the workspace owner may run senders research, with a key or a sign-in not limited to particular addresses or domains, and a workspace looks up at most 200 new domains a day.

nextmail follow-ups holds the reminders set on mail you sent, the ones “Remind me if nobody replies” makes in the app. If no real reply has arrived by the time of a reminder, its thread returns to the top of the inbox, unread.

• —--remind-at takes a future ISO 8601 instant with Z or an offset, at most 365 days out, and anything else is 422 invalid_follow_up. nextmail emails send --follow-up-at sets a reminder as the mail goes out, and also takes a duration such as P3D.
• —A real reply closes a reminder by itself, and automatic replies, delivery reports and mail from your own sending address do not count as one. With an API key the commands act on the reminders of the workspace owner, and after a browser sign-in on your own.
• —nextmail threads list --query "is:waiting in:anywhere" finds, in every folder, the threads whose reminder nobody has answered yet.