Files, imports and settings

Five namespaces cover what sits around the mail itself. nextmail files is the Files page: every attachment sent and received and every file uploaded, with its bytes and the download links it went out as. nextmail imports brings an old mailbox into one address, and nextmail provider-imports brings an account across from Resend, SendGrid, Postmark, Mailgun or Mailchimp. nextmail calendar reads the events found in mail, and nextmail settings reads and changes the mailbox preferences and the signature and tracking of each address.

• —An id says what it names: file_ for a file, imp_ for a mailbox import, pimp_ for an import from another provider and cal_ for a calendar event, each followed by 24 hex characters. A download link has an id of its own, from files list-links or files create-link.
• —--address-id on an import is the id of an address, from nextmail domains list-addresses <id>, not the address itself.
• —The namespaces also answer to file, import, provider-import or providerImports, and setting. Verbs take the usual aliases where they have them: ls for list, show and view for get, new and add for create, edit for settings update, and rm, del and remove for files delete.
• —None of these commands asks a browser sign-in for a verification code. The ones that change something for good ask you to confirm, and --yes answers for a script.
• —nextmail <command> --help lists every argument and flag with its type, the scope the call needs, its method and path, and what comes back. Add --json for the same page as data.

nextmail files reads and manages every file the mailbox holds: attachments that came in, attachments that went out, and files uploaded to the Files page. nextmail open files opens the same page in the web app.

• —files list narrows with --q (the name and the type), --kind (image, pdf, audio, video or text), --direction (inbound, outbound or uploaded), --address, --since and --until, and sorts with --sort (newest, oldest, largest or name). --since and --until take an ISO 8601 date or date-time: --since includes its moment and --until stops before it.
• —Only an upload that nothing depends on can be deleted, and deletable says so ahead of time. usage says what keeps any other file: received, sent, linked for an upload whose download link still works, or scheduled for one attached to a message that has not gone out. delete refuses those with 409 file_in_use. delete-many deletes what it can, lists the rest in kept with a reason each, and lists unknown ids in missing.
• —upload reads the file at the path you give and stores it under that file’s name, with the type its extension implies. --filename and --content-type override them. From stdin, - needs --filename, and without --content-type the type is application/octet-stream. The upload waits up to 10 minutes, which --timeout-ms changes.
• —The id upload returns attaches the file to a send as { "fileId": "…" } in nextmail emails send --attachments, which is how a file over the 10 MB inline limit goes out.
• —An empty file is 400 upload_empty, a program or script (judged by its name) is 400 upload_dangerous, and a file over 100 MB is 413 upload_too_large. A workspace keeps as many uploads as its plan allows, from 10 GB on Free to 1 TB on Enterprise, and takes 500 uploads an hour.
• —download needs --out <file> on a terminal and stops with exit code 2 without it. Piped, the bytes go to stdout, and --out - asks for stdout too. The whole file is held in memory.
• —create-link makes a new link on every call, with its own download count, and the link works until it is revoked or the file is deleted. It lives on the files domain of --domain when that domain has one, such as files.acme.com, else on the files domain of the file’s address, else on the API address. A program or script is refused with 422 file_unshareable.
• —revoke-link is safe to repeat: a link already revoked comes back unchanged.
• —A key or sign-in limited to particular addresses or domains sees only the files that arrived at them, never the files uploaded for the whole workspace, and its own uploads belong to the first address it holds.
• —The files index starts on the day it shipped. Older attachments are still on their messages, where nextmail threads list-attachments <id> reads them.

nextmail imports brings an old mailbox into one address: Google Takeout archives, .mbox files from Apple Mail, Thunderbird and most desktop apps, .eml files, and .zip or .tgz archives holding any of those, up to 100 GB a file and 50 files an import. Threads, dates and labels come across. Imported mail is quiet: it runs no rules, forwards, notifications, summaries or webhooks.

