/v1/workspaces/{workspace_id}/domains/{domain_id}AuthUpdate 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 · uuidId of the workspace.
domain_id*string · uuidId of the domain.
Headers
Idempotency-KeystringOpaque 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_trackingbooleanOnly `false` for now; `true` is refused with 422 `TRACKING_NOT_AVAILABLE`.
Example: false
click_trackingbooleanOnly `false` for now; `true` is refused with 422 `TRACKING_NOT_AVAILABLE`.
Example: false
tracking_subdomainstringNot 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.
capabilitiesobjectResend's shape of `intent`. Omitted fields keep their current value; at least one must stay enabled.
dns_providerstringIdentifier from the wizard's provider list. Free-form so we can ship new entries without a migration. NULL clears the choice.
mail_from_subdomainstringCustom 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_managedbooleanfalse: 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 · uuidThe domain id.
seq_id*stringSequential id per workspace.
Example: "3"
workspace_id*string · uuidThe workspace that owns the domain.
owner_account_id*string · uuidPlatform account that added the domain; null when added with an API key.
fqdn*stringThe domain name.
Example: "productcraft.co"
name*stringSame as `fqdn` (Resend's field name).
Example: "productcraft.co"
intent*objectHow the workspace uses this domain; `capabilities` is the same thing in Resend's shape. Changeable with PATCH.
capabilities*objectsending*objectSending from this domain (DKIM signing).
Example: "enabled"
receiving*objectReceiving mail at this domain (MX pointed at ProductCraft).
Example: "disabled"
tls*objectTLS on delivery to the receiving server. Always `opportunistic` today (TLS whenever the receiver offers it); `enforced` is not available yet.
Example: "opportunistic"
open_tracking*booleanOpen tracking. Always false: tracking is not available yet.
Example: false
click_tracking*booleanClick tracking. Always false: tracking is not available yet.
Example: false
tracking_subdomain*stringTracking subdomain. Always null: tracking is not available yet.
Example: null
status*objectVerification status: `pending` until the required records verify, then `active`; `disabled` when switched off.
Example: "pending"
health*objectDrift 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-timeWhen `health` last changed; null if it has always been `ok`.
health_grace_ends_at*string · date-timeWhile `health` is `degraded`: when the 72 h grace ends and the domain becomes `failing` unless the records are back. Null otherwise.
verification_token*stringOwnership 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*stringToken in the domain's test address (`test-<token>@<domain>`); a mail sent there proves receiving works.
test_received_at*string · date-timeWhen a test mail to the test address last arrived; null if none yet.
dkim_selector*stringDKIM selector the domain signs with; null until DKIM is set up.
dkim_public_key*stringPublic DKIM key in PEM form (private half stays server-side).
dns_provider*objectThe 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*stringThe 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*objectDNS provider detected from the zone's NS records when the domain was added; `dns_provider` reports the effective one.
verification_status*objectOne 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*integerRecommended records (custom MAIL FROM MX + SPF, DMARC) that are not verified yet. Informational; they never block the domain.
Example: 2
region*stringThe 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*stringDisplay name of `region`.
Example: "Stockholm"
dns_check_results*objectSnapshot 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-timeWhen the DNS records were last checked; null if never.
dns_zone*string · hostnameZone apex found by walking SOA records up from the fqdn; null before the first check.
Example: "example.com"
ses_dkim_status*objectDKIM 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*stringCustom MAIL FROM label (`bounce` → `bounce.<fqdn>`); null when off. On by default for sending domains created since 2026-10.
Example: "bounce"
mail_from_status*objectVerification of the custom MAIL FROM host (its MX record); null when no custom MAIL FROM is configured.
dmarc_managed*booleanfalse when the customer opted out of our `_dmarc` recommendation (PATCH `dmarc_managed`).
Example: true
setup_method*objectHow 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*objectThe DMARC policy that governs this domain, graded on the last check; null before the first check of a sending domain.
verified_at*string · date-timeWhen the domain was first verified; null until then.
created_at*string · date-timeWhen the domain was added.
dns_instructions*arrayDNS records to publish for this domain's intent. Records with `required: true` gate `active`; the rest are informational.
records*arrayThe same records in Resend's `records[]` shape, each with its status.
test_address*stringConvenience 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"
}