--- title: "Domains and addresses" description: "Add and verify domains, read the DNS records they need, manage the addresses on them, and check what you can send as." url: "https://nextmail.sh/docs/cli/domains" area: "CLI" category: "Commands by area" --- # Domains and addresses Add and verify domains, read the DNS records they need, manage the addresses on them, and check what you can send as. ## Overview 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 --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. ## Every command | Command | What it does | | --- | --- | | nextmail domains list | List the workspace’s domains, alphabetically, with their receiving, sending, tracking and files state | | nextmail domains get | Read one domain with its addresses, every DNS record it uses and whether each was found, and its DMARC reading | | nextmail domains create --domain | Add a domain. The answer holds every DNS record to publish, already checked once | | nextmail domains verify | Check the domain’s DNS straight away and return the domain as the check left it | | nextmail domains update | Turn the catch-all on or off, and set or remove the tracking domain and the files domain | | nextmail domains delete | Remove the domain and every address on it. Asks you to confirm | | nextmail domains list-addresses | List the addresses on a domain with their ids, labels, enabled state and when each last received mail | | nextmail domains create-address --local-part | Create an address on the domain, enabled, with an optional `--label` | | nextmail domains get-address | Read one address on a domain | | nextmail domains update-address | Rename an address with `--label`, turn it off and on with `--no-enabled` and `--enabled`, or choose with `--destination` whether it keeps its mail here (`mailbox`) or only forwards it (`forward`) | | nextmail domains delete-address | Remove an address from its domain. Asks you to confirm | | nextmail domains get-logo | Read the domain logo with its certificate, what public DNS publishes for it and, for a subdomain, the DMARC of its parent domain | | nextmail domains set-logo --svg | Upload the logo inboxes show next to mail from the domain | | nextmail domains remove-logo | Remove the logo, and take its record down where Nextmail writes the DNS. Asks you to confirm | | nextmail domains set-logo-certificate --certificate | Upload the VMC or CMC that Gmail and Apple Mail need before they show the logo | | nextmail domains remove-logo-certificate | Remove the mark certificate. Asks you to confirm | | nextmail domains set-address-photo | Upload the photo shown for an address in Nextmail | | nextmail domains remove-address-photo | Remove the photo of an address. Asks you to confirm | | nextmail addresses list | List the addresses you may send as with this key or sign-in, and each domain’s receiving and sending state | | nextmail app-host get | Read the web app address of the workspace with its status, its DNS records and whether people can sign in there | | nextmail app-host set --host | Set or replace the web app address, a subdomain such as `mailbox.acme.com` on any domain | | nextmail app-host verify | Check the web app address straight away and return it as the check left it | | nextmail app-host delete | Remove the web app address and sign everyone out there. Asks you to confirm | | nextmail branding get | Read the brand of the workspace: its images, its two fonts and its sign-in background | | nextmail branding update | Change the fonts or the sign-in background, with `--fonts-primary` or `--login-background-kind` | | nextmail branding upload-image | Upload the mark, the logo, the logo for dark mode or the sign-in photo | | nextmail branding remove-image | Remove one of the brand images. Asks you to confirm | | nextmail domains list-address-forwards | List where the mail of an address is forwarded, and whether each destination confirmed it | | nextmail domains add-address-forwards --emails | Forward the mail of an address to more places. Each one is asked by email to confirm first | | nextmail domains update-address-forward | Pause a destination with `--no-enabled`, or switch it back on with `--enabled` | | nextmail domains delete-address-forward | Stop forwarding to a destination. Asks you to confirm | | nextmail domains resend-address-forward-consent | Send a destination the email asking it to confirm once more | | nextmail domains list-address-members | List who can reach an address, and how each one does | | nextmail domains get-address-login | Read whether an address has a password of its own to sign in with | | nextmail domains set-address-login --password | Give an address a password, or replace it and sign out whoever used the old one | | nextmail domains delete-address-login | Remove the password of an address and sign out whoever used it. Asks you to confirm | | nextmail dns-connections list | List the DNS provider accounts connected to the workspace and the domains each one serves | | nextmail dns-connections get | Read one connection and what disconnecting it would leave behind | | nextmail dns-connections delete | Disconnect a DNS provider account and take down the records written through it. Asks you to confirm | | nextmail domains get-dns | Read how the DNS of a domain is set up and which connected zone answers for it | | nextmail domains set-dns-zone --connection-id --zone-id | Choose the zone a domain is set up through, when several could answer for it | | nextmail domains sync-dns | Write or repair the DNS records of a domain, or only one kind with `--purpose` | | nextmail domains get-mail-app-settings | Read the servers and the username that put an address into a mail app | | nextmail domains list-app-passwords | List the app passwords of an address, who holds each and when a mail app last used it | | nextmail domains create-app-password --name | Create an app password for a mail app. It is printed once | | nextmail domains delete-app-password | Revoke an app password and sign out the mail app using it. Asks you to confirm | | nextmail domains send-mail-app-setup --recipient | Email someone a one-time link that sets up an address in their mail app | > Every flag is in the help of its command, for example `nextmail domains update --help` or `nextmail domains create-address --help`. ## Receiving and sending 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. ## Catch-all, tracking and files domains `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. | Flag | What it changes | | --- | --- | | --catch-all, --no-catch-all | On accepts mail to any address on the domain that nobody created, and the address shows up in `list-addresses` from its first message. Off refuses mail to every address not created by hand, including the ones the catch-all picked up before. A new domain starts with it on | | --tracking-host | A subdomain such as `links.acme.com` for tracked links and the open pixel. `null` removes it | | --storage-host | A subdomain such as `files.acme.com` for the download links of files sent from the domain. `null` removes it | | --dmarc-policy | `none`, `quarantine` or `reject`. Inboxes show the domain logo only at `quarantine` or `reject`, and a stricter policy than `none` needs mail from the domain to be signed first | - 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. ## Addresses on a domain 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. ## What you can send as `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. ## Connected mailboxes 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`. | Command | What it does | | --- | --- | | nextmail connected-mailboxes discover | Finds the mail servers of an address and whether it takes an app password | | nextmail connected-mailboxes connect --email
--password - | Signs in to both servers and adds the address. `--import-history` copies the mail already there | | nextmail connected-mailboxes list | Every connected mailbox, with its status and when it last synced | | nextmail connected-mailboxes get | One connected mailbox, with what went wrong if it stopped syncing | | nextmail connected-mailboxes update | `--paused` pauses it, `--no-paused` resumes it, `--label` renames the address and `--password -` gives it a new app password | | nextmail connected-mailboxes sync | Asks for a sync straight away | | nextmail connected-mailboxes disconnect | Stops syncing, forgets the password and removes the address. The mail already here stays | > `--password -` reads the password from standard input and `--password @file` from a file, so it never lands in your shell history. ## status, open and DNS providers `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 ` writes or repairs the records of a domain. `open domains` opens the domains and their DNS records, `open addresses` the addresses, and `open forwarding
` 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. > Where Nextmail wrote a domain’s DNS itself, `domains delete` takes those records back and lists any it could not in `leftBehind`, for you to remove at your DNS provider. Records you published yourself are never touched, so remove them too once the domain is gone. ## Examples **Add a domain and publish its records** ``` nextmail domains create --domain acme.com --json > acme.json jq -r '.records[] | [.type, .name, .value, (.priority // "")] | @tsv' acme.json nextmail domains verify "$(jq -r .id acme.json)" ``` **Wait until it receives, then check sending** ``` id=b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f until nextmail domains get "$id" --json | jq -e .receiving.verified > /dev/null; do sleep 30 done nextmail domains get "$id" --json | jq '.sending | {status, canSend, error}' ``` **Turn the catch-all off, keeping one address** ``` nextmail domains list-addresses "$id" --all nextmail domains create-address "$id" --local-part invoices --label Invoices nextmail domains update "$id" --no-catch-all --dry-run nextmail 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. **Set a tracking domain, then remove it** ``` nextmail domains update "$id" --tracking-host links.acme.com --json | jq '.tracking | {status, record, error}' nextmail domains update "$id" --tracking-host null ``` **Retire an address** ``` address_id=$(nextmail domains list-addresses "$id" --all | jq -r 'select(.address == "sales@acme.com") | .id') nextmail domains update-address "$id" "$address_id" --no-enabled nextmail 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. **Audit from a script** ``` 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' ``` ## Scopes, confirmations and errors | Scope | Commands | | --- | --- | | domains:read | `domains list`, `get`, `list-addresses`, `get-address` | | domains:write | `domains create`, `verify`, `update`, `delete`, `create-address`, `update-address`, `delete-address` | | emails:send | `addresses list` | - 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 ` 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. ## Logo and address photos `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`. ## Where to go next - [Connect a domain](https://nextmail.sh/docs/get-started/domain.md): What verification checks, and how to publish the records. - [Domains in the SDK](https://nextmail.sh/docs/sdk/domains.md): The same calls from TypeScript, with every field of the answer. - [Domains in the API](https://nextmail.sh/docs/api/domains/list.md): The REST endpoints these commands call. - [Verification codes](https://nextmail.sh/docs/cli/authentication.md): When a browser sign-in is asked for a code, and how to verify ahead. ## Web app address `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. ## Brand `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 ` 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. ## Tools `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. | Command | What it does | | --- | --- | | nextmail tools check-dmarc | Read the DMARC record of a domain: its `stage`, every tag, the parent domain it inherits from and the issues found | | nextmail tools check-bimi | Check whether inboxes can draw the logo a domain publishes, with the logo, its mark certificate and the DMARC policy beside it | | nextmail tools check-deliverability | Check MX, SPF, DKIM, DMARC and BIMI, each `pass`, `warn`, `fail` or `absent`, with a score out of 100 and a grade from A to F | | nextmail tools read-verification-code --subject --html | Print the sign-in code in a message, or nothing when the reader is not sure. `--raw` takes the whole MIME source instead | | nextmail tools estimate-cost --sends --domains --people | Price every plan for a usage, with `--ai-actions` and `--interval`, and name the cheapest one that fits | - 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. ## Mail apps 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. - [Mail apps](https://nextmail.sh/docs/knowledge/addresses/mail-apps.md): The server settings, and how to add an address to each mail app.