Hosts#

A key manages a list of hosts. A host is a whole domain (example.com) or a name inside one (advisor.example.com). You manage records at each host and under it (_dmarc.advisor.example.com, google._domainkey.advisor.example.com).

When a key's host is a name inside a domain, everything else in that root domain belongs to someone else: you never see it and can't change it. The rest of this page is about that case; for a whole-domain host, the host and the root are the same name.

Two ways to address a host#

Every API style accepts either form, call by call.

1. The host as its own domain (simplest)#

Put the host in domain (Dynadot style) or in the path (Spaceship style):

• Records at the host are main records (Dynadot) or name @ (Spaceship).
• Records under it use the part in front of the host as the subhost or name: _dmarc, google._domainkey.

curl https://api.maildns.io/api3.json \
  --data-urlencode key=KEY --data-urlencode command=set_dns2 \
  --data-urlencode domain=advisor.example.com \
  --data-urlencode add_dns_to_current_setting=1 \
  --data-urlencode subdomain0=_dmarc \
  --data-urlencode sub_record_type0=txt \
  --data-urlencode 'sub_record0=v=DMARC1; p=quarantine'

2. Root domain plus subhost#

Put the root domain in domain and the full name under it as the subhost, the way registrars normally store subdomain records. Scripts written against a registrar often work this way already.

curl https://api.maildns.io/api3.json \
  --data-urlencode key=KEY --data-urlencode command=set_dns2 \
  --data-urlencode domain=example.com \
  --data-urlencode add_dns_to_current_setting=1 \
  --data-urlencode subdomain0=_dmarc.advisor \
  --data-urlencode sub_record_type0=txt \
  --data-urlencode 'sub_record0=v=DMARC1; p=quarantine'

In root form, get_dns lists only your hosts' records, all as subhosts. Main records (Dynadot) and @ (the other styles) mean the root domain itself, which is not yours: sending one is an error.

Both forms in each style#

Replies name records the way each style does: Cloudflare and Porkbun give full names, the others give names relative to what you addressed.

The same records in both forms#

Which form to use#

• One host at a time: host form. Names are shorter and there is only one way to get them right.
• Several hosts in the same root domain in one call: root form. One call (set_dns2, PUT, PATCH, setHosts) can carry records for every host your key has in that root, and it is applied as one change.
• Reading: either. In root form, reads return the records of all your hosts in that root, and nothing else.

Replace calls work per host#

Some calls replace instead of adding: every host the call mentions ends up with exactly the records in the call, including the records under it. Hosts the call does not mention keep all their records.

• In host form, the call mentions the host in domain.
• In root form, it mentions each host that one of its subhosts belongs to: _dmarc.advisor mentions advisor.example.com.

Careful: a replace that sends only the DMARC record (subdomain0=_dmarc.advisor, or HostName1=_dmarc) leaves advisor.example.com with that one record. Its MX, SPF, verification and DKIM records are removed. Use the add call unless you mean to replace.

On Dynadot, GoDaddy and Namecheap themselves a replace rewrites the whole domain. MailDNS limits it to the hosts you name, so a record forgotten for one host can't take another host down.

Listing hosts#

Every style lists your key's hosts and nothing else: list_domain (Dynadot), GET /api/v1/domains (Spaceship), GET /zones (Cloudflare), GET /v1/domains (GoDaddy), /domain/listAll (Porkbun), namecheap.domains.getList (Namecheap). Hosts can't be added through the API.

Names that are not yours#