All help articles

Automatic DNS

If your domain's DNS is hosted in AWS Route53, on dnso.city (Zappocity's own DNS hosting, free for a team's domains), or at Cloudflare, DigitalOcean, Gandi, GoDaddy, Hetzner, Linode, Namecheap, OVHcloud, Porkbun, Spaceship or Vultr, Zappocity can publish its records for you and keep them right: the MX, SPF, DKIM, DMARC, MTA-STS, ownership and app-discovery records from the domain's DNS list. It checks them every hour, so a new DKIM key or an MTA-STS change goes out by itself, and a record changed by hand is put back.

What it changes, and what it leaves

Records are published as whole record sets (a name and a type), as Route53 keeps them.

• MX at the domain, and the CNAME and SRV records it lists, become Zappocity's alone. Mail for the domain then comes here.
• TXT values are merged: Zappocity's SPF record replaces any other SPF record (a domain may have only one), its DMARC record the one at _dmarc, its DKIM keys the values at their selectors, and its ownership record the old one. Other TXT values at the same names, such as another service's verification, stay.
• Every other record in the zone (your website, other services) is left alone.
• A CNAME in the way. DNS allows no other record at a name that has a CNAME. If your zone has one where Zappocity publishes a record (most often a wildcard *.example.com CNAME for a website, beside the wildcard MX that turning on subdomain addressing adds):
  • By default it is flattened (Route53): the CNAME is replaced by the A and AAAA addresses its target has, with Zappocity's record beside them, so the website keeps working. The addresses are looked up again at every publish (hourly), so they follow the target. When Zappocity no longer needs the name (subdomain addressing turned off), the CNAME is put back as it was.
  • Replace it for good: tick Always replace records in the way with ours to keep the zone the way Zappocity wants it, or choose Publish and replace records in the way once. What the CNAME served stops working at that name.
  • On dnso.city neither is possible yet: the record is skipped, everything else is published, and the page says what was skipped.

Stopping it leaves the records as they are.

Your own addresses and the mail-app names

Automatic DNS also publishes the names people type into a browser or a mail app:

• Your own addresses (see Your own addresses): webmail, the tenant manager, and the forums and wiki while the tenant has them. Each gets a CNAME to the target the team manager shows, and an old A or AAAA record at that name is replaced. A name that cannot have a CNAME (the domain itself, or a name that also has other records, such as MX or TXT) gets the target's A and AAAA addresses instead, looked up again at every publish so they follow the target.
• imap., smtp. and jmap. under the domain get a CNAME to the server's host name, so mail apps can use imap.example.com and the like (each gets its certificate at the first connection). mail. is added too when Also publish the optional records is on (the default). A name already used as one of your own addresses is left to that.

When a name stops being yours (you remove it, or the tenant's forums or wiki are turned off), its record is taken out at the next publish, but only while it still points here: a CNAME to the target, or addresses that are all the target's. A record someone has changed since is left alone. Saving the team's or a domain's own addresses, or turning forums or wiki on or off, publishes at once.

Setting it up

1. In AWS, make an IAM user (or role) with an access key, and give it this policy, with your hosted zone's ID:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["route53:ChangeResourceRecordSets", "route53:ListResourceRecordSets", "route53:GetChange"],
         "Resource": ["arn:aws:route53:::hostedzone/Z0123456789ABC", "arn:aws:route53:::change/*"]
       },
       {
         "Effect": "Allow",
         "Action": ["route53:ListHostedZonesByName"],
         "Resource": "*"
       }
     ]
   }

   The key can then change only that zone. (Leave out ListHostedZonesByName if you give the hosted zone ID below.)

2. On the domain's page in the team manager, Automatic DNS, with Publish at Route53: enter the access key ID and secret, and the hosted zone (the domain itself by default, or a domain above it whose zone holds its records) and its ID if you have it. Choose Publish automatically, then Publish now: the card lists what changed.

   From the command line: corpsuite domain dns-automation set TEAM DOMAIN accessKeyId=AKIA... secretAccessKey=-, then corpsuite domain dns-automation sync TEAM DOMAIN.

3. For a domain added without proof, the ownership record is published too: choose Verify on the domain's page once it is out.

The secret is stored sealed with the server's key and never shown again. If the domain moves to another team, the setting is removed, so your key is never used for another team.

At Cloudflare, Namecheap and other providers

