Hand-written commands

With no flags in an interactive terminal it asks how you want to sign in. The browser sign-in opens the Nextmail approval page, where you pick the workspace, the access and how long it lasts, then brings the approval back to the terminal on its own. Over SSH, or with --no-browser, it prints the link and you paste back the code the browser shows. A browser sign-in asks for a verification code before sensitive changes, exactly like the web app. An API key never asks for a code, which makes it the choice for scripts and servers. The sign-in is saved in ~/.nextmail/config.json as a profile, and becomes the active profile only when no other profile is active, so --profile <name> adds a second sign-in without changing what other commands use.

Reads the credential the next command would use, a saved profile, NEXTMAIL_API_KEY or --api-key, and asks the API what it may do: the workspace, the mode, the scopes, any address or domain restriction, and when a browser sign-in expires.

Everything whoami shows, plus the addresses you can send from and the verification state of every domain, read in parallel. A section your credential may not read, for example domains without the domains:read scope, says so instead of failing the whole command.

Sends one email through emails.send. The body comes from --text, --html or both, then --body-file, then anything piped on stdin, and in an interactive terminal from your editor ($VISUAL or $EDITOR). Piped input that starts with an HTML tag is sent as HTML. Without --from you pick one of the addresses you can send from, or the only one is used. A piped body counts as unattended, so the picker is off and --from is needed when you can send from more than one address. --draft sends a saved draft's body, and its subject unless you pass --subject, to the recipients you name. In an interactive terminal you see a summary and confirm before anything goes, unless you pass --yes. Files attached with --attach travel inline while they come to 5 MB or less in total, and are uploaded to Files first and sent by reference when they come to more.

Lists one page of threads, newest first, and reads each one (six at a time) to show when it last moved, who wrote last, the subject, its labels and its id. The folder defaults to the inbox, and sent, archive, starred, snoozed, spam, trash, draft or a label id such as USER_RECEIPTS work too. A dot marks a thread with unread mail. Pass the id to nextmail read to open it.

Prints every message on the thread, oldest first, with who sent it, who it went to, when, the subject, the attachments with their sizes and ids, and the body. A plain text part is shown as it is, and an HTML-only message is turned into readable text: paragraphs, lists, quotes, headings and links as text (url). With --html stdout gets only the raw HTML of one message, so it can be saved to a file, and the headers go to stderr. Reading marks the thread read unless you pass --no-mark-read.

Searches the inbox, or the folder in --folder, and shows the matches like nextmail inbox. Plain words must all appear and match loosely, a quoted phrase must appear as written, and operators such as from:, to:, subject:, has:pdf, is:unread, after:2026/01/31 and newer_than:7d narrow it. A query that names a folder with in: or is: searches there, and in:anywhere searches every folder.

Replies to whoever sent the last message on the thread, or to its Reply-To address, and files the reply into the same thread. When the last message is one you sent, the reply goes to the people it went to. --all copies everyone else on that message, leaving out your own addresses. The subject gets Re: unless it already has it, and the reply is sent from the address the thread was delivered to when you can send from it. The body flags work as they do for nextmail send, including stdin and your editor.

Adds ARCHIVE and removes INBOX, the same pair the app uses, so the threads leave the inbox and stay searchable. Several ids are handled in one run, and each one is reported.

Adds INBOX and removes ARCHIVE, so the threads show in the inbox again.

Adds TRASH and takes the threads out of the inbox, spam, snoozed and archive in one step, like delete in the app. Nothing is deleted, and a snoozed thread loses its wake time. No API call takes a thread back out of the Bin, so you are asked to confirm unless you pass --yes.

Adds the STARRED label, so the threads show under Starred.

Removes the STARRED label.

Removes the UNREAD label from each thread.

Adds the UNREAD label to each thread, so it shows as new again.

Adds SNOOZED, takes the threads out of the inbox and stores when they come back. Threads are woken by an hourly sweep, so one returns up to about an hour after the time you set, always into the inbox. Snoozing a snoozed thread replaces its wake time.

Adds INBOX, removes SNOOZED and clears the wake time, so the threads return straight away. A thread that is not snoozed stays where it is.

Adds every label in --label to each thread. A label id that names no label is refused and nothing on that thread changes, so create it first with nextmail labels create. TRASH, SNOOZED and DRAFT cannot be set here: use nextmail trash or nextmail snooze.

Removes every label in --label from each thread. A label the thread does not carry is not an error.

