---
title: "Add a domain"
method: POST
path: "/api/v1/domains"
tags: ["Domains"]
---

# Add a domain

`POST /api/v1/domains`

## Request

- Base URL: `https://supermailos.com`
- URL: `https://supermailos.com/api/v1/domains`
- Auth: HTTP bearer

Adds a domain and answers with the DNS records to publish at its DNS host, and where to publish them (`setup`). Nothing changes in the domain's DNS or where its email goes today: publishing the MX records later moves its incoming email here. A domain the workspace already has comes back unchanged (`200`, `created: false`). A workspace owner's or admin's key; plan limits apply (`403` `limit_reached`), and at most 10 domains an hour can be added through the API.

## Request body

- object
  - `domain` string, required: A domain you own, or a subdomain of one (agents.acme.com).

## Response `200`

The workspace already has it.

- object
  - `domain` Domain, required
    - `id` string, required
    - `domain` string, required
    - `kind` 'custom' | 'instant', required: `instant`: the workspace's free subdomain of ours, with nothing to set up.
    - `status` 'pending' | 'verifying' | 'verified' | 'failed', required
    - `canSend` boolean, required: Mail can be sent from it (it's verified).
    - `createdAt` string, date-time, required
    - `verifiedAt` string, date-time, nullable, required
    - `lastCheckedAt` string, date-time, nullable, required
    - `nextCheckAt` string, date-time, nullable, required: The next scheduled check, while it isn't verified.
    - `problems` string[], required: What's wrong, one line per failing required record.
    - `records` DnsRecord[], required
      - `purpose` 'mx' | 'spf' | 'dkim' | 'dmarc' | 'tracking' | 'bimi', required
      - `type` 'MX' | 'TXT' | 'CNAME', required
      - `host` string, required: Relative to the domain: `@` is the domain itself.
      - `name` string, required: The full name the record lives at.
      - `value` string, required
      - `priority` integer: MX only.
      - `ttl` integer
      - `required` boolean, required: Needed to verify the domain.
      - `status` 'unknown' | 'checking' | 'verified' | 'missing' | 'mismatch', required: What the last check found.
      - `reason` string: Why the last definite check failed.
      - `warning` string: A problem that doesn't stop verification (e.g. another provider's MX at the same priority).
      - `suggestedValue` string: A value that would fix it, when one can be computed (e.g. a merged SPF).
    - `setup` DomainSetup
      - `url` string, uri, required: The domain's page in the app: one-click setup for some DNS hosts, step-by-step guides for the rest.
      - `zoneFileUrl` string, uri, required: The records as a BIND zone file (GET /api/v1/domains/{id}/zone).
      - `dnsProvider` object, nullable, required: Where its DNS is hosted, from its nameservers; `null` when we can't tell.
        - `id` string
        - `name` string
        - `oneClick` boolean: The app can write the records with an API token from this host.
      - `nextStep` string, required: What to do next, in a sentence a person can follow.
  - `created` false, required

## Other responses

- `201`: Added.
- `400`: The request is malformed.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks the scope (`missing_scope`) or the access (`forbidden`).
- `404`: Not found — or not reachable with this key.
- `409`: A request with this Idempotency-Key is still in progress.
- `429`: Too many requests.

---

[API](https://skmtc.dev/supermailos/apis/supermailos-api.md) · [All operations](https://skmtc.dev/supermailos/apis/supermailos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/supermailos/apis/supermailos-api/revisions/5bd0ce2ee269?raw)