Mail API reference

Mail API · Domains

post/v1/workspaces/{workspace_id}/domains/{domain_id}/dns-records/applyAuth

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

Id of the workspace.

domain_id*string · uuid

Id of the domain.

Headers

Idempotency-Key*string

Required. 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 · password

A 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 · hostname

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

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

The domain the records were applied to.

fqdn*string · hostname

The domain name.

Example: "mail.example.com"

provider*object

The DNS provider the records were written to.

Example: "cloudflare"

zone*string · hostname

The provider zone the records go into.

Example: "example.com"

dry_run*boolean

True when this was a dry run: nothing was written.

Example: true

applied*boolean

Whether records were written (false on a dry run).

Example: false

plan*array

Each record and what was (or would be) done with it.

conflicts*array

Every conflict in the plan, flattened, with the record it belongs to.

counts*object
create*integer

Records that would be (or were) created.

Example: 4

update*integer

Records that would be (or were) updated.

Example: 0

skip*integer

Records already correct and left as they are.

Example: 0

failed*integer

Writes 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*boolean

No DMARC policy applies to this domain, so the optional DMARC record can be added (`include_dmarc`).

Example: true

dns_records*object

After 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": {}
}