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

const client = createClient(); // reads MAILS_API_KEY

const result = await client.domains.verify(
  "dom_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);
{
  "id": "dom_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "domain": "<domain>",
  "status": "pending",
  "provider": "<provider>",
  "dns_records": [
    {
      "type": "TXT",
      "host": "<host>",
      "value": "<value>",
      "purpose": "spf",
      "required": false,
      "verified": false,
      "instruction": "<instruction>",
      "merge_token": "<merge_token>"
    }
  ],
  "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"
}

Verify a domain now

Re-checks every DNS record and updates per-record + overall status.
POST/v1/domains/{id}/verifyscope · manage
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.domains.verify(
  "dom_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);
{
  "id": "dom_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "domain": "<domain>",
  "status": "pending",
  "provider": "<provider>",
  "dns_records": [
    {
      "type": "TXT",
      "host": "<host>",
      "value": "<value>",
      "purpose": "spf",
      "required": false,
      "verified": false,
      "instruction": "<instruction>",
      "merge_token": "<merge_token>"
    }
  ],
  "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"
}

Path Parameters

idstringrequired

Domain id (dom_…).

Each call is an attempt: one that does not pass counts toward failed, 20 in a row mark the domain failed, and the count starts over on success or after a day without a call. Polling is rarely needed. We re-check an unverified domain every 15 minutes and a failed one at least daily, without counting, whatever its age or the workspace's plan, and it verifies at the first check after its records resolve.

Response

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

Was this page helpful?