import-files is the one most people need: it creates the import, uploads every file in parts with a progress line, and starts it. The other verbs are those steps one at a time, for finishing an upload that stopped or for driving it yourself. create returns the plan, chunkBytes and each file’s chunks, upload-chunk sends one part, upload-state says which parts arrived, and start queues the import. nextmail open imports shows the same imports in the web app.

• —The address has to be one on the workspace’s own domains that the key or sign-in may act for. Only one import runs per address: another while one is queued or running is 409 already_running.
• —import-files takes --files once per file, or several paths separated by commas, and sends each under its own file name. --options takes JSON such as {"keepInbox":false,"includeSpam":true}. On create the same three are switches: --options-keep-inbox, --options-include-spam and --options-include-trash, each turned off with --no- in front, as in --no-options-keep-inbox.
• —keepInbox is on by default, so mail from the old inbox lands in Inbox with its unread state. Off files everything under Archive. Spam and trash stay behind unless you include them.
• —create takes --files as JSON, inline or from a file with @path, and each bytes must be the exact size of the file you then upload.
• —Each part is exactly chunkBytes long, except the last part of a file, and a part of the wrong length is 400 bad_chunk. start refuses a file with parts missing with 412 missing_chunks, and one that is not an archive or a mailbox with 400 unsupported_file. On an import that already left uploading, it returns the import unchanged.
• —If a part still fails after its retries, import-files stops with the import left in uploading. The block below sends the missing parts of the first file and starts it.
• —An import reports processedBytes out of totalBytes, and counts with seen, imported, duplicate, filtered, failed and threads. lastError is set only when status is failed.
• —list-failures gives each failure a reason: too-large (over 50 MB), unparseable, no-date, storage-error, unreadable-entry, encrypted-entry or archive-limit, with the subject and sender where they could be read.
• —cancel on a finished import is 409 not_cancellable. delete-upload cancels an import that is still uploading, and refuses one that is queued or running with 409 still_running, so cancel that first.

nextmail imports get "$import_id" --json > import.jsonnextmail imports upload-state "$import_id" --json > state.jsonchunk=$(jq .chunkBytes import.json)chunks=$(jq '.files[0].chunks' import.json)for i in $(seq 0 $((chunks - 1))); do  jq -e --argjson i "$i" '.received[0] | any(. == $i)' state.json > /dev/null && continue  dd if=takeout-001.zip bs="$chunk" skip="$i" count=1 2> /dev/null |    nextmail imports upload-chunk "$import_id" 0 "$i" -donenextmail imports start "$import_id"

nextmail provider-imports moves a workspace across from Resend, SendGrid, Postmark, Mailgun or Mailchimp with one API key, and --provider says which. Suppressions keep their reason, segments and lists become audiences, subscribed contacts arrive with their names, and templates arrive as HTML templates with their variables declared. Webhooks are registered switched off, because deliveries here are signed differently. A signing key or a token cannot leave the provider that made it, so domains and API keys come back as a checklist in the report instead.

• —Pass the provider key as @path to read it from a file, or as - to read it from stdin, so it stays out of your shell history and the process list. A key typed on the command line still works, with a warning. --dry-run prints the body with the key redacted.
• —--resources takes any of suppressions, audiences, contacts, templates, webhooks, domains and api-keys, comma separated or repeated.
• —A key that can only send is 400 restricted_key. Create one with more access at the provider for the import, and revoke it afterwards.
• —inspect reads the first page of each resource and returns resources, what the key can bring across, and counts, one { count, more } per resource, with more set where a resource runs past its first page.
• —One import runs per workspace at a time, and a second is 409 already_running. Running the same import twice duplicates nothing. The key is held encrypted only while the import runs, and is erased when it ends, fails or is cancelled.
• —Contacts who unsubscribed at the provider are left out and counted in report.contacts.unsubscribed.
• —report.domains lists each domain at the provider with a state: absent when it is not in this workspace, added when it is but is not verified, and verified, with the records it had there. Add a missing one with nextmail domains create. report.apiKeys names the keys to create again with nextmail keys create.
• —With a browser sign-in only the workspace owner may use these commands, and a member gets 403 owner_only. An API key is not held to that. A key or sign-in limited to particular addresses or domains cannot inspect or create an import, since audiences, suppressions and templates belong to the whole workspace.
• —create also needs the scope of each resource it brings in: audiences:write for audiences, contacts:write and audiences:write for contacts, templates:write for templates, webhooks:write for webhooks and domains:read for domains.
• —--provider takes resend, sendgrid, postmark, mailgun or mailchimp, and defaults to resend. Resend needs a full-access key, SendGrid a key with read access, Postmark a Server API token, Mailgun a private API key from either region, and Mailchimp an API key ending in its datacenter, such as -us6.
• —What a provider has no such thing for, or the key cannot read, is left out of resources and of the import. Postmark keeps domains and sender signatures behind an Account token, which the import does not take, and Mailchimp has no webhooks for sending events and does not list its API keys.
• —SendGrid hands out contacts through an export it prepares first, so the contacts step waits for it. Mailchimp shares only the editable sections of a template, which arrive as a draft.

