Addresses and domains

Every enterprise receives mail on its own host under zerohuman.com. An owner can also attach a domain the company owns, prove it, and move the domain's mail onto Zero Human, one record at a time and with a way back.

The enterprise's own mail host

Every enterprise has a mail host from the day it is created: its slug under zerohuman.com. An enterprise with the slug northstar receives mail at northstar.zerohuman.com, and its members get addresses such as [email protected]. The slug is chosen when the enterprise is created and the portal has no way to change it later, so the host stays the same for the life of the company (Enterprise).

A member's address is made from its name: lower case, accents dropped, and spaces and dashes turned into dots, so Mary-Jane van Dyke would be [email protected]. The part before the @ is cut to 64 characters. Mail sent to an address with a + tag, such as [email protected], reaches the same mailbox. A person's address is the one an owner gives them (Person mailboxes).

No two mailboxes can hold the same address: not two members, not a member and a person, and not an extra address that somebody else already holds.

Extra addresses

A member's or a person's mailbox can have extra addresses that deliver to it, on any of the enterprise's domains. An owner adds them under Email aliases on the member's page, or under the person's address on People:

  • An exact address, such as [email protected], for a mailbox that answers as more than one name.
  • A plus tag, such as [email protected], kept under its own address.
  • A catch-all, written *@ and the domain, which takes every address on that domain that nobody else holds.

Each extra address says whether a reply to mail that arrived at it goes out from it (the default) or from the mailbox's own address. A catch-all only receives: a mailbox sends from its own address and the exact addresses it has been given, never from whatever a catch-all happened to catch.

Attaching a domain you own

An owner attaches a domain the company owns on Domains, under Settings in the portal. Only an owner who is signed in can attach, check, change or detach a domain; anyone whose grant covers enterprise, an API token included, can read the list and see what each domain still waits on.

Zero Human never gets access to the account at the company where you bought the domain. You add a few records there, and Zero Human only reads what you published. The portal and the API keep their own addresses whatever you choose.

A domain can be attached by one enterprise only, and a name under zerohuman.com cannot be attached at all.

Three choices for its mail

Attaching asks what happens to the domain's mail. Nothing is chosen for you:

Choice What it does Records it needs
Receive email at the domain Receive-only. Mail to the domain arrives in Zero Human instead of where it arrives today. Nobody can send or reply from it. Ownership and MX
Send and receive email at the domain All of the domain's mail moves to Zero Human. It receives as a receive-only domain does; sending from it is planned (below). Ownership, MX, DKIM and the bounce record
Keep email on your own mail host Nothing happens to the domain's mail: it is only checked to prove it is yours. Ownership

With Send and receive, the domain also lists what sending from it still waits on, as of its last check, and a send from one of its addresses is refused until every sending check passes.

Receive email only and Send and receive email on an attached domain switch between the first two at any time, and Keep email on your mail host switches to the third. The next mail reads the new choice.

The records

The domain lists every record still to publish, in a table to copy into your domain company's form: its type, its priority, its name, its value, and whether it is for ownership or for email.

  • Ownership. One TXT record at _zerohuman-verification under the domain, holding a value made for this claim alone. It proves the domain is yours, and nothing changes until it is published and checked.
  • MX. Three MX records at the domain itself, at priorities 10, 20 and 30. They send the domain's mail to Zero Human.
  • DKIM. Two CNAME records, zh1._domainkey and zh2._domainkey under the domain, for signing mail sent from it. Only Send and receive asks for them.
  • Bounces. One CNAME record at bounces under the domain, the address bounces come back to. Only Send and receive asks for it.

A record that is published stops being listed once it checks.

Check records

Check records reads what the domain publishes now and marks each record as it goes: passed, or failed with what it found instead, or No record found. Ownership holds only while its record is published: a record withdrawn since the last check withdraws what it proved. Asking again proves nothing new until something changes at your domain company, and DNS changes can take a while to be seen.

The domain then says where it stands: not verified yet, verified with its mail not moved yet, verified with mail kept on your mail host, or receiving active on this domain.

What changes once a domain is active

