Domains and addresses

Three namespaces cover your domains. nextmail domains manages the domains attached to the workspace: adding and removing them, the DNS records each one needs, whether it can receive and send, its catch-all, its tracking and files domains, its logo, and the addresses on it. nextmail addresses answers a narrower question: which addresses the key or sign-in you are using may send as. nextmail app-host manages the web app address of the workspace, a subdomain of one of its domains where its people open Nextmail.

• —A domain command takes the domain id, a UUID from domains list or domains create. The hostname is not accepted in its place, so nextmail domains get acme.com is a 404 and exits with code 5.
• —An address command takes the domain id and then the address id, a UUID from domains list-addresses or domains create-address.
• —domain and address work as namespace names too. The domain verbs answer to the usual aliases, such as ls, show, new, edit and rm, and so does addresses list. The verbs for the addresses on a domain, such as create-address, and for its logo, such as set-logo, have none.
• —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.

A domain reports two independent facts. receiving.verified is true once public DNS answers with its MX records and its _openemail-challenge TXT record, and from then on it receives mail. sending.status is the signing state as the last check saw it: verified, pending, failed, no_identity or unknown. sending.canSend says whether a send from the domain would be accepted right now, and a negative verdict older than a day counts as unknown, so a script should branch on canSend rather than on status. While it is false, a send from the domain is refused with 409 domain_not_sendable.

• —domains create runs the first DNS check during the call, so each entry in records already carries a status: found, missing, or null when it has not been checked yet. Publish every record exactly as given, since the values are specific to the domain.
• —domains verify checks straight away. Within 10 seconds of the last check it checks nothing new and returns the domain as it stands. On a verified domain it checks the signing records again, so sending is fresh.
• —domains get on an unverified domain checks again when the last check is more than 20 seconds old, so polling get also works and needs only domains:read, where verify needs domains:write.
• —A record published a moment ago can take a few minutes to show up in public DNS.

On a terminal, get, create and verify print one field per line, with nested blocks such as receiving, sending and records as compact JSON. Add --json and read them with a tool such as jq, as the examples below do.

domains update changes three settings that do not depend on each other. A flag you leave out is left alone, and with no flags at all the domain comes back unchanged.

• —A new host is saved and checked in the same call. Publish a CNAME record named record.name with the value record.value from the tracking or storage block of the answer, with any proxying turned off. Setting a host up again can give it a different value, so publish the one the latest answer reports.
• —Until a check passes, the host reads pending and new mail keeps the default Nextmail host. Once one passes it reads active. Nextmail keeps checking on its own, and an active host that fails three checks in a row, or whose last passing check is 2 hours old, reads failed while new mail goes back to the default host.
• —Remove a host with null, as in --tracking-host null. An empty value such as --tracking-host= is a usage error in the CLI and exits with code 2.
• —A new host needs the domain verified, or at least its _openemail-challenge TXT record published. Otherwise the call is refused with 409 domain_not_verified.
• —The flags apply in order: the catch-all, then the tracking domain, then the files domain, then the DMARC policy. A later flag that is refused can leave an earlier change saved, so send them in separate calls when each has to stand on its own.

A domain holds the addresses created by hand or through the API, and the ones its catch-all picked up when mail first arrived for them. list-addresses shows both kinds, disabled ones included. The catch-all itself is not a row: it is receiving.catchAll on the domain.

• —create-address takes --local-part, the part in front of the @, and an optional --label. The domain does not have to be verified yet, but the address receives nothing until it is. * on its own is refused, since that is how the catch-all is written.
• —Creating an address that already exists, or one that was removed, is not an error. It comes back enabled, with the label you sent or none, and keeps its id. An address the catch-all picked up becomes one created by hand, so it keeps receiving after the catch-all is turned off.
• —With the catch-all on, a new address starts with the per-address settings of the catch-all, such as its signature and tracking, apart from the privacy settings. They are copied once and not kept in step.
• —update-address --no-enabled stops the address taking mail, so senders get a bounce, and nothing can be sent from it. It keeps its mail, its settings and the people who can reach it, and --enabled picks up where it left off. --label renames it, and --label null removes the name.
• —delete-address goes further. Mail to the address is refused even with the catch-all on, its forwarding stops, its settings are deleted, the people given access to it lose that access, and its password sign-in is revoked. Mail it already received stays in the mailbox. Creating it again brings back the same id, without the old settings or access.

nextmail addresses list answers the question behind a 403 from_address_forbidden: which addresses the key or sign-in you are calling with may put in From. It needs emails:send rather than a read scope, because it describes what a send would accept.

