Mail API reference

Mail API · Domains

post/v1/workspaces/{workspace_id}/domains/{domain_id}/domain-connect/startAuth

Start one-click DNS setup at the domain's DNS provider (Domain Connect).

Returns a signed Domain Connect URL for the provider that hosts the domain's zone (Cloudflare, GoDaddy, IONOS, Vercel and the others that have onboarded ProductCraft's template). Open it in the browser: the user signs in at their provider and confirms, the provider writes the DKIM key at `productcraft._domainkey.<domain>` and the MAIL FROM records at `bounce.<domain>` (MX to the regional feedback host, SPF merged into any existing SPF there), and then redirects to `GET /v1/domain-connect/callback`, which records `setup_method = domain_connect`, checks the records and returns the user to the domain in the console. With `include_dmarc` and no DMARC policy in place yet, a second confirmation adds `v=DMARC1; p=none;` at `_dmarc.<domain>`. The URL is valid for 10 minutes and works once. ProductCraft never receives a DNS credential. For sending domains whose MAIL FROM label is `bounce` (the default). Not available while ProductCraft has Domain Connect switched off (`domain_connect.available` in `GET .../domains/lookup` says whether it is).

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. A replay returns the same URL, which still works only once.

Request body

include_dmarcboolean

Also add the recommended DMARC record (`v=DMARC1; p=none;` at `_dmarc.<domain>`) as a second confirmation at the provider. Ignored, and not offered, when a DMARC policy already applies to the domain or its organisational domain, when DMARC is not managed here (`dmarc_managed: false`), or when the provider has not onboarded the DMARC template.

Example: true

Response · 200 The signed apply URL to open in the browser.

url*string · uri

The signed Domain Connect apply URL at the DNS provider. Open it in the user's browser (a top-level navigation, not a fetch): the provider asks them to sign in and confirm, writes the records, and sends them back to ProductCraft, which checks the records and returns them to the domain's page in the console. Valid for 10 minutes and usable once.

Example: "https://dash.cloudflare.com/domainconnect/v2/domainTemplates/providers/productcraft.co/services/mail/apply?domain=example.com&host=mail&dkimkey=MIIBIjANBg...&redirect_uri=https%3A%2F%2Fapi.mail.productcraft.co%2Fv1%2Fdomain-connect%2Fcallback&state=3q2-7wVdZ6xYb9mJk1Lr0pQs4tUv8wXy&key=_dck1&sig=Qm9n..."

provider_name*string

The DNS provider the URL goes to, for the button label.

Example: "Cloudflare"

zone*string · hostname

The zone the records are written into.

Example: "example.com"

includes_dmarc*boolean

A second confirmation for the DMARC record follows the first one at the provider.

Example: true

expires_at*string · date-time

When the URL stops working (10 minutes).

Example

Request

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

{
  "include_dmarc": true
}

Response

{
  "url": "https://dash.cloudflare.com/domainconnect/v2/domainTemplates/providers/productcraft.co/services/mail/apply?domain=example.com&host=mail&dkimkey=MIIBIjANBg...&redirect_uri=https%3A%2F%2Fapi.mail.productcraft.co%2Fv1%2Fdomain-connect%2Fcallback&state=3q2-7wVdZ6xYb9mJk1Lr0pQs4tUv8wXy&key=_dck1&sig=Qm9n...",
  "provider_name": "Cloudflare",
  "zone": "example.com",
  "includes_dmarc": true,
  "expires_at": "2026-01-01T00:00:00.000Z"
}