Mail API reference

Mail API · Domains

patch/v1/workspaces/{workspace_id}/domains/{domain_id}Auth

Update domain settings: capabilities, DNS provider hint, custom MAIL FROM subdomain, DMARC recommendation.

`intent` (or Resend's `capabilities`) changes what the domain is used for. A pending domain just changes; a verified domain gaining sending or receiving has the new records checked live and is refused with 409 `CAPABILITY_NOT_VERIFIED` (the records to publish in `details.records`) until they pass. Turning receiving off is refused while active mailboxes exist (409 `DOMAIN_HAS_MAILBOXES`, the mailboxes in `details.mailboxes`; deleted mailboxes do not count); turning sending off also turns the custom MAIL FROM off. `tls`, `open_tracking`, `click_tracking` and `tracking_subdomain` are accepted for Resend compatibility; only the values in effect today pass (422 otherwise). `dns_provider` is the provider the setup wizard renders host names for. `mail_from_subdomain` sets the custom MAIL FROM label (`bounce` → `bounce.<fqdn>`; `null` turns it off): the domain's record set gains the MAIL FROM MX + SPF records, and once the domain is verified its MAIL FROM is pointed there (the default return address stays in use until the MX record is found, so mail never stops). Refused with 409 when that host already carries records that are not ours. `dmarc_managed: false` hides the `_dmarc` recommendation for domains whose DMARC is managed elsewhere (the policy is still detected and graded).

Path parameters

workspace_id*string · uuid

Id of the workspace.

domain_id*string · uuid

Id of the domain.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window.

Request body

tlsenum (2)

`opportunistic` only for now (TLS whenever the receiver offers it); `enforced` is refused with 422 `TLS_ENFORCED_NOT_AVAILABLE`.

open_trackingboolean

Only `false` for now; `true` is refused with 422 `TRACKING_NOT_AVAILABLE`.

Example: false

click_trackingboolean

Only `false` for now; `true` is refused with 422 `TRACKING_NOT_AVAILABLE`.

Example: false

tracking_subdomainstring

Not available yet: any value is refused with 422 `TRACKING_NOT_AVAILABLE`.

intentenum (3)

Change how the domain is used. On a verified domain, a capability it gains must verify first: its records are checked live and the change is refused with 409 `CAPABILITY_NOT_VERIFIED` (records to publish in `details.records`) until they pass. Dropping receiving is refused with 409 `DOMAIN_HAS_MAILBOXES` while active mailboxes exist (listed in `details.mailboxes`). Same as `capabilities`; send one or the other, or both in agreement.

capabilitiesobject

Resend's shape of `intent`. Omitted fields keep their current value; at least one must stay enabled.

dns_providerstring

Identifier from the wizard's provider list. Free-form so we can ship new entries without a migration. NULL clears the choice.

mail_from_subdomainstring

Custom MAIL FROM label: one DNS label, so `bounce` makes the envelope sender `…@bounce.<fqdn>` and SPF align with the From domain. `null` turns the custom MAIL FROM off (the default return address is used; DKIM still aligns). Sending domains only.

Example: "bounce"

dmarc_managedboolean

false: do not recommend a `_dmarc` record for this domain (DMARC is managed elsewhere). The policy that applies is still detected and graded in `dmarc_grade`.

Example: false

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

PATCH https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/domains/{domain_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "tls": "opportunistic",
  "open_tracking": false,
  "click_tracking": false,
  "tracking_subdomain": "string",
  "intent": "receive",
  "capabilities": {},
  "dns_provider": "string",
  "mail_from_subdomain": "bounce",
  "dmarc_managed": false
}

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"
}