• —On a terminal it prints two tables: the addresses, each with whether it is enabled and whether you can send from it, then the domains, each with whether it is verified for receiving and for sending, and its catch-all.
• —unrestricted is true when the credential is narrowed by nothing. Any local-part on the workspace’s domains can then be sent from, including ones nobody created. Otherwise canSend is true only for an enabled address the credential covers, through a whole domain it holds or its own list of addresses.
• —canSend is false for a disabled address, for one the credential does not cover, and for one whose domain cannot sign yet.
• —Only created addresses are listed. A credential that holds a whole domain can still send as any local-part on it, and an address on its list with no mailbox behind it can be sent from without showing up here.
• —With --json it prints { unrestricted, addresses, domains, hasMore, nextCursor } for one page, and { unrestricted, addresses, domains } with --all, rather than the { items, hasMore, nextCursor } document other lists print. With --all in a pipe, or with --ndjson, it prints one address per line.

A connected mailbox is an address at Gmail, Yahoo, iCloud or another provider whose mail stays there and is worked from Nextmail. nextmail connected-mailboxes connects one with an app password and manages it. Reading needs threads:read, syncing needs threads:write, and connecting, changing and disconnecting need domains:write.

nextmail status reads your sign-in, addresses list and domains list at the same time and prints them together. Its Sender addresses table shows each address with whether it can send and whether it is enabled. Its Domains table shows each domain as verified or not verified for receiving, its sending status, and its catch-all. It shows the first 100 of each and names the --all command for the rest.

• —A part your credential may not read, such as the domains without domains:read or the addresses without emails:send, says Not available with the reason, and the rest still prints.
• —With no addresses yet, it suggests nextmail domains create --domain example.com.
• —nextmail status --json prints one object with account, addresses, domains and unavailable, where unavailable gives the reason for each part that could not be read.

Linking a DNS provider account, so the records of a new domain are written for you, happens only in the web app, because the provider asks you to sign in there. nextmail open providers, or open dns, opens that page. Once an account is linked, nextmail dns-connections list shows it and domains sync-dns <id> writes or repairs the records of a domain. open domains opens the domains and their DNS records, open addresses the addresses, and open forwarding <address> the forwarding of one address, which domains list-address-forwards and the commands beside it manage from here too. --print prints the link instead of opening a browser.

nextmail domains create --domain acme.com --json > acme.jsonjq -r '.records[] | [.type, .name, .value, (.priority // "")] | @tsv' acme.jsonnextmail domains verify "$(jq -r .id acme.json)"

id=b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6funtil nextmail domains get "$id" --json | jq -e .receiving.verified > /dev/null; do  sleep 30donenextmail domains get "$id" --json | jq '.sending | {status, canSend, error}'

nextmail domains list-addresses "$id" --allnextmail domains create-address "$id" --local-part invoices --label Invoicesnextmail domains update "$id" --no-catch-all --dry-runnextmail domains update "$id" --no-catch-all

Creating invoices by hand keeps it receiving once the catch-all is off, while mail to every other address the catch-all picked up is refused. The dry run prints the PATCH and its body without sending it.

nextmail domains update "$id" --tracking-host links.acme.com --json | jq '.tracking | {status, record, error}'nextmail domains update "$id" --tracking-host null

address_id=$(nextmail domains list-addresses "$id" --all | jq -r 'select(.address == "sales@acme.com") | .id')nextmail domains update-address "$id" "$address_id" --no-enablednextmail domains delete-address "$id" "$address_id" --yes

Turning the address off first can be undone with --enabled. The delete cannot, and in a script it needs --yes. With a browser sign-in it also asks for a verification code, which --yes never skips.

nextmail domains list --all | jq -r 'select(.sending.canSend | not) | [.domain, .sending.status] | @tsv'nextmail addresses list --all --json | jq -r '.addresses[] | select(.canSend) | .address'

• —A sign-in or key without the scope stops with exit code 4, names the missing scope and says how to get it.
• —domains delete and domains delete-address 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.
• —With a browser sign-in, those two deletes also ask for a verification code, as the web app does. Unattended nobody can type it, so the command stops with exit code 4. Run nextmail verify first and the next 60 minutes need no code. An API key is never asked.
• —--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 list reads 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, domains list and list-addresses print one { items, hasMore, nextCursor } document.
• —A key or sign-in limited to particular domains or addresses still sees every domain and address. It cannot add a domain, and every other change needs the whole domain among the domains it holds, or the call is refused with 422 capability_unsupported.
• —A refusal exits with the code of its status: 4 for a 403, such as domain_allowance_reached when the plan allows no more domains, 5 for a 404, 6 for a 409, such as domain_already_added or domain_claimed, and 7 for a 422, such as invalid_tracking_host or workspace_limit_reached.
• —The last domain in a workspace cannot be removed from the CLI. That is a 409 last_domain, because removing it deletes the whole mailbox, which the web app confirms first. A domain holding reserved account addresses is a 409 domain_holds_reserved_addresses.
• —domains create and the two deletes are never retried after a network failure. A 409 domain_already_added, or a 404 on your own second try after a lost answer, means the first one worked. verify, update, create-address and update-address are retried on their own, since sending one twice leaves the same result.

