Create a domain and its DNS records

POST https://api.dairo.app/v1/domains

Registers a domain you own for authenticated sending and inbound receiving, and returns the created domain object with the records array to publish in DNS. Those records are DKIM CNAME records, an MX and an SPF TXT record on the mail. sending subdomain, an MX record on the root domain for receiving replies, and a DMARC TXT record on _dmarc; each record reports its own status of pending or configured. A new domain starts at status: "pending" and stays there until you publish the records and it passes a recheck — see verify a domain. The call is idempotent on the domain name: re-creating a domain you already own returns the existing record instead of erroring, so a retry is safe without an Idempotency-Key. A domain another account has verified, or claimed within the last 72 hours, is refused with a 409; an older claim that never verified and has no inboxes is released to you, so nobody can hold a domain they cannot prove. dairo.app cannot be created because it is included with every account. Only a key whose creator is an organization owner or admin may add domains, and a key restricted to specific inboxes is refused with a 403. Requires domains:write, counts against your plan's domain limit (a 429 once reached), and is rate-limited to 10 create calls per hour.

Scope: domains:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

curl -X POST "https://api.dairo.app/v1/domains" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com"
  }'

Headers

Body

Required, application/json: CreateDomainRequest.

Response

201 Created. Body: application/json, Domain.

{
  "object": "domain",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "domain": "orin-ai.app",
  "status": "pending",
  "verifiedAt": "2026-10-19T09:30:00Z",
  "region": "eu-north-1",
  "records": [
    {
      "type": "CNAME",
      "host": "string",
      "value": "string",
      "priority": null,
      "status": "pending"
    }
  ],
  "type": "custom",
  "isIncluded": true,
  "isDeletable": true,
  "isSystem": true,
  "isReadOnly": true,
  "receiving": "active"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.