Creates a disposable address that needs no account and no API key, and keeps its token in ~/.nextmail/temp-mail.json so the other temp commands can reach it. The address is printed on stdout on its own, so ADDRESS=$(nextmail temp new) works in a script. It lives for 60 minutes unless you pass --ttl, up to 24 hours, and nextmail temp-mail extend adds up to an hour at a time within 24 hours of its creation, saving the new token it returns. A name you choose with --name is issued to anyone who asks for it too, so leave it out when the mail should reach you alone.

Lists the inboxes kept in ~/.nextmail/temp-mail.json, soonest to expire last. Expired inboxes are forgotten as they are found, because their tokens no longer open anything. An inbox extended with nextmail temp-mail extend shows its later expiry. Nothing is read from the network.

Without a message id it lists what has arrived, newest first, with a short preview that is often enough to read a one time code. With one it prints the whole message, turning HTML into readable text, and lists its attachments by name and size, without their bytes. The inbox is its id or address, and can be left out when you have only one, so a lone thr_ id reads that message. Reading a message does not mark it seen, and its body is never cut. The sender of mail in a temporary inbox is never verified.

Prints what is already in the inbox, then checks every 3 seconds and prints each new message as it lands, until you press Ctrl+C or the inbox expires. When nextmail temp-mail extend saves a new token for the inbox meanwhile, the watch carries on with it until the later expiry. With --first it stops as soon as there is a message, which suits a script waiting for a sign-up code. With --json each message is one JSON line on stdout.

Moves every message the inbox shows to the bin at once, then removes the inbox and its token from ~/.nextmail/temp-mail.json. Nothing about the lease is stored on the server, so there is nothing to revoke: it runs on until its expiry, and mail that arrives in the meantime still reaches whoever holds the token. Nothing holds the address back either, so it can be issued again at once, to anybody. You are asked to confirm unless you pass --yes.

Runs the same translation a translated send performs and prints the result, so you can read it before anything leaves. Nothing is stored and nothing is sent. The body comes from --text, --html, --body-file (a .html file is sent as HTML, anything else as text) or stdin when it is piped. --text and --html also read a file with @path or stdin with -. Each call spends one AI action, and the credential needs the emails:send scope.

Prints the language table the server translates into, in the order a picker should show it. Any row's code, English name or own name works as --to on nextmail ai translate and nextmail send --translate. Signed out, it prints the table bundled with this version of the CLI.

Asks the Nextmail assistant to write an email body in your own writing style and prints it. Nothing is sent or saved, so pipe it into nextmail send --from <address> when you are happy with it. With --thread the assistant reads the thread first and writes a reply to it. The prompt can also come from stdin. This uses the MCP tool composeEmail, so it needs a browser sign-in (nextmail login) and spends one AI action, plus one for each web search it runs.

Prints the short summary Nextmail keeps for a thread, with its subject, sender and date, and writes it first when there is none yet or new mail has arrived since. A thread holding an encrypted message gets no new summary, and summaries spend no AI actions. This uses the MCP tool getThreadSummary, so it needs a browser sign-in (nextmail login).

Prints what to add to an MCP client so it can read and act on your mail, and which file it goes in. There are two ways to connect. The remote server URL is the simplest: the client opens your browser, you approve it on the Nextmail consent page, and it appears in Account, Connected apps. Each client runs its own browser sign-in for the remote URL. The local bridge (nextmail mcp serve, started through npx) is for clients that only start local servers, and it reuses this CLI's sign-in, so run nextmail login first. With no --client, every client is printed in short form.

Lists every tool the Nextmail MCP server offers to this sign-in, with the first sentence of its description. The list already leaves out tools your role or the app grant cannot use. Name one tool to see its full description and arguments. It needs a browser sign-in (nextmail login).

