# Domains API

Register custom domains, configure DNS, and verify ownership.

## GET /v1/domains

**GET** `/v1/domains`

List all registered domains. Requires full-access key.

```response — 200 OK
{
  "domains": [
    {
      "id": "f6a7b8c9-abcd-4ef0-1234-666666666666",
      "domain": "example.com",
      "status": "VERIFIED",
      "mxVerified": true,
      "spfVerified": true,
      "dkimVerified": true,
      "dmarcVerified": true,
      "createdAt": "2026-03-11T00:00:00.000Z"
    }
  ]
}
```


## POST /v1/domains

**POST** `/v1/domains`

Register a new custom domain. Requires full-access key and paid plan. Returns the DNS records you need to configure.

**Request body**

| Name | Type | Description |
|------|------|-------------|
| `domain`* | `string` | Domain name (e.g. example.com) |

```response — 201 Created
{
  "domain": {
    "id": "f6a7b8c9-abcd-4ef0-1234-666666666666",
    "domain": "example.com",
    "status": "PENDING_VERIFICATION"
  },
  "dnsRecords": {
    "mx": { "type": "MX", "host": "example.com", "value": "mail.robotomail.com", "priority": 10 },
    "sendMx": { "type": "MX", "host": "send.example.com", "value": "feedback-smtp.us-east-1.amazonses.com", "priority": 10 },
    "spf": { "type": "TXT", "host": "send.example.com", "value": "v=spf1 include:amazonses.com ~all" },
    "dkim": [
      { "type": "CNAME", "host": "abc123._domainkey.example.com", "value": "abc123.dkim.amazonses.com" },
      { "type": "CNAME", "host": "def456._domainkey.example.com", "value": "def456.dkim.amazonses.com" },
      { "type": "CNAME", "host": "ghi789._domainkey.example.com", "value": "ghi789.dkim.amazonses.com" }
    ],
    "dmarc": { "type": "TXT", "host": "_dmarc.example.com", "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@robotomail.com" }
  }
}
```

**Note:**DKIM records may be CNAME or TXT depending on Resend's provider configuration. The number of DKIM records may also vary. Always use the exact records returned by the API.

### Errors

- `400` — Invalid domain format
- `403` — Email not verified, or free plan (custom domains require paid)
- `409` — Domain already registered


## GET /v1/domains/:id

**GET** `/v1/domains/:id`

Get domain details including current verification status and DNS records. Requires full-access key.


## POST /v1/domains/:id/verify

**POST** `/v1/domains/:id/verify`

Trigger a DNS verification check. A background job also runs every 5 minutes, but you can call this to verify immediately after configuring DNS.

```response — 200 OK
{
  "domain": { "id": "f6a7b8c9-abcd-4ef0-1234-666666666666", "status": "VERIFIED" },
  "verification": {
    "mx": true,
    "spf": true,
    "dkim": true,
    "dmarc": true,
    "allVerified": true
  }
}
```

See [Custom domain guide](https://robotomail.com/docs/guides/custom-domain) for a step-by-step walkthrough.


## DELETE /v1/domains/:id

**DELETE** `/v1/domains/:id`

Remove a domain. Mailboxes on this domain will stop receiving email. Requires full-access key.

```response — 200 OK
{ "deleted": true }
```


---

Previous: [Events (SSE)](https://robotomail.com/docs/api/events.md) | Next: [Attachments](https://robotomail.com/docs/api/attachments.md)