nextmail domains

Returns one page of the domains added to the workspace, alphabetically by domain. receiving reports the inbound checks: verified is true once verifiedAt is set, catchAll is the domain's catch all setting, lastCheckedAt is the most recent check and error is the last verification failure.

receiving and sending are independent. A verified domain can receive mail, and that says nothing about whether outbound mail from it is signed. sending.status is the signing state as the last check saw it, one of verified, pending, failed, no_identity or unknown, sending.canSend says whether a send from the domain would be accepted right now, sending.checkedAt dates that verdict, and sending.error carries the last failure. A negative verdict older than a day is treated as unknown rather than as a refusal, so canSend can be true while status is pending.

tracking reports the domain's custom tracking domain, set with update, and only a tracking.status of active means tracked links and the open pixel in new mail from the domain use its host instead of the default Nextmail host. storage reports the domain's custom files domain the same way, and only a storage.status of active means the download links for files sent from the domain use its host.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Returns the same receiving and sending blocks as list, plus addresses: every address on the domain as a full lower cased address with its enabled flag. Disabled addresses are listed too. listAddresses returns the same addresses with their ids and labels. It also carries the tracking and storage blocks described on list, whose record is the CNAME record to add at your DNS provider for the tracking domain and for the files domain.

records is every DNS record the domain uses, each with type, name, value, priority on an MX record, a purpose written to be shown to a person, and status: found when the last check saw it in public DNS, missing when it did not, and null when it has not been checked yet. Publish each one exactly as given, since the values are specific to this domain. dmarc is the domain's DMARC record as public DNS has it, with its stage, any issues, and whether a policy stricter than p=none is safe yet. It is null until the domain is verified.

Reading an unverified domain checks its DNS again when the last check is more than 20 seconds old, so polling get is one way to wait for verification. verify checks straight away.

The id must belong to the calling workspace. Another workspace's domain id is a 404, the same as an id that does not exist, and the domain name is not accepted in its place.

Adds a domain and returns it with every DNS record to publish, in the same shape as get. The first DNS check runs during the call, so records[].status already says what public DNS answers with.

The domain receives mail once public DNS answers with its MX records and its _openemail-challenge TXT record, and it can send once its signing records are in place. Publish every entry in records exactly as given, since the values are specific to this domain, then call verify or poll get until receiving.verified is true.

A new domain starts with its catch-all on and no addresses. Create addresses with createAddress, or turn the catch-all off with update.

Checks the DNS of the domain straight away and returns it in the same shape as get. On an unverified domain it looks for the records that verify it, and receiving.verified comes back true when they are found. On a verified domain it checks the signing and return path records again and asks whether mail from the domain can be sent, so sending is fresh.

When the last check ran less than 10 seconds ago, nothing new is checked and the domain comes back as it stands, so calling it faster than that gains nothing. A record published a moment ago can take a few minutes to show up in public DNS.

--catch-all true accepts mail to any address on the domain that nobody created, and the address shows up in listAddresses from its first message on. False refuses mail to every address that was not created by hand, including the ones the catch-all picked up before. It applies to the whole domain, so only a key that holds the whole domain may change it.

--tracking-host and --storage-host set the two custom names a domain can carry once it is verified or its _openemail-challenge TXT record is published, each of them a subdomain of it. --tracking-host, such as links.example.com, is the name tracked links and the open pixel use. --storage-host, such as files.example.com, is the name the download links for files sent from the domain use. All five fields are optional and independent: a field left out is left alone, and for either host null removes that name and a string sets it. A patch carrying none of them changes nothing and answers with the domain as it stands. Each value is trimmed and lower cased, and a leading https:// or http://, any path, query or fragment and any trailing dots are stripped.

A new host is validated, saved and checked in the same call, so the response already carries the result of that first check. --tracking-host reports into the tracking block and --storage-host into storage, and the two blocks carry the same fields. The check asks the host over HTTPS for an answer signed by Nextmail, on /t/v/<nonce> for a tracking domain and /f/v/<nonce> for a files domain, so the host needs a CNAME record named record.name with the value record.value, with any proxying turned off. That value, also reported as target, is an address prepared for this host alone. When it could not be prepared during the call, record is null, target is an empty string and error says so, and it is finished within a few minutes without another call. Until a check passes, status is pending and new mail keeps using the default Nextmail host. Once one passes, status is active and new mail from the domain uses the host.

