Commands

nextmail <command> [subcommand] [arguments] [flags]

• —Flags go anywhere after the command, before or after the arguments. Global flags such as --profile and --json may also come before it, and any other flag placed there stops with a hint to move it after the command name.
• —A value follows its flag after a space or an equals sign, so --limit 50 and --limit=50 are the same. Short flags take values too, as in -n 50.
• —A value that starts with a dash needs the equals sign, as in --subject=-draft-, because after a space it reads as the next flag and the first one is reported as missing its value. Negative numbers work either way. An empty value is a usage error rather than a quiet default.
• —A switch is on with --flag and off with --no-flag, and --flag=true and --flag=false work too.
• —A list is comma separated or repeated: --to ada@example.com,bob@example.com, or --to twice.
• —Everything after -- is an argument and never a flag, which is how a search for -from:ada gets through.
• —An unknown command or flag stops with exit code 2 and suggests the closest match.

These are written for people: they ask for what is missing, format what they print, and combine several API calls where that helps.

Every method of the SDK is also a command, nextmail <namespace> <verb>. The namespace is the SDK namespace in kebab case, and the verb is the method name in kebab case, so keys.listRequests is nextmail keys list-requests. Together they cover the whole REST API.

nextmail domains listnextmail domains create --domain acme.comnextmail rules create --data @rule.jsonnextmail keys list-requests 9f2c1a4b7e05d3862c1f0a44 --failed-only --allnextmail files download file_6bb640f5b99e47deb758f1f5 --out report.pdf

• —An id the method takes is an argument, as in nextmail domains get <id>. Each field of the request body is a flag named after it in kebab case: replyTo is --reply-to, and color.backgroundColor is --color-background-color.
• —Three fields whose flag would clash with a global flag are renamed: --template-version, --label-color and --provider-key. The provider key, in --provider-key and in provider-imports inspect, also takes - for stdin or @path for a file, which keeps it out of your shell history.
• —--data takes the whole body as JSON, inline, from a file with @path, or from stdin with -, and any flag you pass as well overrides its key. A flag that takes an object reads JSON the same way.
• —Numbers and switches are read as such, and lists are comma separated or repeated.
• —A missing required value is asked for in a terminal, and is a usage error (exit code 2) anywhere else.
• —A list verb reads one page. --limit sets its size and --cursor carries on from the cursor it printed. --all reads every page and streams the items, --max <n> stops after that many, and --ndjson prints one JSON object per line. With --json it prints one { items, hasMore, nextCursor } document, --all included.
• —Anything destructive, such as deleting, revoking, rotating, cancelling or emptying, asks you to confirm, unless you pass --yes.
• —A download is written to the file in --out, and to stdout only when stdout is not a terminal.
• —A table fits the terminal. When even the narrowest columns do not fit, the last ones are left out, and a note names them.

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.

Also lists the other names a namespace answers to.

Each area has a page of its own, with every command in its namespaces, the scopes they need and worked examples. Every command is also on one page of its own, with the endpoint and scope of each.

In members and suppressions, whose verbs are add and remove, new and create lead to add, and rm, del and delete lead to remove. A few hand-written subcommands have aliases of their own, which their help lists.

nextmail api <method> <path> sends one request to the REST API through the same transport as every other command, so your profile or key, token renewal and verification codes all apply. A path on its own is a GET. A JSON answer prints formatted, and a failed request prints the API error and exits with the matching code.

nextmail api /keys/selfnextmail api GET /threads --query folder=inbox --query limit=5nextmail api POST /labels --data '{"name":"Receipts"}'nextmail api PATCH /threads/CAHk7pQ2x9LmZ4 --data @patch.jsonnextmail api GET /files/file_6bb640f5b99e47deb758f1f5/content --out report.pdf

• —-d, --data takes the body as inline JSON, from a file with @path, or from stdin with -. -q, --query and -H, --header take key=value and can be repeated, and -o, --out saves the answer to a file as it came.
• —The path is relative to the API origin. A full URL, a path that would leave the origin and an Authorization header are refused with exit code 2 before anything is sent, because the CLI sets the credential itself.
• —A DELETE, and any call a resource command would confirm, such as revoking or rotating a key, cancelling a send or sending a broadcast, asks you to confirm first. Unattended it stops with exit code 2 unless you pass --yes.

nextmail --helpnextmail help sendnextmail domains --helpnextmail domains create --helpnextmail domains create --help --json

nextmail --help lists every command by what it is for. A group lists its subcommands with examples, and a command shows everything it takes. nextmail docs open cli opens these pages.

Add --json to any of them and the same help prints as one JSON document, with every argument, flag, scope and example, for a script or an AI agent to read. The For AI agents page describes its fields.