# Domains & onboarding

{/* // ONE RECORD, NOT TEN */}

Where do mailboxes live? Postern gives you four onboarding modes, from zero-config to bring-your-own.
The headline path — **NS delegation** — lets you put agents on `mail.yourco.com` by adding exactly
**one DNS record**, then never touching DNS again.

## The four modes
**1 · Shared subdomain**
**Default, zero-config.** Mailboxes land on a pre-warmed, pre-verified shared `mszazu.com`
    subdomain — `agent@<label>.mszazu.com`. Instant. We steward reputation; abuse is bounded by
    credits and karma.

**2 · NS delegation**
**The differentiator.** Add one `NS` record pointing a subdomain at our nameservers. Our
    authoritative DNS then serves MX, SPF, DKIM, and DMARC for it — we control and rotate DKIM, you
    do no further DNS work.

**3 · Buy through us**
We register a domain on your behalf and auto-wire every record. The zero-DNS-work ideal —
    register-and-provision in one step. ops-assisted in V1

**4 · Manual**
The AgentMail-style fallback: we output the TXT / MX / DKIM records and you add them. De-emphasized
    — and **CNAME-to-us is rejected** because it breaks DKIM control.

## NS delegation — the headline flow

The premise: most agentic-email products make you add a fistful of DNS records and re-add them
whenever keys rotate. Postern asks for **one** `NS` record, then becomes authoritative for that
subdomain so every other record — and every future DKIM rotation — happens on our side.

1. **Pick a subdomain** you'll dedicate to agents, e.g. `mail.theirco.com`. (Use a subdomain, never
   your apex — this keeps your main mail untouched.)

2. **Add one `NS` record** at your registrar, delegating that subdomain to Postern's nameservers:

   ```ini title="at your DNS provider"
   mail.theirco.com.   NS   ns1.mszazu.com.
   mail.theirco.com.   NS   ns2.mszazu.com.
   ```

3. **Postern becomes authoritative.** Our DNS server (`postern-dns`, built on `miekg/dns`,
   DB-backed) now answers for `mail.theirco.com` and serves the records mailboxes need:

   ```ini title="served by ns1/ns2.mszazu.com (automatic)"
   mail.theirco.com.        MX    10 inbound.mszazu.com.
   mail.theirco.com.        TXT   "v=spf1 include:spf.mszazu.com -all"
   selector1._domainkey.mail.theirco.com.   CNAME   …acs-dkim…
   _dmarc.mail.theirco.com. TXT   "v=DMARC1; p=none; rua=mailto:dmarc@mszazu.com"
   ```

4. **Verification flips to `verified`.** Once the `NS` delegation resolves and the served records are
   live, the domain's `verification_status` and `dkim_status` go green — no per-record dance.

5. **Create mailboxes on it.** `domain: "mail.theirco.com"` on any create now works, within the
   enrollment key's `allowed_domains`.
**Why NS delegation wins:** After the one `NS` record, **DKIM rotation never touches your DNS again** — Postern re-serves the
  new selector from our authoritative zone. Manual-DNS competitors make you re-add records on every
  rotation. One record, then silence.

### Our authoritative DNS, in brief

| Piece | Detail |
|---|---|
| Nameservers | `ns1.mszazu.com`, `ns2.mszazu.com` (public, UDP/TCP 53) |
| Server | `postern-dns` — Go, `miekg/dns` (the library CoreDNS is built on), DB-backed by `dns_zones` / `dns_records` |
| Why our own | Dynamic, per-tenant records + programmatic DKIM rotation with full control — over a static zone file |
| Records served | A / MX / SPF / DKIM (CNAME) / DMARC for each delegated subdomain |

## Verification status

Each onboarded domain carries a `verification_status` and a `dkim_status`:

| State | Meaning |
|---|---|
| `pending` | Delegation/records not yet observed. |
| `verifying` | Records seen; ACS verification in flight. |
| `verified` | Domain is live; mailboxes can be created on it. |
| `failed` | Delegation or DKIM didn't resolve — re-check the `NS` record. |

## Manual mode (the fallback)

If you can't delegate, Postern outputs the exact TXT / MX / DKIM records to add and verifies them.
It's supported but de-emphasized, and it loses the auto-rotation benefit. **CNAME-to-us is rejected**
on purpose: it would hand DKIM control back to your DNS and break our ability to rotate keys.

## Next

- [Inboxes](https://docs.agents.mszazu.com/concepts/inboxes/) — creating mailboxes on an onboarded domain.
- [Deliverability & karma](https://docs.agents.mszazu.com/concepts/deliverability-and-karma/) — what we do with that DNS authority.
- [Self-host](https://docs.agents.mszazu.com/operating/self-host/) — running the DNS + API yourself.