Sending a host the domain already has runs the check again, unless the last check was less than 30 seconds ago, in which case the stored state comes back unchanged. A different host replaces the current one at once, so new mail uses the default host until the new one passes a check. null removes that name, and its block then reports status as none with host and record null.

--dmarc-policy is what the domain's DMARC record tells receivers to do with mail that fails its checks: none only monitors, quarantine sends it to spam and reject refuses it. Inboxes show the domain logo only at quarantine or reject, and where Nextmail writes the DNS for the domain the record is updated during the call, keeping its other tags such as rua, while elsewhere you publish the DMARC record records lists.

--sender-name is the name recipients see beside every address on the domain that has no name of its own, such as Acme Support. Mail sent without a name in from goes out under the name of the address, then this one, then the name of the workspace. It is trimmed, and null or a string that is empty once trimmed removes it.

Removes the domain. Mail to it stops being accepted and nothing can be sent from it. Every address on it goes with it, their password sign-ins are revoked, its signing key is released, its tracking and files domains are retired, and the domain.deleted webhook fires. Mail already received stays in the mailbox.

Where Nextmail wrote the DNS for this domain itself, it takes those records back, and any it could not take back are listed 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.

There is no undo. Adding the domain again starts it from scratch.

Returns the logo inboxes show next to mail from the domain through BIMI, with its mark certificate and DMARC policy, and asks public DNS what default._bimi.<domain> holds right now: published.ours turns true once the record pointing at the logo is live. For a subdomain, parentDmarc reports the DMARC record of the domain it belongs to, because inboxes show the logo only when its p= and sp= both quarantine or reject at 100 percent.

Converts the SVG to the SVG Tiny PS format inboxes require, replaces any logo the domain had, and publishes the BIMI record where Nextmail writes the DNS for the domain. Inboxes show the logo once dmarcPolicy is quarantine or reject, which update sets, and Gmail also needs a mark certificate from setLogoCertificate.

Removes the logo and deletes the stored file, and takes the BIMI record down where Nextmail writes the DNS for the domain. Elsewhere remove the record yourself. Any mark certificate stays, ready for the next logo.

Stores the Verified Mark Certificate (VMC) or Common Mark Certificate (CMC) a certificate authority issued for the domain, replacing any there was, and points the BIMI record at it. Gmail shows the logo only with one and Apple Mail only with a VMC, and when the logo inside the certificate differs from the published one, it becomes the published one and logoFromCertificate is true.

Removes the mark certificate and deletes the stored file, while the logo stays. The BIMI record no longer points at a certificate, so Gmail and Apple Mail stop showing the logo.

Returns one page of the addresses on the domain, alphabetically by address, with each one's id, label, enabled and lastReceivedAt. That covers the addresses created by hand or through the API and the ones the catch-all picked up when mail first arrived for them. Disabled addresses are listed. Removed addresses and the catch-all itself are not: the catch-all is receiving.catchAll on the domain.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Creates an address on the domain, enabled, and returns it. The domain does not have to be verified yet, but the address receives nothing until it is.

When the domain has its catch-all on, the 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, not kept in step.

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 when the catch-all is turned off.

Returns one address on the domain with its label, enabled, lastReceivedAt and timestamps.

Changes the fields you send and leaves the rest alone. label renames the address, and null removes the name. enabled false stops the address taking mail: mail to it is refused while the sending server is still connected, so the sender gets a bounce, and nothing can be sent from it. It keeps its mail, its settings and the people who can reach it, so enabled true picks up where it left off. That is the difference from deleteAddress.

destination chooses where the mail of the address goes: mailbox keeps a copy here, as an address does by default, and forward only sends it on to the destinations from addAddressForwards, keeping nothing here. forward needs at least one destination that is switched on.

