# MailDNS docs

MailDNS is one API for all your registrars. Your registrar accounts are connected once; a MailDNS key then manages DNS records on the domains it was issued for, in the API style of any of six registrars. Code written for one of them works after you change the base URL and the key.

## API styles

| Style | Base URL | Auth |
|---|---|---|
| [Dynadot](https://maildns.io/docs/dynadot.md) | `https://api.maildns.io/api3.json` | `key=KEY` parameter |
| [Spaceship](https://maildns.io/docs/spaceship.md) | `https://api.maildns.io/api/v1` | `X-API-Key: KEY`, `X-API-Secret: SECRET` |
| [Cloudflare](https://maildns.io/docs/cloudflare.md) | `https://api.maildns.io/client/v4` | `Authorization: Bearer KEY` |
| [GoDaddy](https://maildns.io/docs/godaddy.md) | `https://api.maildns.io/v1` | `Authorization: sso-key KEY:SECRET` |
| [Porkbun](https://maildns.io/docs/porkbun.md) | `https://api.maildns.io/api/json/v3` | `apikey` and `secretapikey` in the JSON body |
| [Namecheap](https://maildns.io/docs/namecheap.md) | `https://api.maildns.io/xml.response` | `ApiKey=KEY` parameter |

- All six take the same key and reach the same records. Mix them freely.
- The style doesn't have to match the registrar that holds a domain: a GoDaddy-style script can manage a domain held at Porkbun.
- The live check, `dns_status`, is a [Dynadot-style](https://maildns.io/docs/propagation.md) call. It takes the same key whichever style you write with.

## Registrars you can connect

Dynadot, Spaceship, Cloudflare, GoDaddy, Porkbun and Namecheap. Accounts are by invitation: when yours is set up, you connect your registrar accounts through a private link. Each registrar key is checked when you add it and is never shown again. Then MailDNS issues keys for the domains you choose.

## What a key can do

- List the domains and hosts it was issued for, and read their records.
- Add, change and delete `A`, `AAAA`, `CNAME`, `MX` and `TXT` records on them, at a host and under it (`_dmarc.advisor.example.com`, `google._domainkey.advisor.example.com`).
- Read the current nameservers.
- Ask the authoritative nameservers whether a record is live, before you ask Google or Microsoft to verify it.

## What a key can't do

- **Change nameservers, ever.** No key can change nameservers or add NS records, in any style. The answer is always `This API key doesn't work for nameservers.`
- See or change anything it wasn't issued for: other domains in your accounts, or records of a root domain outside its hosts.
- Add domains or hosts to itself. MailDNS sets them when the key is issued.
- Register, renew, transfer or delete domains, or change contacts or forwarding.
- Use record types other than the five above (no `NS`, `SRV`, `CAA`, forwarding records).

## Words

- **Host**: a name a key manages, such as `advisor.example.com`, or a whole domain such as `example.com`. You manage records **at** the host and **under** it.
- **Root domain**: the registered domain a host lives in (`example.com`). When a key is issued for a host inside it, the root's other records are not yours.
- **Main record** (Dynadot) or **`@`** (most other styles): a record at the name you addressed, not under it.
- **Subhost** or **name**: the part of a record's name in front of the name you addressed, such as `_dmarc` or `google._domainkey`.

## Where to start

- [Quickstart](https://maildns.io/docs/quickstart.md): from a new key to a live record in five calls.
- [Hosts](https://maildns.io/docs/hosts.md): the two ways to name a host, in each style, and which calls replace records.
- [Recipe: Google Workspace on a subdomain](https://maildns.io/docs/google-workspace.md): the whole flow, with a complete script, and step 1 in all six styles.
- [For AI agents](https://maildns.io/docs/agents.md): `llms.txt`, `llms-full.txt`, and a briefing to paste into your agent.