Skip to main content
POST
/
api
/
email
/
domains
Create an email sending domain
curl --request POST \
  --url https://app.puffle.ai/api/email/domains \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain": "<string>"
}
'
{
  "domain": {
    "id": "dddd1111-1111-1111-1111-111111111111",
    "user_id": "11111111-1111-1111-1111-111111111111",
    "domain": "acme.com",
    "agentmail_domain_id": "acme.com",
    "status": "verifying",
    "dns_records": [
      {
        "type": "CNAME",
        "name": "agm._domainkey.acme.com",
        "value": "agm._domainkey.agentmail.to"
      }
    ],
    "verified_at": null,
    "created_at": "2026-04-22T10:00:00Z",
    "updated_at": "2026-04-22T10:00:00Z"
  }
}

​
Overview

Registers a new custom domain in AgentMail, auto-syncs the DKIM/SPF/DMARC records to Cloudflare when the caller’s zone is managed by CF_API_TOKEN, triggers verification, and schedules the domain-verify-poller background task to converge status as DNS propagates. Sending domains unlock creating email inboxes under that domain via createEmailAccount. Until a domain is verified, no inboxes can be provisioned on it.
This operation shares the URL path /api/email/domains with the list verb. See List sending domains to enumerate domains already registered.

​
AI agent notes

Verification is a multi-step DNS dance. Creating a domain does not mean it is usable. The flow is:
  1. createEmailDomain — AgentMail issues DKIM/SPF/DMARC records; if Cloudflare is the authoritative DNS provider and CF_API_TOKEN is configured for the caller’s zone, records are written automatically and verification is triggered.
  2. If Cloudflare sync was skipped (zone not managed), status stays pending — the user must add the DNS records at their provider manually, then call verifyEmailDomain (no ?poll=true) once.
  3. The domain-verify-poller background task re-checks AgentMail on an exponential-backoff schedule (10m, 20m, 40m, 80m, 160m, 320m) for up to 12 hours.
First-verifier-wins on ownership conflicts. If another user’s unverified claim exists on the same domain, creating here will drop the stale claim. If someone else has already verified the domain, you get a 409.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Only domain is accepted. The handler creates the domain in AgentMail, auto-syncs the DKIM/SPF/DMARC records to Cloudflare when the zone is managed by the caller's Cloudflare account, triggers verification if DNS was synced, and schedules the domain-verify-poller background task to converge status.

​
domain
string
required

Apex or subdomain to register. Lowercased server-side. Must match ^[a-z0-9](…)+\.[a-z]{2,}$.

Response

Domain created. status is verified if DNS was already in place, verifying if the poller has been scheduled, or pending if Cloudflare sync failed and the user must add records manually.

​
domain
object
required

A custom sending domain. Domains are created in AgentMail, optionally auto-synced to Cloudflare, and then polled (via the domain-verify-poller background task) until AgentMail confirms DNS propagation.