Mail API reference

Mail API · Domains

post/v1/workspaces/{workspace_id}/domains/{domain_id}/verifyAuth

Run a synchronous DNS check against this domain; flips status to active when the required record set passes.

Legacy shape, kept as an alias of `POST .../dns-records/check`: returns the domain on success and a 400 with `dns_check_results` when a required record fails. New integrations should use `POST .../dns-records/check`, which returns per-record states.

Path parameters

workspace_id*string · uuid

Id of the workspace.

domain_id*string · uuid

Id of the domain.

Response · 200

id*string · uuid

The domain id.

seq_id*string

Sequential id per workspace.

Example: "3"

workspace_id*string · uuid

The workspace that owns the domain.

owner_account_id*string · uuid

Platform account that added the domain; null when added with an API key.

fqdn*string

The domain name.

Example: "productcraft.co"

name*string

Same as `fqdn` (Resend's field name).

Example: "productcraft.co"

intent*object

How the workspace uses this domain; `capabilities` is the same thing in Resend's shape. Changeable with PATCH.

capabilities*object
sending*object

Sending from this domain (DKIM signing).

Example: "enabled"

receiving*object

Receiving mail at this domain (MX pointed at ProductCraft).

Example: "disabled"

tls*object

TLS on delivery to the receiving server. Always `opportunistic` today (TLS whenever the receiver offers it); `enforced` is not available yet.

Example: "opportunistic"

open_tracking*boolean

Open tracking. Always false: tracking is not available yet.

Example: false

click_tracking*boolean

Click tracking. Always false: tracking is not available yet.

Example: false

tracking_subdomain*string

Tracking subdomain. Always null: tracking is not available yet.

Example: null

status*object

Verification status: `pending` until the required records verify, then `active`; `disabled` when switched off.

Example: "pending"

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.

verification_token*string

Ownership token for the `_productcraft-verify` TXT. Issued for receive-only domains; sending domains prove ownership with their DKIM record, so it is null for send/both domains created since 2026-10.

test_token*string

Token in the domain's test address (`test-<token>@<domain>`); a mail sent there proves receiving works.

test_received_at*string · date-time

When a test mail to the test address last arrived; null if none yet.

dkim_selector*string

DKIM selector the domain signs with; null until DKIM is set up.

dkim_public_key*string

Public DKIM key in PEM form (private half stays server-side).

dns_provider*object

The effective DNS provider: the user's choice when set, otherwise the one detected from the zone's NS records; null when neither is known. Changed in 2026-10 from the raw id string, which is now `dns_provider_id`.

dns_provider_id*string

The provider id chosen in the setup wizard (PATCH `dns_provider`), or null when not chosen. Kept for one release for clients that read the old string `dns_provider`; use `dns_provider.id`.

Example: "cloudflare"

dns_provider_detected*object

DNS provider detected from the zone's NS records when the domain was added; `dns_provider` reports the effective one.

verification_status*object

One status in Resend's vocabulary, derived from `status`, `health`, `intent` and the record states; first match wins. `disabled`: the domain is disabled. `failed`: `health` is `failing`, or still pending 72 h after it was added. `temporary_failure`: verified, but a required record went missing or changed (`health = degraded`, within the 72 h grace). `verified`: active and healthy. `partially_verified`: a send + receive domain where exactly one of sending (DKIM, and DKIM signing) and receiving (MX) verifies. `pending`: checked at least once, not verified yet. `not_started`: not checked yet. Recommended records (MAIL FROM, DMARC) never change it; see `recommended_pending`.

Example: "pending"

recommended_pending*integer

Recommended records (custom MAIL FROM MX + SPF, DMARC) that are not verified yet. Informational; they never block the domain.

Example: 2

region*string

The region mail from this domain is sent from, e.g. `eu-north-1`. Read-only and the same for every domain of this deployment; null when not configured.

Example: "eu-north-1"

region_name*string

Display name of `region`.

Example: "Stockholm"

dns_check_results*object

Snapshot of the most recent DNS check, as recorded by the checker (its keys are not a stable contract; `GET .../dns-records` returns the typed per-record results).

last_dns_check_at*string · date-time

When the DNS records were last checked; null if never.

dns_zone*string · hostname

Zone apex found by walking SOA records up from the fqdn; null before the first check.

Example: "example.com"

ses_dkim_status*object

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

mail_from_subdomain*string

Custom MAIL FROM label (`bounce` → `bounce.<fqdn>`); null when off. On by default for sending domains created since 2026-10.

Example: "bounce"

mail_from_status*object

Verification of the custom MAIL FROM host (its MX record); null when no custom MAIL FROM is configured.

dmarc_managed*boolean

false when the customer opted out of our `_dmarc` recommendation (PATCH `dmarc_managed`).

Example: true

setup_method*object

How the DNS records were last set up by an automated path: `provider_api` after `POST .../dns-records/apply` wrote them with a provider token, `domain_connect` after a Domain Connect flow. Null when the records were (or are being) added by hand.

Example: null

dmarc_grade*object

The DMARC policy that governs this domain, graded on the last check; null before the first check of a sending domain.

verified_at*string · date-time

When the domain was first verified; null until then.

created_at*string · date-time

When the domain was added.

dns_instructions*array

DNS records to publish for this domain's intent. Records with `required: true` gate `active`; the rest are informational.

records*array

The same records in Resend's `records[]` shape, each with its status.

test_address*string

Convenience accessor for the test-email mailbox address on this domain.

Example: "test-abc123@productcraft.co"

Example

Request

POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/domains/{domain_id}/verify
Authorization: Bearer YOUR_TOKEN

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "seq_id": "3",
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "owner_account_id": "00000000-0000-0000-0000-000000000000",
  "fqdn": "productcraft.co",
  "name": "productcraft.co",
  "intent": {},
  "capabilities": {
    "sending": "enabled",
    "receiving": "disabled"
  },
  "tls": "opportunistic",
  "open_tracking": false,
  "click_tracking": false,
  "tracking_subdomain": null,
  "status": "pending",
  "health": "ok",
  "health_changed_at": "2026-01-01T00:00:00.000Z",
  "health_grace_ends_at": "2026-01-01T00:00:00.000Z",
  "verification_token": "string",
  "test_token": "string",
  "test_received_at": "2026-01-01T00:00:00.000Z",
  "dkim_selector": "string",
  "dkim_public_key": "string",
  "dns_provider": {},
  "dns_provider_id": "cloudflare",
  "dns_provider_detected": {},
  "verification_status": "pending",
  "recommended_pending": 2,
  "region": "eu-north-1",
  "region_name": "Stockholm",
  "dns_check_results": {},
  "last_dns_check_at": "2026-01-01T00:00:00.000Z",
  "dns_zone": "example.com",
  "ses_dkim_status": {},
  "mail_from_subdomain": "bounce",
  "mail_from_status": {},
  "dmarc_managed": true,
  "setup_method": null,
  "dmarc_grade": {},
  "verified_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "dns_instructions": [
    {
      "purpose": "dkim",
      "type": "TXT",
      "host": "productcraft._domainkey.mail.example.com",
      "value": "string",
      "ttl": 0,
      "priority": 0,
      "required": true
    }
  ],
  "records": [
    {
      "record": "DKIM",
      "purpose": "dkim",
      "name": "productcraft._domainkey.mail",
      "type": "TXT",
      "value": "string",
      "priority": 10,
      "ttl": 3600,
      "status": "verified",
      "required": true
    }
  ],
  "test_address": "test-abc123@productcraft.co"
}