Setting up a domain
Two steps: activate email for the domain, then get its DNS records in place. The second step is where almost all the difficulty is, and how much of it falls to you depends entirely on where the domain's DNS is hosted.
Activate the domain
Open Email → Domain Settings, pick the domain, and press Activate.
A payment method has to be on file first; without one the activation is refused. A domain linked to one of your web hosting packages needs no activation at all and shows Included in hosting. If you link a domain that already has paid email hosting to an active package, the paid plan ends automatically and the unused days of the current period are refunded pro rata.
Mailboxes, aliases and everything else on the domain can only be created once email is active for it and, for a domain registered elsewhere, the domain is verified. How to cancel email, and when it is switched off, for example when the hosting package ends or you unlink the domain, is covered in Ending email for a domain and When email is switched off.
For a domain you keep at another registrar, Add External Domain on the Mailboxes tab puts email hosting for it into your cart.
Before such a domain gets email, we need to see that it is yours. Email → DNS & Setup shows a TXT record named _itsh-mail with a token unique to the domain. Add it at your DNS provider and press Check now, or wait: we also check every ten minutes. Until the record is found, nothing can be created on the domain. Once the domain is verified, we check once a day that either this record or an MX record pointing to us is still there. A domain that is never verified is released when its email hosting ends.
Activation, or for a domain registered elsewhere its verification, registers the domain on the mail server and generates two DKIM keys for it, one Ed25519 and one RSA. Both are published, and outgoing mail is signed with both.
The DNS records
Mail works once the required records exist. MX decides whether mail arrives at all; SPF, DKIM and DMARC decide whether the mail you send is accepted by anyone else. All records use a TTL of 3600.
| Type | Name | Value | Required |
|---|---|---|---|
MX | @ | 10 mail.itsh.dev. | yes |
TXT | @ | v=spf1 ip4:116.203.15.70 -all | yes |
TXT | _dmarc | v=DMARC1; p=quarantine; rua=mailto:dmarc-rua@itsh.dev | yes |
TXT | <selector>._domainkey | one record per DKIM key of your domain | yes |
TXT | _itsh-mail | the token shown on DNS & Setup | only for a domain registered elsewhere, until it is verified |
CNAME | autoconfig | api.itsh.dev. | no |
CNAME | autodiscover | api.itsh.dev. | no |
SRV | _autodiscover._tcp | 0 0 443 autodiscover.itsh.dev. | no |
SRV | _imaps._tcp | 0 1 993 mail.itsh.dev. | no |
SRV | _submission._tcp | 0 1 587 mail.itsh.dev. | no |
The DKIM selectors and keys are unique to your domain and are not listed here. Email → DNS & Setup shows every record as a card with your keys filled in, each field labelled the way DNS providers label them and with its own copy button.
The optional records are what makes a mail client configure itself from nothing but an address and a password. Mail still flows without them; setting up a client just becomes manual.
Three things break mail when the domain already had records before:
- The old provider's MX records have to go. Left next to ours, part of your mail keeps arriving there.
- There can only be one SPF record. If one exists, add our
ip4:116.203.15.70to it, ahead of itsall, instead of creating a second: with two, receivers ignore both. - There can only be one DMARC record. Replace an existing
_dmarcrecord, or add our address to itsrua.
Who writes them
If the domain's DNS is hosted here, we do. Press Auto-configure on the DNS & Setup tab and the missing records are written into your zone. A nightly job then keeps them there, so a record deleted by accident comes back on its own. Records that conflict with ours, such as another provider's MX, a second SPF or DMARC record, or a CNAME on a name we need, are left for you to remove; the tab says which.
If the domain's DNS is anywhere else, you do. Copy the table into your DNS provider by hand. Nothing on our side can reach that zone, so nothing on our side can repair it either.
The button only appears when it can work
Auto-configure is offered only for a domain whose DNS is hosted here, to an account that may change it, and only while there is something left it can fix. For a domain on external nameservers, add the records at your provider.
The button may be missing even when your DNS is here
For a domain you bought only for email, the Auto-configure button is not shown at all, even though the zone is hosted here and the records could be written. Use the table above and add them by hand.
What happens to records you already had
Auto-configure and the nightly job repair rather than replace, which matters if the domain already sends mail through something else:
- An existing SPF record is extended. Our IP is merged into it instead of overwriting it, so a newsletter tool or shop already listed there keeps working.
- An existing DMARC record keeps its policy, and its
ruais rewritten to ours unless it already lists our address. To keep receiving your own DMARC reports, list both, separated by a comma:rua=mailto:you@example.com,mailto:dmarc-rua@itsh.dev. - The apex is skipped when mail lives only on a subdomain. A domain whose mailboxes are all on
support.example.comkeeps whatever MX the apex already has, so the root domain can stay with another provider. Pressing Auto-configure for the domain itself applies the rules above to the apex at once.
Checking it worked
The DNS & Setup tab checks every record and marks it Valid, Not right, Missing or Could not check. For a domain whose DNS is hosted here it reads the zone directly, so a change shows at once; anywhere else it resolves the records live, the way a receiving server would.
Not right means something is published under that name but does not do its job. The card shows what it found: a different value, a second SPF or DMARC record, another provider's MX next to ours, or a CNAME occupying the name. An SPF record that includes our IP among others, ahead of its all, counts as valid, and so does a DMARC record with your own policy as long as its rua lists our address.
The domain counts as set up once every required record is valid; the optional ones do not hold it back.
A record you have just added can read Missing for as long as its old TTL takes to expire elsewhere. Give it an hour before treating it as a problem, then press Check now.
Email on a subdomain
Email → Subdomains → Add Subdomain switches on mail for a name under the domain, so that support.example.com can have its own mailboxes and its own catch-all.
A subdomain gets the same records, each prefixed with its label, and its own DKIM keys rather than copies of the parent's.
Names are lowercase letters, digits and hyphens. These are reserved and refused:
www ftp mail smtp imap pop pop3 ns1 ns2 ns3 ns4 ns mx webmail autoconfig autodiscoverA subdomain cannot be removed while it still has mailboxes on it.
What's next
- Connecting a mail client once the first mailbox exists
- Mailboxes and aliases to create addresses