Skip to main content
POST
/
api
/
email
/
domains
/
{id}
/
verify
Trigger or poll domain verification
curl --request POST \
  --url https://app.puffle.ai/api/email/domains/{id}/verify \
  --header 'Authorization: Bearer <token>'
{
  "domain": {
    "id": "dddd1111-1111-1111-1111-111111111111",
    "user_id": "11111111-1111-1111-1111-111111111111",
    "domain": "acme.com",
    "agentmail_domain_id": "acme.com",
    "status": "verified",
    "dns_records": [
      {
        "type": "CNAME",
        "name": "agm._domainkey.acme.com",
        "value": "agm._domainkey.agentmail.to"
      }
    ],
    "verified_at": "2026-04-22T10:12:00Z",
    "created_at": "2026-04-22T10:00:00Z",
    "updated_at": "2026-04-22T10:12:00Z"
  }
}

​
Overview

POST /api/email/domains/{id}/verify (verifyEmailDomain) has two modes:
  • Trigger mode (default). Pre-marks the domain verifying, calls AgentMail’s verify() to kick off an async DNS check, reads the live status back, and persists it along with the latest expected DNS records. If the post-call status is still verifying, the domain-verify-poller background task is scheduled (idempotency keyed per domain) so the DB converges even if the user closes the page.
  • Poll mode (?poll=true). Skip the verify trigger and just read the live AgentMail status. Use this on every polling tick — re-triggering verification on each tick restarts AgentMail’s async DNS checker and can cause visible flicker between verifying, failed, and back to verifying.

​
AI agent notes

Cloudflare DNS dependency. Verification only succeeds after AgentMail’s DKIM/SPF/DMARC records resolve on the domain. Creating the domain via createEmailDomain auto-syncs these records to Cloudflare when the caller owns the zone and CF_API_TOKEN is configured; otherwise the user must add the records manually at their DNS provider before calling this endpoint.Polling recipe. Use verifyEmailDomain (no flag) once to start the verification, then hit it with ?poll=true every 30–60 seconds until status is verified or failed. The background domain-verify-poller will keep re-checking on exponential backoff (10m, 20m, 40m, 80m, 160m, 320m) for up to 12 hours even without client-side polling.Idempotency is enforced. Repeated trigger calls collapse into the original poller chain via a per-domain idempotency key.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string<uuid>
required

Email domain (email_domains.id) UUID.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Query Parameters

​
poll
enum<string>

If true, skip triggering AgentMail's verification check and only read the current live status. Use this on every polling tick so AgentMail's async DNS checker isn't restarted repeatedly (which can cause flicker verifying → failed → verifying).

Available options:
true,
false

Response

Domain verification state after this call. status is verified on success, verifying if DNS is still propagating, or failed if AgentMail rejected the records. dns_records is always refreshed with the live expected values.

​
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.