---
title: "List custom domains"
method: GET
path: "/v1/domains"
tags: ["Domains"]
---

# List custom domains

`GET /v1/domains`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/domains`
- Auth: HTTP bearer

**Requires scope:** `read`.

## Response `200`

This workspace's custom domains.

- object
  - `data` Domain[], required: Every custom domain in the workspace.
    - `id` string, required: Domain id (`dom_…`).
    - `domain` string, required: The custom sending domain, lowercased.
    - `status` 'pending' | 'verifying' | 'verified' | 'failed', required: pending → records issued; verifying → checks in progress; verified → agents on this domain send under their own identity; failed → 20 verify calls in a row did not pass. Not final: a failed domain is still re-checked automatically (less often the longer it fails, at most a day apart) and verifies by itself once its records resolve; verify still checks at once, and the count starts over on success or after a day without a verify call.
    - `provider` string: Backing sending infrastructure for this domain.
    - `dns_records` DnsRecord[], required: The records to create at your DNS host. Each record's `verified` says whether the last check found it, and every `required` one must be found for the domain to verify.
      - `type` 'TXT' | 'CNAME' | 'MX', required: DNS record type to create.
      - `host` string, required: Fully-qualified record host/name to create at your DNS provider.
      - `value` string, required: Exact record value. Copy verbatim.
      - `purpose` 'spf' | 'dkim' | 'dmarc' | 'return_path' | 'tracking' | 'ownership', required: What the record is for: `dkim` (the key that signs your mail), `return_path` (the bounce address), `spf` and `dmarc` (your domain's sender policy), `tracking` (link tracking), or `ownership` (any other record the sending provider asks for, such as proof you control the domain).
      - `required` boolean, required: Required records gate verification; optional ones improve deliverability/reporting.
      - `verified` boolean, required: Whether the record was observed in DNS on the last check.
      - `instruction` string: How to create this record, word for word from the provider. For SPF and DMARC it says when to merge the value into a record the domain already publishes instead of replacing it, because replacing one can break the domain's existing mail.
      - `merge_token` string: The part to add to an existing record when merging (for SPF, e.g. `ip4:…`). A merged SPF record that contains it verifies.
    - `fail_reason` string, nullable: Why the last verification did not pass, when it didn't.
    - `last_check_at` string, date-time, nullable: When the records were last checked: by a verify call, by the automatic re-checks of unverified domains, or by the daily re-check of verified ones. Null before the first check.
    - `verified_at` string, date-time, nullable: When the domain first verified. Null until then, and cleared again when the daily re-check of verified domains (06:40 UTC) finds a required record gone.
    - `created_at` string, date-time, required: When the domain was added (UTC).
  - `has_more` boolean, required: Always `false`: every domain comes in one response.
  - `next_cursor` string: Pass as `cursor` to fetch the next page. Absent on the last page.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `500`: Internal server error.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)