nextmail calendar reads and changes the calendar. list-events expands every event into its occurrences inside a window you give, so a weekly meeting is one row per week, and get-event and get-event-ics read one event whole. Five more change events as the Calendar page does, the feed commands manage the links that publish the calendar, the subscription commands manage the other calendars you subscribe to, and nextmail threads get-event reads the event a thread carries. nextmail open calendar opens the calendar in the web app.

• —--from and --to are ISO 8601 date-times such as 2026-10-01T00:00:00Z. --to must be after --from and at most 366 days later, since a repeating series has no end to list up to. A missing bound is 422 invalid_parameter. A bound that does not parse, a reversed or overlong window, or an unknown zone is 400 invalid_parameter.
• —--timezone is an IANA zone such as Europe/London, UTC when left out. It expands the events stored without a zone of their own, which decides the day an all-day event lands on.
• —get-event and get-event-ics take the eventId of an occurrence, not the iCalendar uid. A recurring series is one event, so its start and end describe the first instance.
• —Cancelled events are listed too, with status CANCELLED. myPartstat is the answer recorded for any address the workspace holds on its own domains, and null when none of them is an attendee.
• —Paging carries on with --cursor and the same window. A key or sign-in limited to particular addresses sees only the events one of them organises or attends, and any other event is a 404.
• —get-event-ics declares METHOD:PUBLISH, so importing it shows the event as it stands rather than offering to accept or decline. Timed events are written in the zone they were made in, with the rules of that zone attached, and all-day events as dates. A repeating series comes with its changed and cancelled instances. DTSTAMP is the time of the download, so two downloads of an unchanged event differ on that line.
• —Changing needs calendar:write. Inviting, updating or cancelling a meeting with attendees, and every answer, goes out by email, so it needs emails:send too, and --from has to be an address the key may send as. --no-send-invites keeps a change to your own calendar.
• —The feed and subscription commands need calendar:read to list and calendar:write to change, and a key limited to particular addresses or domains cannot use them, because they cover the whole calendar. decline-proposal emails the guest, so it needs emails:send too.

nextmail settings reads and changes the mailbox preferences, such as timezone, time format and the blocklists. An address can have its own signature, openEmailSignature (the Nextmail footer), trackOpens and trackClicks, and an address or a whole domain its own externalImages, trustedSenders and blocklist. Name the address with --address, *@acme.com for the catch-all of a domain, or @acme.com for the whole domain.