Sends the image bytes as the request body, replacing any photo the address had: PNG, JPEG, WebP or GIF up to 5 MB, cropped to a 512 pixel square, stored as JPEG or PNG and shown for the address in Nextmail in place of the domain logo. The type is read from --content-type, or from a Blob's own type when that is left out, and without either the server refuses the bytes with 422 invalid_image.

Removes the photo of the address and deletes the stored image, so the domain logo is shown for it again.

Removes the address. Mail to it is refused from then on, even when the catch-all on the domain is on. Its forwarding stops, its settings are deleted, the people who were given access to it lose that access, and its password sign-in is revoked. Mail it already received stays in the mailbox.

Creating the same address again with createAddress brings it back with the same id, enabled, but without its old settings or access.

Returns every place the mail of the address is forwarded to, oldest first, as the Forwarding section of the address in the app lists them. Each destination says whether it is switched on (enabled) and where it stands (status): only a live destination, one that confirmed by email that it wants this mail, receives anything.

destination on the list says whether the address also keeps a copy of its mail here (mailbox) or only forwards it (forward), and max is how many destinations one address may have.

Adds places the mail of the address goes to, as adding a destination in the app does. Each new destination is sent an email asking it to confirm, and receives nothing until it does, so it comes back pending and turns live once its owner confirms.

An address hosted here, one already on the list, one that would make a loop, one past the limit of 10 and one that refused mail from this workspace before are not added. Each is named in skipped with the reason, and the rest are still added.

The address keeps a copy of its mail here as before. To stop keeping one, set destination to forward with updateAddress once a destination is switched on.

enabled false pauses the destination: nothing is forwarded to it until it is switched on again. It keeps its confirmation, so switching it back on needs no new one, and switching it on clears the failures recorded against it.

When the last destination that is on is paused, the address goes back to keeping its mail here. destination in the result says where the mail of the address goes now.

Removes the destination, so nothing more is forwarded to it. When it was the last destination that was on, the address goes back to keeping its mail here, and destination in the result says where the mail of the address goes now.

To stop forwarding for a while instead, pause the destination with updateAddressForward, which keeps its confirmation.

Sends the confirmation email to the destination once more, for when the first one was lost or ignored. status says what became of the request: sent, already-confirmed when the destination has confirmed and needs nothing, too-soon when the last email went out moments ago, revoked when the destination refused mail from this workspace, and send-failed when the email could not be sent.

Returns everybody who can read the mail of the address and how each one reaches it, in via: owner for the owner of the workspace, every-address for a role that reaches every address, whole-domain for a grant of the whole domain named in viaDomain, and direct for a grant of the address itself. Each person appears once.

access is member for somebody who reads and sends from the address and viewer for somebody who only reads it. removable is true for a grant of the address itself, which members.revokeAddress takes back. The others come from the role or a domain grant, and change there.

Says whether the address has a password of its own, which lets somebody sign in to Nextmail as that address alone and read and send only its mail. login is null when it has none, and otherwise says who set the password and when, and when it was last used to sign in.

Sets the password somebody uses to sign in to Nextmail as this address alone. Whoever holds it reads and sends only the mail of the address and reaches nothing else in the workspace. Nextmail sends the password to nobody, so hand it over yourself.

Calling it again replaces the password, signs out everybody who signed in with the old one and removes the forwarding destinations they added. created says whether the sign-in is new.

Takes the password away and signs out everybody who signed in with it. The address, its mail and the people who reach it otherwise stay as they are, and the forwarding destinations added by whoever signed in as the address are removed with it.

Returns what to enter in Apple Mail, Gmail, Outlook, Thunderbird or any other mail app to add the address to it: the IMAP, SMTP and POP3 servers, each with its host, port and security, and the username to sign in with, which is the address itself. Each of those three encrypts the connection from the first byte, so its security is ssl-tls. smtpSubmission is the same SMTP server on port 587 for apps, devices and libraries that only offer STARTTLS: its security is starttls, the connection is upgraded before the sign-in, and it takes the same username and password.

caldav is the server that puts the calendar of the address into Apple Calendar, Thunderbird, DAVx5 on Android or any other CalDAV app, and carddav the one that puts the contacts of the workspace into Apple Contacts or any other CardDAV app. Each has a url to enter, with the same username and password, a principalUrl for apps that ask for the account address on the server, and host, port and security like the others.

