# List sending domains

`GET /v1/sending-domains`

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

Returns the sending domains in this organization with their verification state. Results are cursor-paginated: pass `meta.pagination.nextCursor` back as `cursor` until it comes back `null`. The cursor is opaque — do not construct or parse one.

## Query parameters

- `limit` (integer, optional, min > 0, max 100, default `20`)
- `cursor` (string, optional, 1–2048 characters)

## Returns

Returns `200 OK` with a list of `SendingDomain` objects in `data`, and the next page's cursor in `meta` (see [pagination](/docs/api/pagination)). 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 https://api.kirora.io/v1/sending-domains \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```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"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    }
  }
}
```