Set up a domain

Onboard one of a project's domains in Cloudflare Email Sending, with its DNS records and delivery events.

POST/v1/admin/projects/{slug}/domains/{domain}/setupAdmin key

Does in one call what Deploy steps 3 and 4 do by hand. It is what the dashboard's Set up in Cloudflare menu item and Add domain dialog call. It only works with the admin key: project API keys get 403 admin_only, because it changes DNS with the mailer's own Cloudflare token.

The mailer needs a CF_API_TOKEN secret with Zone Read, Email Sending Edit, DNS Edit and Queues Edit, and the CF_ACCOUNT_ID var. See Configuration.

It runs these steps in order and reports each one:

sending domain: adds the domain to Email Sending on its Cloudflare zone, unless it is already there.
dns: one step per record Cloudflare lists for the domain (SPF, DKIM, return path). Adds each record that is missing.
dmarc: only when Cloudflare's list has no DMARC record. If neither _dmarc.<domain> nor _dmarc.<zone> has one, adds v=DMARC1; p=none at _dmarc.<domain>.
delivery events: subscribes the domain's delivery events to the flaresend-events queue, unless a subscription for this zone and domain already exists.

It never changes or deletes a DNS record that is already there. When a different record is in the way (a CNAME at the same name, or another SPF, DKIM or DMARC TXT record), the step is reported as conflict for you to fix by hand. Records are added unproxied. It is safe to run again: finished steps report exists.

Path parameters

slugstringpathrequired

The project slug.

domainstringpathrequired

One of the project's allowedDomains. Add it to the project first with Update a project.

Response

Status 200. A step that fails does not fail the request; check each step's status.

domainstring

The domain, lowercased.

zonestring

The Cloudflare zone that holds it, for example acme.com for mail.acme.com.

stepsStep[]

What happened, in order.

Show step properties

stepstring

sending domain, dns, dmarc or delivery events.

status'created' | 'exists' | 'conflict' | 'skipped' | 'failed'

created: done now. exists: already in place. conflict: another record is in the way. skipped: delivery events only, when CF_ACCOUNT_ID is not set. failed: the Cloudflare API call failed.

detailstring

A sentence explaining the status, or the Cloudflare error.

record{ type, name, content }

For DNS steps, the record that was wanted.

recordobject

The domain's fresh verification status after setup: domain, verification (onboarded, pending, missing or unknown), details and checkedAt. The same as an entry from List domains, without defaultFrom.

Errors

Status	Code	When
403	`admin_only`	Called at `/v1/domains/:domain/setup` with a project API key.
404	`project_not_found`	No project has this slug.
404	`domain_not_in_project`	The domain is not in the project's `allowedDomains`.
422	`cf_token_missing`	The mailer has no `CF_API_TOKEN` secret.
422	`zone_not_found`	The token can't see a Cloudflare zone for the domain. The domain's DNS must be on Cloudflare in the mailer's account.
422	`cloudflare_api_error`	Finding the zone or creating the sending domain failed. `message` has Cloudflare's error.

Request

const res = await fetch(
  'https://mailer.example.com/v1/admin/projects/acme/domains/acme.com/setup',
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.FLARESEND_ADMIN_KEY}` },
  },
);
const { steps, record } = await res.json();

Response

{
  "domain": "acme.com",
  "zone": "acme.com",
  "steps": [
    { "step": "sending domain", "status": "created", "detail": "added acme.com to Email Sending" },
    {
      "step": "dns",
      "status": "created",
      "detail": "added to DNS",
      "record": { "type": "TXT", "name": "cf-bounce.acme.com", "content": "v=spf1 include:_spf.mx.cloudflare.net ~all" }
    },
    {
      "step": "dns",
      "status": "conflict",
      "detail": "a different TXT record is already at this name (v=spf1 include:_spf.google.com ~all); fix it by hand",
      "record": { "type": "TXT", "name": "acme.com", "content": "v=spf1 include:_spf.mx.cloudflare.net ~all" }
    },
    {
      "step": "dmarc",
      "status": "created",
      "detail": "added to DNS",
      "record": { "type": "TXT", "name": "_dmarc.acme.com", "content": "v=DMARC1; p=none" }
    },
    {
      "step": "delivery events",
      "status": "created",
      "detail": "subscription \"flaresend-acme-com\" sends delivery events to flaresend-events"
    }
  ],
  "record": {
    "domain": "acme.com",
    "verification": "pending",
    "details": { "zone": "acme.com", "name": "acme.com", "enabled": false, "dkimSelector": null, "returnPathDomain": null },
    "checkedAt": "2026-09-26T10:10:00.000Z"
  }
}

Path parametersCopy Anchor Link

ResponseCopy Anchor Link

ErrorsCopy Anchor Link

Path parameters

Response

Errors