DNS through the API: adding, changing and deleting records, and restoring a zone backup

Domains & DNS·· 38 views· 4 min read

The short answer: the API reads and changes the DNS zone of the active domains in your account that have DNS switched on (you switch it on in My MozOut). With dns:read you read; with dns:write you add, change and delete records. Before every change a zone backup is kept, and the last 20 per domain are stored.

The operations

Operation What it does
GET /v1/domains/{domain}/dns Lists the records. Those with read_only set to true, such as the root NS, cannot be changed here.
POST /v1/domains/{domain}/dns Adds a record: name, type, value and, optionally, ttl and priority.
POST /v1/domains/{domain}/dns/validate Checks a record without saving it. dns:read is enough.
PUT /v1/domains/{domain}/dns/{record_id} Changes a record.
DELETE /v1/domains/{domain}/dns/{record_id} Deletes a record.
GET /v1/domains/{domain}/dns/backups Lists the zone backups.
POST /v1/domains/{domain}/dns/backups/{id}/restore Restores a backup.
POST /v1/domains/{domain}/dns/reset Empties the zone of your records. Needs the domain name in confirm.

The accepted types are A, AAAA, CNAME, MX, TXT, NS, SRV and CAA. Nameservers are changed in the domains part: see domains through the API.

Example: a TXT verification record

1 Check it first with POST /v1/domains/{domain}/dns/validate, using the same body you will save.
2 Save it with POST /v1/domains/{domain}/dns. Use @ as the name for the domain itself.
3 Read the answer: it shows what ended up in the zone, which is what counts.

curl https://api.mozout.com/v1/domains/yourcompany.com/dns -X POST \
-H "Authorization: Bearer $RLX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "@", "type": "TXT", "value": "verification=abc123", "ttl": 14400}'

Quotes in a TXT: quotes around the whole value are removed; quotes or backslashes in the middle of the text answer 422, because the DNS server would store a different value. And a CNAME cannot share its name with other records: that answers 409 with cname_conflict.

A record's id changes

A record's id changes when its name, type, value or priority changes; changing only the ttl keeps the same id. Always use the id from the latest list, or the next change answers 404. An AAAA address comes back in its short form.

The domain of the account e-mail

If the e-mail you sign in with, or that of one of your users, is on this domain (or a subdomain of it), the API refuses, with 409 account_email_domain and in Sandbox too, anything that decides where the mail goes: the MX records for that name; the A, AAAA, CNAME and NS records of the name the MX points to (or, without MX, of the name itself); resetting the zone and restoring a backup that touches these records. Make those changes in My MozOut. All other records can still be changed through the API.

Backups and limits

What How it works
Zone backups One before every change; the last 20 per domain are kept.
Incomplete restore If complete comes back false, a record in the backup could not be put back exactly as it was: check the list.
Changes 20 per minute, per account, on top of the general limit.
Zone reads 30 per minute, per account. The list may come from a copy up to 60 seconds old, which does not count towards that limit.
What you change through the API shows at once; what you change in My MozOut can take up to 60 seconds to show in the API. Before a big change, list the backups: if something goes wrong, restoring is a single request.

Want to automate the DNS of your domains? See the API page and test with a Sandbox key, which simulates the changes.

See the API page

SEE ALSO

Domains through the API: checking a name, registering, renewing and transferring with credit

Hosting e-mail through the API: mailboxes, passwords, quotas, forwarders and the default address

Hosting through the API: subdomains, databases, cron jobs, SSL, PHP options and FTP

API request limits: per key, per account and per task, the headers and what to do after a 429

Our API's error codes: what each one means, and which ones are worth retrying

API Sandbox or Production: what each key really does, and moving your program to production

RECOMMENDED PRODUCT

Register your .com domain

Secure your company name before someone else registers it. from £13.60/yr

Search a domain
Was this answer helpful? Your answer helps us improve this article.

Related Articles

Domains & DNS 2,150 How to check a domain DNS Checking a domain’s DNS means finding out where it currently points. It is the first step whenever a site will not open,...
Domains & DNS 2,507 How to find the hosting DNS Whenever you need to point a domain at your MozOut hosting, you will be asked for the nameservers - also called DNS serv...
Domains & DNS 2,312 How to configure a domain DNS Configuring DNS means telling the world where your domain should point. There are two levels, and it is worth separating...
Domains & DNS 2,158 How to change the DNS of a domain already in use Changing the DNS of a domain that already works takes more care than setting up a new one. Here you are not starting fro...
Domains & DNS 2,318 How long DNS changes take to propagate You changed the nameservers or a DNS record and nothing happened yet. That's normal - DNS changes are not instant. How l...
Domains & DNS 2,423 How to transfer a domain to us Bringing a domain you registered elsewhere over to us. The transfer keeps the time you already paid for - it is added to...