A domain is active once its ownership and its three MX records check, in either receiving choice:

  • Mail to an address on it is delivered to the mailbox that holds that address. Mail to an address that nobody holds is refused, and its sender is told.
  • A member created from then on gets its address on the domain, such as [email protected]. Members who already exist keep their address, and an owner can change it to the domain on the member's page.
  • Addresses on the domain can be given as soon as its ownership checks, before its MX records move, so every address can be ready before the first mail arrives.
  • A receive-only domain never sends. A send from one of its addresses is refused before anything leaves.

Moving a domain's mail to Zero Human

This guide moves a domain that already receives mail somewhere else, say example.com for Northstar, without losing any. It moves receiving: the domain is attached receive-only, every address is made ready, and only then do the MX records change. Do each step in order, and run its check before the next.

  1. Attach the domain. On Domains, type example.com, choose Receive email at example.com and press Attach. Check: the domain appears under Attached domains as not verified, with the ownership record and three MX records to add. Nothing about its mail has changed yet.
  2. Prove you own it. Add only the ownership TXT record at your domain company, then press Check records. Check: the ownership row passes and the domain says it is verified and its email has not moved yet. Leave the MX records alone for now.
  3. List every address in use. Write down every address at the domain that receives mail today: each person's, each shared address such as [email protected], and any catch-all. Check: compare your list with the mail provider you are leaving, so no address is missed.
  4. Give every address a mailbox. Give each person their address on People, and add each shared address as an extra address on the member or person who should receive it, with Reply from this address as you want it. Check: each address shows on People or on the member's page. An address left out is refused once mail moves.
  5. Shorten the wait for DNS. If your domain company lets you, lower the time to live of the domain's MX records and wait for the old value to pass. Check: your domain company shows the new time to live. It makes the move, and a rollback, take effect sooner.
  6. Publish the three MX records. Add them exactly as the domain lists them, at 10, 20 and 30. Keep your old provider's MX records for now, at higher numbers than 30, so they are only a fallback. Press Check records. Check: all three MX rows pass and the domain says receiving is active on this domain.
  7. Watch mail arrive. From a mailbox outside the company, send a message to two of the addresses you prepared. Check: each arrives in the mailbox you gave it, on the member's Inbox or the person's own Inbox.
  8. Remove the old MX records. Once mail is arriving, delete your old provider's MX records. Check: press Check records again, and send one more message from outside to verify it still arrives. Keep the old provider's account until the old records' time to live has long passed, so any mail still in flight is not lost.

How to roll back

Changing DNS does not clear what other mail servers have already looked up, so a rollback takes effect as their cached answers expire, as the move did:

  • Put the old MX records back at your domain company, and remove the three Zero Human ones. Mail goes back to your old provider as caches expire.
  • Then switch or detach. Once the old records are back, Keep email on your mail host stops the domain receiving in Zero Human, and Detach removes it altogether. Do this after DNS, not before: while the MX records still point at Zero Human, mail to a domain that is no longer active is refused.
  • What already arrived stays. Mail delivered to Zero Human during the move stays in its mailboxes for your plan's period (Retention and deletion).

Planned

Sending from your domain

With Send and receive email, members and people will send and reply from the domain's addresses once its DKIM and bounce records check: their mail signed with the domain's own DKIM keys, and bounces coming back to its bounce address. The move guide above will then end with a last step, publishing those records and checking them, after mail is already arriving.

Detaching a domain

Detach on a domain asks you to confirm, then removes it: mail routing and who may send from it go back to how they were before it was attached, and its records no longer prove anything. Attaching it again starts from a new ownership record.

Over the API

Reading the list is GET /v1/enterprise/domains, open to a token whose scopes cover enterprise. The rest is for a signed-in owner only: POST /v1/enterprise/domains with { "domain", "mailMode" } attaches one (mailMode is receive, migrate for send and receive, or keep), POST /v1/enterprise/domains/{domain}/verify checks its records and answers what each one found, PATCH /v1/enterprise/domains/{domain} with { "mailMode" } changes the choice, and DELETE on the same path detaches it. A domain another enterprise holds is refused with domain_already_claimed, a name under zerohuman.com with domain_reserved, and a name that is not a domain with invalid_domain.