/v1/workspaces/{workspace_id}/domainsAuthRegister a domain for a workspace
Accepts Resend's create-domain body as well as ours: `name` for `fqdn`, `capabilities` for `intent`, `custom_return_path` for the MAIL FROM label, and `region`, `tls`, `open_tracking`, `click_tracking`, `tracking_subdomain`. Defaults to sending only (`intent: send`), as Resend does. Options we do not offer yet are refused with 422 rather than ignored.
Path parameters
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-KeystringOpaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.
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`.
fqdnstringFully qualified domain name. Required unless `name` is sent.
Example: "mail.example.com"
namestringResend's name for `fqdn`. Send either; both must agree when both are sent.
Example: "mail.example.com"
intentenum (3)How the workspace plans to use this domain; drives which DNS records gate verification. Defaults to `send` (Resend's default: sending on, receiving off). Same as `capabilities`; send one or the other, or both in agreement.
capabilitiesobjectResend's shape of `intent`: `sending` defaults to `enabled`, `receiving` to `disabled`; at least one must be enabled.
regionstringThe AWS region to send from. Every domain of this deployment sends from the same region (`region` on any domain, e.g. `eu-north-1`); any other value is refused with 422 `REGION_NOT_AVAILABLE`.
Example: "eu-north-1"
custom_return_pathstringResend's name for `mail_from_subdomain`: the custom MAIL FROM (return-path) label, `bounce` → `bounce.<fqdn>`. Sending domains only; defaults to `bounce`. Refused with 409 `MAIL_FROM_HOST_IN_USE` when that host already has records that are not ours.
Example: "bounce"
Response · 201
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
POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/domains
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"tls": "opportunistic",
"open_tracking": false,
"click_tracking": false,
"tracking_subdomain": "string",
"fqdn": "mail.example.com",
"name": "mail.example.com",
"intent": "receive",
"capabilities": {},
"region": "eu-north-1",
"custom_return_path": "bounce"
}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"
}