Under Automatic DNS on the domain's page, choose the provider under Publish at and give what it asks for. Each provider's own help is shown beside the fields; in short:

• Give a token limited to DNS, and to this zone where the provider allows it.
• Secrets (tokens, keys) are sealed and never shown again. To change only a setting (a Namecheap user, an OVH endpoint), leave the secrets empty: the stored ones are kept.
• When you save new secrets, Zappocity reads the zone with them first; if the provider refuses (a wrong token, a zone it can't see), nothing is saved and its error is shown.
• Everything above holds as for Route53: our record sets are kept right every hour, other records stay, CNAMEs in the way are flattened or replaced.
• Namecheap's API replaces a zone's records all at once; Zappocity reads them first and writes them back with its own, so the others stay, but a change made in Namecheap's page during a publish can be lost.
• Route53 connections (one key for several domains) are for Route53 only; with other providers each domain gets its own credentials.

From the command line:

corpsuite domain dns-providers acme
corpsuite domain dns-automation set acme acme.com provider=cloudflare credentials:='{"apiToken":"..."}'

Several domains with one key (Route53 connections)

If your tenant has many domains in one AWS account, keep the key once instead of entering it on every domain:

1. Make the IAM key with the policy above, listing every hosted zone it should change (or arn:aws:route53:::hostedzone/* for all of them). Keep route53:ListHostedZonesByName: it is how each domain's zone is found.
2. On the Domains page of the tenant manager, Route53 connections → Add a connection: a name, the access key ID and secret, and whether new domains should be published with it by themselves.
3. Under Publish domains with a connection, tick the domains, choose Find hosted zones to see which zone each one would use (nothing changes), then Publish. Each domain's records go in the public hosted zone named after it, or after the nearest domain above it (so mail.acme.com goes in acme.com's zone if it has none of its own). The table says, for each domain, what was published or why not.

With Publish new domains by themselves on, every domain of the tenant without automatic DNS is set up with the connection within ten minutes, including domains added later. A domain whose hosted zone is not in the AWS account is tried again every hour.

A domain's own Automatic DNS card can also choose a connection under Key instead of a key of its own.

• New key on a connection changes it for all its domains at their next publish.
• Remove stops automatic DNS for every domain using it; their records stay as they are.
• A tenant's connection serves only that tenant's domains. If a domain moves to another tenant, its automatic DNS is removed.

The operator has the same under Shared domains → Route53 connections, for the shared domains (mailo.city and the like).

From the command line:

sudo corpsuite tenant dns-connection add acme name="Our AWS" accessKeyId=AKIA... secretAccessKey=- autoNewDomains:=true
sudo corpsuite tenant dns-connections acme
sudo corpsuite tenant dns-connection apply acme CONNECTION-ID all:=true dryRun:=true
sudo corpsuite tenant dns-connection apply acme CONNECTION-ID all:=true
sudo corpsuite dns-connection add name="Platform" accessKeyId=AKIA... secretAccessKey=-   # shared domains

On dnso.city

dnso.city is Zappocity's DNS hosting, and a team's own domains are free there. Under Automatic DNS, choose Publish at: dnso.city, then Publish on dnso.city and Publish now: no keys are needed.

• The first time, the domain's zone is made on dnso.city, in a DNS account of the team's organization ("Acme (Mailocity domains)", on the free Mailocity domains plan; a zone the organization already has there is used instead). Its owners find it on the account page under DNS hosting, where they can add records of their own; those stay.
• Then set the domain's name servers to dnso.city's at its registrar; the zone's page says when the registry has them, and shows the DS record that turns DNSSEC on.
• The team must belong to an organization (its Mailocity subscription's), and the domain must not be served for another organization on dnso.city; otherwise publishing fails and the card says why.

From the command line: corpsuite domain dns-automation set TEAM DOMAIN provider=dnso, then corpsuite domain dns-automation sync TEAM DOMAIN.

Shared domains and the platform's own zones

The operator can set up shared domains the same way, under Shared domains, or publish with the server's own AWS credentials instead of a key (Use the server's own AWS credentials: the server's environment, or the instance role of a server running in AWS). A team's domain can never use the server's credentials. Shared domains publish in Route53 or at one of the other providers, not on dnso.city.

Not yet

• Other DNS providers than those above: use the zone file or the provider guides.
• Connections (one set of credentials for several domains) at providers other than Route53.
• The platform's own host names (the mail host's address records) published this way.