• —Without --address, get reads the four per-address settings as the built-in defaults: no signature, the Nextmail footer on, and open and link tracking off. With it they come from the address’s own values, then from its domain’s catch-all when the catch-all caught that address, then from the defaults. A plus address with no settings of its own reads its base address’s.
• —Without --address, update refuses --signature, --nextmail-signature, --track-opens and --track-clicks with 422 address_required and writes nothing. With an address or a catch-all it takes those four, --external-images, --trusted-senders and the blocklist, with @domain the last three only, and anything else is 422 not_per_address. The address has to be in this workspace, a catch-all needs a verified domain here with its catch-all on, and @domain a domain in this workspace.
• —Every switch turns off with --no- in front, such as --no-track-opens or --no-external-images.
• —--signature is HTML of at most 150,000 characters, sanitised on write, so what comes back is what will be sent. An empty string removes it. Whether a send adds it is up to the send: see --signature in nextmail emails send --help.
• —Every setting has its own flag, such as --time-format, --week-start or --undo-send-enabled, and --data takes them as JSON instead, inline, from a file with @path or from stdin with -. Without --address, keys the settings do not know are dropped without an error. A known key with the wrong type is 422 invalid_parameter.
• —A list such as blockedDomains is replaced whole, so read it first and send it back with your change, as the example below does. A blocklist entry too short to be a rule is 422 blocklist_entry_too_broad.
• —--timezone is saved as given, without checking, so check a zone before you send it.
• —Without --address, the privacy fields (externalImages, trustedSenders, blockedSenders, blockedDomains, blockedWords, useDefaultBlockedWords, semanticSearch, replySuggestions and knowledgeLearning) and --workspace-name belong to the workspace, and a key or sign-in limited to particular addresses or domains cannot change them. With --address it may name only an address it holds, or a catch-all or a domain it holds whole. Either refusal is 422 capability_unsupported.
• —An update with nothing in it changes nothing and returns the current settings. defaultEmailAlias only preselects the From address in the web app composer, and the API never uses it to choose a sender.
• —null in --data removes a value the scope sets itself, so --address [email protected] --data '{"externalImages":null}' makes the address inherit externalImages again. get lists what a scope sets itself under overrides.
• —Three switches belong to your account, not to the workspace. --inbox-tabs shows the inbox as Primary, Promotions, Updates, Social and Forums, --primary-only-alerts keeps notifications to Primary mail while the tabs are on, and --phone-follow-ups sends a push when a reminder comes due with no reply.

nextmail out-of-office reads and sets the automatic reply an address sends while its owner is away, the Out of office tab of an address in the app. It is saved for one address, or for the catch-all of a domain written *@acme.com.

• —--message is plain text of 1 to 10,000 characters. Without --starts-at a new reply starts now and a reply that is already on keeps its start, and without --ends-at it stays on until it is switched off. Changing the start begins a new away period in which everyone is answered once more. --no-enabled saves the text and keeps the reply paused.
• —Each sender is answered once for the whole away period. Spam, newsletters and other bulk mail, automatic mail, bounces, blocked senders and the workspace’s own addresses get no reply, and --contacts-only answers only contacts and people the workspace has written to.
• —active in the answer says whether mail arriving now is answered. A sign-in or key limited to particular addresses or domains reaches only the addresses it holds, and a catch-all only when it holds the domain whole.

file_id=$(nextmail files upload ./price-list.pdf --json | jq -r .id)nextmail files create-link "$file_id" --domain acme.com --json | jq -r .urlnextmail files list-links "$file_id"nextmail files download "$file_id" --out copy.pdf

Each create-link makes a new link, so run it once and read the link back with list-links. revoke-link stops it later, in mail that already went out as well.

nextmail files list --direction uploaded --all | jq -r 'select(.deletable) | .id' > deletable.txtwc -l < deletable.txtxargs -r -n 100 nextmail files delete-many --yes --json < deletable.txt | jq -c '.kept[]'

With --all in a pipe, files list prints one file per line. xargs -n 100 hands delete-many at most 100 ids a call, and any file that became used in between comes back in kept with its reason rather than failing the call.

domain_id=$(nextmail domains list --all | jq -r 'select(.domain == "acme.com") | .id')address_id=$(nextmail domains list-addresses "$domain_id" --all | jq -r 'select(.address == "[email protected]") | .id')nextmail imports import-files --address-id "$address_id" --files ~/Downloads/takeout-001.zip --files ~/Downloads/takeout-002.zip --json > import.jsonimport_id=$(jq -r .id import.json)until nextmail imports get "$import_id" --json | jq -e '.status != "queued" and .status != "running"' > /dev/null; do  sleep 60donenextmail imports get "$import_id" --json | jq '{status, counts, lastError}'nextmail imports list-failures "$import_id" --json | jq -r '.data[] | [.reason, .subject] | @tsv'