set-logo uploads the logo inboxes show next to mail from the domain. Pass the SVG inline, as in --svg "$(cat logo.svg)". It is converted to the format inboxes require, and get-logo reads it back with what public DNS publishes for it.

• —Where Nextmail writes the DNS for the domain, the logo record is published in the same call, and records in the answer says how that went. Otherwise publish record at your DNS provider.
• —Inboxes show the logo once domains update --dmarc-policy quarantine or reject is in place. For a subdomain, the domain it belongs to needs the same, and get-logo reports that as parentDmarc.
• —set-logo-certificate --certificate takes the VMC or CMC as PEM text, or a DER or PKCS #7 file in base64. When the logo inside it differs from the published one, its logo is published instead, since inboxes compare the two.
• —set-address-photo reads the image from a file, or from stdin with -. Pass --content-type, such as image/jpeg.

nextmail app-host manages the web app address of the workspace: a subdomain such as mailbox.acme.com, on one of its verified domains or any other domain it controls, where its people open Nextmail under the workspace brand. It is the same address as the Branded app tab in the web app. A workspace has one, and it needs a paid plan. app-host get needs domains:read, and set, verify and delete need domains:write.

• —app-host set --host mailbox.acme.com sets it up and answers pending, with the CNAME record to publish in record, and a TXT record in ownershipRecord too when the address is not on a verified domain of the workspace. It goes live a few minutes after the records answer. app-host verify checks straight away, and app-host get checks again when the last check is more than 15 seconds old.
• —Only the members of the workspace, the people who sign in with one of its addresses and anyone with a pending invitation can sign in there. On the free plan the address is kept but paused, and nobody can sign in there until the workspace is on a paid plan again.
• —app-host delete asks you to confirm, signs everyone at the address out and leaves its DNS records at your DNS provider. With a browser sign-in it also asks for a verification code. A key or sign-in limited to particular domains or addresses can read the address but cannot set or remove it.

nextmail branding manages the brand of the workspace, the settings on its Customisations page: the mark, the logo, the logo for dark mode, the photo behind the sign-in page, the primary and secondary fonts, and the sign-in background. The logo is what brands the web app address and, on a paid plan, the emails sent for the workspace. branding get needs settings:read, and the other three need settings:write. A personal space carries no brand.

• —branding update --fonts-primary inter --fonts-secondary georgia sets the fonts, and null sets the default. --login-background-kind preset --login-background-preset dusk, or --login-background-kind color --login-background-color '#1f2937', sets the sign-in background, and --login-background null sets the default.
• —branding upload-image login-background lobby.jpg --content-type image/jpeg uploads the sign-in photo and switches the sign-in page to it. The variant is mark, wordmark, wordmark-dark or login-background.
• —branding remove-image <variant> asks you to confirm and deletes the stored image. A key or sign-in limited to particular domains or addresses can read the brand but cannot change it.

nextmail tools runs the free tools on the Nextmail website. The checkers work on any domain, yours or anybody else’s, and read public DNS and nothing in the workspace. The code reader finds the sign-in code in a message, and the cost estimate prices every plan. None of them needs a scope.

• —An email address or a URL is read as its domain, so nextmail tools check-dmarc ana@acme.com checks acme.com.
• —A value that does not read as a domain is 422 invalid_parameter, and DNS that does not answer is 503 unreachable, which is worth trying again.

An address that keeps its mail in Nextmail can be used in Apple Mail, Outlook, Thunderbird, the Gmail app and other mail apps, which sign in with an app password.

• —get-mail-app-settings needs domains:read, and update-mail-app-settings needs domains:write. The other five commands need members:write, and a sign-in or key limited to some domains or addresses is refused. create-app-password and send-mail-app-setup also need the key or the sign-in to hold every mail, calendar and contacts scope the password would carry, or they are refused with 403 insufficient_authority.
• —create-app-password prints the password once, in password, and the CLI then warns that it is never shown again. Made with an API key, it acts as the workspace owner, and made with a browser sign-in, it acts as you.
• —delete-app-password asks you to confirm. A mail app that stays connected with that password is signed out within about five minutes.
• —With a browser sign-in, create-app-password and send-mail-app-setup ask for a verification code, as the web app does. An API key is never asked.
• —update-mail-app-settings turns the connections an address accepts on or off with the boolean flags --imap, --smtp, --pop3, --caldav and --carddav, changing only the ones you pass. update-app-password --name renames a password, which keeps working as before.