Calls a tool on the Nextmail MCP server with your browser sign-in and prints the text it returns. --args gives every argument as one JSON object, and each --arg key=value sets or overrides one of them. A value is read as JSON when it parses (--arg maxResults=5 is a number, --arg labelIds='["Label_1"]' a list) and as text otherwise, so quote a number you mean as text (--arg 'id="123"'). A result that starts with Refused ( exits with code 4, and usually means your role or the app grant does not allow the tool. A tool that makes a sensitive change, such as creating a rule or removing a domain, first needs a verification code, as the same change does through the REST API. In an interactive terminal the command asks for the code and then calls the tool again. Unattended it exits with code 4, so run nextmail verify beforehand. The MCP server never asks for confirmation, so a tool that sends or deletes acts at once. Run nextmail mcp tools <tool> to see what a tool takes.

Reads newline-delimited JSON-RPC from stdin, sends each message to the Nextmail MCP server with your saved browser sign-in, and writes each answer to stdout as one line. Notifications produce no output, a batch is split into single requests and answered as one array, and an expired access token is refreshed without the client noticing. Nothing but protocol reaches stdout, and nothing reaches stderr unless you pass --debug, except one hint the first time a tool is refused because it needs a verification code. That refusal reaches the client unchanged, because the bridge cannot ask for a code over stdio. Run nextmail verify in a terminal with the same profile, and tools that make a sensitive change run without a code for the next 60 minutes. It stops when stdin closes. Use it for MCP clients that only start local servers; nextmail mcp config prints the snippet. It needs a browser sign-in (nextmail login), because API keys cannot reach the MCP server.

Sends your question to the Nextmail docs assistant and prints the answer as it is written, followed by the numbered pages it came from. The assistant answers only from the documentation, so it cannot see or change your mailbox. It needs no sign-in and never sends your credentials. Questions are limited to 600 characters and to a daily number per network, so for longer research open the docs with nextmail docs open.

Opens the Nextmail documentation, or the page you name. A slug is the part of the address after /docs/, such as cli/ai-and-mcp, and a full docs link works too. Over SSH, or with --print, it prints the link instead.

Prints the Markdown version of a docs page, the same text the website serves at the page address with .md on the end. It is handy for reading in the terminal or handing a page to another tool. With no slug it prints llms.txt, the index of every page. It needs no sign-in.

Prints a short guide, in Markdown, for an AI agent such as Claude Code or Codex, or a script in CI: how to sign in without a person, why to pass --json and how to read errors and exit codes, how to find commands with --help --json, how to preview a change with --dry-run and when to pass --yes, how lists and streams page, what happens when a verification code or a scope is missing, and a few recipes to copy. With --json it prints the same guide as one JSON document. It needs no sign-in and sends nothing.

With a browser sign-in, a sensitive change such as adding a webhook, creating or turning on a rule, or removing a domain asks for a verification code first, the way the web app does. Commands ask for it when they need it. nextmail verify asks for it now instead: it emails you a code, or asks for one from your authenticator app or a backup code when two-factor sign-in is on, and once the code is right, sensitive commands, nextmail mcp call and nextmail mcp serve run without a code for the next 60 minutes. Run it before a script or an AI client does something sensitive, because neither can type a code. It covers this profile only. An AI client connected through the remote server URL is a connected app of its own, so this does not cover it: allow that app with Allow changes for 60 minutes in its menu under Connected apps on the website (nextmail open apps). --status shows whether this sign-in is verified and until when. A code allows 5 tries. After 10 wrong codes for this sign-in within 24 hours, or 20 across all your connected apps, verification is paused, so the command says when it resumes and exits 4. API keys never need a code.

A browser sign-in is revoked on the server first, which removes it from Account settings, Command line, and then forgotten on this device. The profile is forgotten even when the server cannot be reached, and the command says so. An API key is only forgotten: the key itself keeps working until you revoke it.

Shows every saved sign-in with its kind, workspace and user or key. The active profile is marked with a dot.

Every command without --profile then uses this sign-in. With no name in an interactive terminal it lets you pick one.

The same as nextmail logout --profile <name>: a browser sign-in is revoked on the server, then the profile is forgotten on this device either way.

Prints the profile name on stdout, so $(nextmail profile current) works in scripts. When NEXTMAIL_API_KEY or --api-key is in effect no profile is used, and it says so on stderr.

Opens the web app at the page you name, signed in as whoever is signed in to that browser. Use it for what the CLI does not do, such as account security, deleting your account, linking a DNS provider and talking with the assistant. With no page it opens the mailbox. forwarding takes the address whose forwarding you want to change. A path that starts with / is opened as it is. Over SSH, or with --print, it prints the link instead.

Checks the npm registry now, ignoring the daily cache, and prints the command that installs the latest release with the package manager you used. The CLI never updates itself. When npm has no release of the CLI yet it says so and exits 0, and only a registry it could not reach exits 9.

Prints a completion script built from every command, subcommand and flag this version of the CLI knows. Load it in your shell profile, and run the command again after an update.

Sends one request to the Nextmail REST API through the same transport the other commands use, so your profile or API key, token refresh and verification codes all apply. The path is relative to the API origin, for example /threads or /keys/self, and a path on its own is a GET. A JSON response is printed as formatted JSON, and a file is saved with --out. A failed request prints the API error and exits with the matching code.