--dry-run on import-files prints the POST /imports it would send, with each file’s name and size, and uploads nothing. list-failures reads 100 at a time: pass the nextCursor it printed as --after for the next page.

nextmail provider-imports inspect @resend-key.txtnextmail provider-imports create --provider-key @resend-key.txt --resources suppressions,audiences,contacts,templates,webhooks,domains,api-keys --json > resend.jsonpimp_id=$(jq -r .id resend.json)until nextmail provider-imports get "$pimp_id" --json | jq -e '.status != "queued" and .status != "running"' > /dev/null; do  sleep 10donenextmail provider-imports get "$pimp_id" --json | jq '.report | {contacts, domains: [.domains[] | {name, state}], apiKeys: [.apiKeys[].name]}'

nextmail calendar list-events --from 2026-10-01T00:00:00Z --to 2026-11-01T00:00:00Z --timezone Europe/London --all |  jq -r 'select(.status != "CANCELLED") | [.start, .summary, .myPartstat] | @tsv'nextmail calendar get-event cal_8d3f0a2b9c4e41f7a6b5c2d1 --json | jq '.attendees[] | {email, partstat}'nextmail calendar get-event-ics cal_8d3f0a2b9c4e41f7a6b5c2d1 --out standup.ics

nextmail settings get --address [email protected] --json | jq '{signature, openEmailSignature, trackOpens, trackClicks}'nextmail settings update --address [email protected] --signature "$(cat signature.html)" --no-track-clicks --dry-runnextmail settings update --address [email protected] --signature "$(cat signature.html)" --no-track-clicksnextmail settings update --address '*@acme.com' --no-track-opensnextmail settings update --address @acme.com --no-external-imagesnextmail settings update --timezone Europe/Londonnextmail settings get --json | jq -c '{blockedDomains: ((.blockedDomains + ["spam.example"]) | unique)}' |  nextmail settings update --data -

The dry run prints the PATCH /settings?address=sales%40acme.com and its body without sending it. The catch-all line sets tracking for every address the catch-all of acme.com picks up, and the last line adds one domain to the blocklist without dropping the others.

• —A sign-in or key without the scope stops with exit code 4, names the missing scope and says how to get it.
• —files revoke-link, files delete, files delete-many, imports cancel, imports delete-upload and provider-imports cancel ask you to confirm. Answering no exits with code 10 and changes nothing. Unattended and without --yes, they stop with exit code 2 before anything is sent.
• —No command here asks for a verification code, with a browser sign-in or an API key, so --yes is all a script needs.
• —--dry-run prints the request a change would send, with its body, and exits with code 0 without sending it or asking you to confirm. A file body is shown as its size and type.
• —files list, files list-links, imports list, provider-imports list and calendar list-events read one page: --limit takes 1 to 100 and the server sends 25 when it is left out, and --cursor takes the nextCursor of the page before. --all reads every page, --max <n> stops after that many items, and --ndjson, or --all in a pipe, prints one JSON object per line. With --json they print one { items, hasMore, nextCursor } document.
• —imports list-failures pages its own way: --after takes the nextCursor of the page before, --limit is at most 100, the default, and there is no --all. With --json it prints { object, data, nextCursor }.
• —Reads and the changes that land the same way twice are retried after a network failure: files revoke-link, imports upload-chunk, imports start and settings update. Every other change is sent once. After a lost answer, look before trying again: a second upload stores a second copy and a second create-link makes a second link, a 404 on your second files delete means the first one worked, and a second delete-many lists what the first deleted in missing.
• —A refusal exits with the code of its status: 4 for a 403, 5 for a 404, 6 for a 409, 7 for a 400 or a 422, and 8 for a 429.