protocols says which of these connections the address accepts, as true or false for imap, smtp, pop3, caldav and carddav. updateMailAppSettings changes them.

The password is an app password of the address, such as one createAppPassword makes, or the password setAddressLogin set when the address has a sign-in of its own without two-factor.

Switches each kind of connection the address accepts on or off: imap, smtp and pop3 for mail, caldav for its calendar and carddav for contacts. Send only the ones to change, and the rest stay as they are. Every kind is on until it is switched off.

A switched-off kind refuses every sign-in to it, whatever the password, with a message that says it is turned off. Mail apps and calendar or contacts apps that are already connected over it are signed out within minutes. App passwords stay as they are, so switching a kind back on lets them in again.

Returns every app password a mail app can sign in to the address with, newest first. Each one has the name it was given, last4, the last four letters of the password, to tell them apart, owner, the person it signs in as, and origin, which says where it was made: settings in the app, api through createAppPassword, and setup-link by opening an emailed setup link, such as one sendMailAppSetup sends.

lastUsedAt and lastUsedProtocol say when an app last signed in with it and over which of imap, smtp, pop3, caldav and carddav, and lastUsedClient names the mail app when it named itself. The passwords themselves are shown only when they are made, and revoked ones are left out.

Makes a password a mail app signs in to the address with, using the address as the username, and returns it in password with the server settings in servers. That is the only time the password is shown, so hand it over or store it then.

The password signs in as the caller for this address alone: an API key makes it for the workspace owner, and an access token for the person who connected the app. A mail app using it reaches the mail of the address with what that person may do there, and nothing else in the workspace. It is 16 letters in four groups joined by dashes, and the dashes, or spaces in their place, can be left out when it is typed.

Besides members:write, the key or access token has to hold itself every mail, calendar and contacts scope the password carries (threads:read, threads:write, emails:send, drafts:write, labels:write, calendar:read, calendar:write, contacts:read and contacts:write; for an access token, those of them its person's role holds). Without one of them the call is refused with 403 insufficient_authority.

Changes the name shown for the app password, such as when the device it is for changes hands. The password itself stays the same, and a mail app signed in with it stays signed in.

A person renames the app passwords they hold. The workspace owner, and someone whose role manages members, rename anyone's.

Revokes the app password, so no mail app can sign in with it again, and a mail app that is signed in with it is signed out within minutes. The address, its mail and its other app passwords stay as they are.

Emails the recipient a link that sets the address up in a mail app. Opening it makes an app password named after the recipient, shows it once with the server settings, and offers a profile that sets up an Apple device in one step. The link works once and expires in three days, at expiresAt.

The app password it makes signs in as the caller, as one from createAppPassword does: an API key makes it for the workspace owner, and an access token for the person who connected the app. It then appears in listAppPasswords with origin set to setup-link.

Besides members:write, the key or access token has to hold itself every mail, calendar and contacts scope the password carries (threads:read, threads:write, emails:send, drafts:write, labels:write, calendar:read, calendar:write, contacts:read and contacts:write; for an access token, those of them its person's role holds). Without one of them the call is refused with 403 insufficient_authority.

Returns whether Nextmail writes the records of the domain itself (managing), through which connection and zone, where each kind of record stands in steps, and the records left behind to delete by hand.

zone says which connected zone answers for the domain: one is resolved, several are ambiguous and need setDnsZone, none holds it, with the reason, or the connections could not be asked (unusable). The answer is kept for a few minutes, and refresh asks the providers again.

Attaches the domain to a zone of a connection, when several connected zones could answer for it. The zone has to cover the domain, be active at the provider and take a test record. Nothing is written yet: call syncDns to write the records.

Writes or repairs every record the domain needs through the connected zone that answers for it, as Sync does in the app. When exactly one zone answers it is attached first, and attached says so. With purpose, only that kind of record is written. A domain that was waiting for its records is verified once they are in place.

When no single zone answers, nothing is written: outcome is refused, message says why and zone shows the zones to choose from with setDnsZone.