Mail API reference

Mail API · Domains

post/v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/checkAuth

Check the domain's DNS records now.

Queries the zone's authoritative nameservers and a public resolver for every record, stores the result, flips a pending domain whose required records pass to `active`, and returns the same body as `GET .../dns-records`. Never fails because records are missing: their states say so. Limited to one call per domain every 10 seconds. Safe to retry: it changes nothing but the stored check result, so it takes no Idempotency-Key.

Path parameters

workspace_id*string · uuid

Id of the workspace.

domain_id*string · uuid

Id of the domain.

Query parameters

zonestring · hostname

As on `GET .../dns-records`.

Response · 200

domain_id*string · uuid

The domain id.

fqdn*string

The domain name.

Example: "mail.example.com"

status*object

Verification status of the domain.

health*object

Drift on a verified domain. `degraded`: a required record (DKIM, or MX for receiving) went missing or changed, or DKIM signing no longer verifies; mail still flows and workspace owners are emailed. `failing`: still degraded 72 h later; sends from the domain are refused with 422 `domain_not_verified_by_provider`. Back to `ok` as soon as the records are. A failed DNS lookup never changes it, and recommended records (MAIL FROM, DMARC) never do. Always `ok` while the domain is not `active`.

Example: "ok"

health_changed_at*string · date-time

When `health` last changed; null if it has always been `ok`.

health_grace_ends_at*string · date-time

While `health` is `degraded`: when the 72 h grace ends and the domain becomes `failing` unless the records are back. Null otherwise.

zone*string

Zone the relative names are rendered against: the `zone` query parameter, else the zone found by walking SOA records (null before the first check).

Example: "example.com"

last_checked_at*string · date-time

When the records were last checked; null if never.

records*array

Each required and recommended record with its current state.

ses*object
enabled*boolean

Whether sending verification (DKIM signing) is switched on for this deployment.

dkim_status*object

DKIM signing verification of the DKIM record. `not_enabled` where sending verification is off in this environment (local, preview); null while the domain is not registered for signing yet.

mail_from_status*object

Verification of the custom MAIL FROM host; null when none is configured.

Example

Request

POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/check
Authorization: Bearer YOUR_TOKEN

Response

{
  "domain_id": "00000000-0000-0000-0000-000000000000",
  "fqdn": "mail.example.com",
  "status": {},
  "health": "ok",
  "health_changed_at": "2026-01-01T00:00:00.000Z",
  "health_grace_ends_at": "2026-01-01T00:00:00.000Z",
  "zone": "example.com",
  "last_checked_at": "2026-01-01T00:00:00.000Z",
  "records": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "purpose": "dkim",
      "type": "TXT",
      "host": "productcraft._domainkey.mail.example.com",
      "name_relative": "productcraft._domainkey.mail",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqh…",
      "priority": 10,
      "ttl": 3600,
      "required": true,
      "state": "verified",
      "found": [
        "string"
      ],
      "conflicts": [
        {
          "code": "spf_multiple",
          "severity": {},
          "message": "string",
          "suggested_value": "v=spf1 include:amazonses.com include:_spf.google.com ~all"
        }
      ],
      "hint": "Your nameservers already serve it; public resolvers will within ~30 min (the zone's negative-cache TTL is 1800 s).",
      "covered_by": "_dmarc.example.com",
      "first_verified_at": "2026-01-01T00:00:00.000Z",
      "last_checked_at": "2026-01-01T00:00:00.000Z",
      "last_changed_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "ses": {
    "enabled": false,
    "dkim_status": {},
    "mail_from_status": {}
  }
}