# Connect your own domain: DNS records

> Put agent inboxes and human mailboxes on your own domain: add five DNS records at any provider, or connect in one click where supported. Paid plans.

Source: https://trotta.email/docs/domains

Every inbox starts on `trotta.email`. Put yours on your own name instead, for humans and for agents: five records at any DNS provider, or one click where your provider supports it. Your own domain is part of the paid plans.

## Three steps in the console

1. **Add your domain.** Open [Domains](https://trotta.email/console/domains) and type the name.
2. **Publish its records.** Copy the five records into your DNS provider, or import the zone file, then check them. Where your provider supports one click, a button above them does it for you.
3. **Create your mailbox.** Once the domain is verified, create your own mailbox on it and add inboxes for your agents.

## Add the domain

```bash
curl -X POST https://api.trotta.email/v1/domains \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "agents.example.com"}'
```

The response lists the five records and the `zone` the domain lives in. Use a subdomain such as `agents.example.com` to leave mail for the name above it where it is.

## The records, by hand

This works at every DNS provider.

| Purpose | Type | What it is for |
| --- | --- | --- |
| `ownership` | TXT | Proves the domain is yours. |
| `inbound` | MX | Routes mail for the domain to Trotta Mail, so it is screened on arrival. |
| `spf` | TXT | Says Trotta Mail may send for the domain. |
| `dkim` | TXT | The public key that outgoing mail is signed against. |
| `dmarc` | TXT | Tells receivers what to do with mail that fails the two checks above. |

- Each record has its `name` in full and its `host`, the part before the zone (`@` for the zone itself). Most providers ask for the host; some want the full name.
- Already have an SPF record? Keep one: after a check, the `spf` value is your record with ours merged in.
- `GET /v1/domains/{id}/zone-file` returns the same records as a BIND zone file to import. Use the values from your own response, not from an example.

## One click, where your provider supports it

Domain Connect lets you approve the records at your DNS provider. You sign in there, see the changes and approve. We never see your password or a token. It works once your provider has switched on Trotta Mail.

```bash
curl -X POST https://api.trotta.email/v1/domains/dom_2Yq5hLf6/connect \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

- `available: true` comes with `provider` and `url`: open the link in a browser. Your provider sends you back to the console, which checks the records.
- `available: false` comes with a `reason`: add the records by hand.
- Your provider merges our SPF include into yours. An existing DMARC policy is never replaced.
- If mail for the name goes elsewhere today, the call answers `409 mx_conflict`. Send `replace_mx: true` to move it here.

## Verify

`POST /v1/domains/{id}/verify` checks again, asking the zone's own name servers first, so a record published a moment ago is seen. Each record comes back `ok`, `missing` or `wrong` (something else is there, listed in `found`). The domain is `verified` once the ownership and inbound records are in place, and a `domain.verified` event is sent. Publish the other three before you send from it.

## Your own mailbox on it

Signed in, create a mailbox for yourself with `kind: "human"`. It is yours alone. You can sign in with it or with your `trotta.email` address, and make it your main address, the one the app shows and writes from by default.

```bash
# as the signed-in human, or with a key that human made
curl -X POST https://api.trotta.email/v1/inboxes \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "jordan", "kind": "human", "domain": "example.com"}'
```

`POST /v1/auth/main-address` with that inbox's id makes it the main address. Mailboxes for teammates on the same domain come from [Team and seats](https://trotta.email/docs/team).

## Agent inboxes on it

```bash
curl -X POST https://api.trotta.email/v1/inboxes \
  -H "Authorization: Bearer $TROTTA_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "riley", "domain": "agents.example.com"}'
```

## A paid feature

Your own domain needs a paid plan: 3 on Developer, 25 on Startup. See [plans and limits](https://trotta.email/docs/plans). On Free, adding one answers `403 domain_limit_reached`.

If a plan stops covering a domain that is already connected, the domain is paused, not deleted. Mail for it still arrives and stays in the inbox. Sending from it answers `403 custom_domain_paused` until the plan covers it again. Nothing has to be set up twice.
