/v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/applyAuthSet up the domain's DNS records in one step with a short-lived Cloudflare or DigitalOcean API token.
Reads the zone through the provider's API and plans every record the domain needs: `create`, `update` (only ever an SPF merge into an existing SPF record, shown with `before`/`after`) or `skip` (already there). `dry_run: true` returns the plan and changes nothing; `dry_run: false` applies exactly that plan, runs a DNS check straight away and records `setup_method = provider_api`. Only names at or under the domain are written, nothing is ever deleted, and Cloudflare records are DNS-only (not proxied). The recommended DMARC record (`p=none`) is included when `include_dmarc` is true (the default) and no DMARC policy applies to the domain yet; an existing policy is never touched. Any blocking conflict refuses the whole apply with 409. The token is used for this request only: it is never stored, logged, queued or returned; revoke it afterwards (`warnings` says so when it could see more than this zone). Applies are limited to one per domain every 10 seconds; dry runs are not limited.
Path parameters
workspace_id*string · uuidId of the workspace.
domain_id*string · uuidId of the domain.
Headers
Idempotency-Key*stringRequired. Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`). A retry with the same key and body (the token is not part of the comparison) replays the first response instead of writing again, for 24 hours.
Request body
provider*enum (2)The DNS provider that hosts the zone.
Example: "cloudflare"
token*string · passwordA short-lived API token for the provider, used for this request only and never stored, logged or returned. Cloudflare: an API token limited to this one zone with the **Zone → DNS → Edit** permission and a short expiry. DigitalOcean: a personal access token with custom scopes `domain:read`, `domain:create`, `domain:update` and a 1-hour expiry. Revoke it once the apply is done.
Example: "dop_v1_EXAMPLE_TOKEN_DO_NOT_USE"
zonestring · hostnameThe zone at the provider (the domain or one of its parents). Defaults to the closest parent zone the token can see.
Example: "example.com"
dry_run*boolean`true`: return the plan and change nothing. `false`: apply the plan and return what was written.
Example: true
include_dmarcbooleanAlso add the recommended DMARC record (`_dmarc.<fqdn>` `v=DMARC1; p=none;`). Only ever planned when no DMARC policy applies at the domain or its organisational domain; an existing policy is never touched, whatever this says.
Example: true
Response · 200 The plan (dry run), or the plan with each record's `result` and the post-apply DNS check.
domain_id*string · uuidThe domain the records were applied to.
fqdn*string · hostnameThe domain name.
Example: "mail.example.com"
provider*objectThe DNS provider the records were written to.
Example: "cloudflare"
zone*string · hostnameThe provider zone the records go into.
Example: "example.com"
dry_run*booleanTrue when this was a dry run: nothing was written.
Example: true
applied*booleanWhether records were written (false on a dry run).
Example: false
plan*arrayEach record and what was (or would be) done with it.
conflicts*arrayEvery conflict in the plan, flattened, with the record it belongs to.
counts*objectcreate*integerRecords that would be (or were) created.
Example: 4
update*integerRecords that would be (or were) updated.
Example: 0
skip*integerRecords already correct and left as they are.
Example: 0
failed*integerWrites that failed (apply only).
Example: 0
warnings*array`token_scope_broader_than_zone`: the token can see more than this zone; it worked, but revoke it now. `dmarc_lookup_failed`: we could not tell whether a DMARC policy applies, so DMARC was left out. `partially_applied`: some writes failed (see each item's `error`); run it again once fixed, finished records are skipped.
Example: ["token_scope_broader_than_zone"]
dmarc_available*booleanNo DMARC policy applies to this domain, so the optional DMARC record can be added (`include_dmarc`).
Example: true
dns_records*objectAfter an apply: the result of the DNS check run right away (new records are usually `propagating`). Null on a dry run.
Example
Request
POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/apply
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"provider": "cloudflare",
"token": "dop_v1_EXAMPLE_TOKEN_DO_NOT_USE",
"zone": "example.com",
"dry_run": true,
"include_dmarc": true
}Response
{
"domain_id": "00000000-0000-0000-0000-000000000000",
"fqdn": "mail.example.com",
"provider": "cloudflare",
"zone": "example.com",
"dry_run": true,
"applied": false,
"plan": [
{
"action": "create",
"purpose": "dkim",
"type": "TXT",
"host": "productcraft._domainkey.mail.example.com",
"name_relative": "productcraft._domainkey.mail",
"value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqh…",
"priority": null,
"ttl": 3600,
"required": true,
"optional": false,
"existing": [
"string"
],
"before": null,
"after": "v=DKIM1; k=rsa; p=MIIBIjANBgkqh…",
"note": null,
"conflicts": [
{
"code": "spf_multiple",
"severity": {},
"message": "string",
"suggested_value": "v=spf1 include:amazonses.com include:_spf.google.com ~all"
}
],
"result": "created",
"error": null
}
],
"conflicts": [
{
"code": "spf_multiple",
"severity": {},
"message": "string",
"suggested_value": "v=spf1 include:amazonses.com include:_spf.google.com ~all",
"purpose": "mail_from_mx",
"host": "bounce.mail.example.com"
}
],
"counts": {
"create": 4,
"update": 0,
"skip": 0,
"failed": 0
},
"warnings": [
"token_scope_broader_than_zone"
],
"dmarc_available": true,
"dns_records": {}
}