Skip to main content
Get Started
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.domains.list();
console.log(result);
{
  "data": [
    {
      "id": "dom_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "domain": "<domain>",
      "status": "pending",
      "provider": "<provider>",
      "dns_records": [
        {
          "type": null,
          "host": null,
          "value": null,
          "purpose": null,
          "required": null,
          "verified": null,
          "instruction": null,
          "merge_token": null
        }
      ],
      "fail_reason": "<fail_reason>",
      "last_check_at": "2026-10-04T12:00:00.000Z",
      "verified_at": "2026-10-04T12:00:00.000Z",
      "created_at": "2026-10-04T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": "<next_cursor>"
}

List custom domains

GET/v1/domainsscope · read
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.domains.list();
console.log(result);
{
  "data": [
    {
      "id": "dom_01JZX8K3M9Q4P7VN2YB6RTDC0E",
      "domain": "<domain>",
      "status": "pending",
      "provider": "<provider>",
      "dns_records": [
        {
          "type": null,
          "host": null,
          "value": null,
          "purpose": null,
          "required": null,
          "verified": null,
          "instruction": null,
          "merge_token": null
        }
      ],
      "fail_reason": "<fail_reason>",
      "last_check_at": "2026-10-04T12:00:00.000Z",
      "verified_at": "2026-10-04T12:00:00.000Z",
      "created_at": "2026-10-04T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": "<next_cursor>"
}

Response

dataobject[]

Every custom domain in the workspace.

Show propertiesHide properties
idstring

Domain id (dom_…).

domainstring

The custom sending domain, lowercased.

statusstring

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.

One of: pending, verifying, verified, failed

providerstring

Backing sending infrastructure for this domain.

dns_recordsobject[]

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.

Show propertiesHide properties
typestring

DNS record type to create.

One of: TXT, CNAME, MX

hoststring

Fully-qualified record host/name to create at your DNS provider.

valuestring

Exact record value. Copy verbatim.

purposestring

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).

One of: spf, dkim, dmarc, return_path, tracking, ownership

requiredboolean

Required records gate verification; optional ones improve deliverability/reporting.

verifiedboolean

Whether the record was observed in DNS on the last check.

instructionstring

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_tokenstring

The part to add to an existing record when merging (for SPF, e.g. ip4:…). A merged SPF record that contains it verifies.

fail_reasonstring | null

Why the last verification did not pass, when it didn't.

last_check_atstring | null

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_atstring | null

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_atstring

When the domain was added (UTC).

has_moreboolean

Always false: every domain comes in one response.

next_cursorstring

Pass as cursor to fetch the next page. Absent on the last page.

Was this page helpful?