Mail API reference

Mail API · Domains

post/v1/workspaces/{workspace_id}/domainsAuth

Register 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 · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Opaque 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_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`.

fqdnstring

Fully qualified domain name. Required unless `name` is sent.

Example: "mail.example.com"

namestring

Resend'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.

capabilitiesobject

Resend's shape of `intent`: `sending` defaults to `enabled`, `receiving` to `disabled`; at least one must be enabled.

regionstring

The 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_pathstring

Resend'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 · 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
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"
}