# Add a sending domain

`POST /v1/sending-domains`

Requires an API key with the `domains:write` scope. [About keys and scopes](/docs/api/authentication)

Registers a domain to send from and returns the DNS records to publish. The domain cannot send until those records are in place and verification has succeeded.

## Request body

- `domain` (string, required, 3–253 characters)

## Returns

Returns `201 Created` with a `SendingDomain` in `data`. Otherwise returns an error; [Errors](/docs/api/errors) lists every code and which to retry.

- `id` (string, required, uuid)
- `domain` (string, required)
- `status` (string, required, one of `pending`, `verified`, `failed`) — Whether the provider has verified the domain for sending.
- `ownershipStatus` (string, required, one of `pending`, `verified`) — Whether proof that you control the domain has been found in DNS.
- `ownershipRecord` (object, required) — The record that proves you control the domain.
  - `type` (string, required, one of `CNAME`, `TXT`, `MX`)
  - `name` (string, required) — The full hostname to publish the record at.
  - `value` (string, required) — What the record must contain.
  - `found` (string[], optional) — What DNS returned for this name and type at the last check; absent before one.
  - `matches` (boolean, optional) — Whether `found` holds `value`; absent before a check.
- `separateOwnershipRecord` (boolean, required) — False for a domain added since one-trip setup: `ownershipRecord` is its DKIM record, listed in `dnsRecords` with the others. True for older domains, whose ownership TXT is published first and on its own.
- `provisioningStatus` (string, required, one of `awaiting_proof`, `provisioning`, `provisioned`, `quarantined`) — Setup progress at the email provider: `awaiting_proof` until ownership is shown, then `provisioning`, `provisioned`. `quarantined`: the domain is already set up at the provider by someone else, so nothing sends from it until Kirora support reviews it.
- `dnsRecords` (object[], required) — The records to publish at your DNS host.
  - `type` (string, required, one of `CNAME`, `TXT`, `MX`)
  - `name` (string, required) — The full hostname to publish the record at.
  - `value` (string, required) — What the record must contain.
  - `found` (string[], optional) — What DNS returned for this name and type at the last check; absent before one.
  - `matches` (boolean, optional) — Whether `found` holds `value`; absent before a check.
- `provider` (string, required) — The email provider that sends for the domain.
- `failureReason` (string | null, required) — Why verification failed, when it has.
- `readinessChecks` (object | null, required) — Per-check results from the last verification; null before one.
  - `identity` (string, required, one of `pending`, `verified`, `failed`) — The sending identity.
  - `dkim` (string, required, one of `pending`, `verified`, `failed`) — The DKIM signing records.
  - `mailFrom` (string, required, one of `pending`, `verified`, `failed`) — The custom MAIL FROM (`bounce.`) records.
  - `dmarc` (object, required) — The DMARC record covering the domain.
    - `status` (string, required, one of `valid`, `missing`, `invalid`, `unknown`) — Whether a usable DMARC record was found.
    - `policy` (string | null, required, one of `none`, `quarantine`, `reject`) — The policy the DMARC record sets.
    - `policyDomain` (string | null, required) — The domain the DMARC record was found on.
    - `inherited` (boolean, required) — True when the record is the parent domain's, not the domain's own.
- `verificationCheckedAt` (string | null, required, date-time) — When DNS was last checked.
- `verificationCurrent` (boolean, required) — Whether the domain can send now; see `verificationReadinessReason` if not.
- `verificationReadinessReason` (string | null, required, one of `inactive_provider`, `quarantined`, `provisioning_incomplete`, `provider_unverified`) — Why `verificationCurrent` is false; null when it is true.
- `createdAt` (string, required, date-time)
- `updatedAt` (string, required, date-time)

## Example

```bash
curl -X POST https://api.kirora.io/v1/sending-domains \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "domain_example"
  }'
```

Response `201`:

```json
{
  "data": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "domain": "domain_example",
    "status": "pending",
    "ownershipStatus": "pending",
    "ownershipRecord": {
      "type": "CNAME",
      "name": "Weekend specials",
      "value": "value_example"
    },
    "separateOwnershipRecord": true,
    "provisioningStatus": "awaiting_proof",
    "dnsRecords": [
      {
        "type": "CNAME",
        "name": "Weekend specials",
        "value": "value_example"
      }
    ],
    "provider": "provider_example",
    "failureReason": "failureReason_example",
    "readinessChecks": {
      "identity": "pending",
      "dkim": "pending",
      "mailFrom": "pending",
      "dmarc": {
        "status": "valid",
        "policy": "none",
        "policyDomain": "policyDomain_example",
        "inherited": true
      }
    },
    "verificationCheckedAt": "2030-03-14T09:30:00Z",
    "verificationCurrent": true,
    "verificationReadinessReason": "inactive_provider",
    "createdAt": "2030-03-14T09:30:00Z",
    "updatedAt": "2030-03-14T09:30:00Z"
  }
}
```