Skip to main content
POST
/
api
/
email
/
domains
/
{id}
/
verify
Verify Domain
curl --request POST \
  --url https://app.puffle.ai/api/email/domains/{id}/verify \
  --header 'Authorization: Bearer <token>'
{
  "domain": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "domain": "<string>"
  }
}
CLI: 
puffle email domain verify --id <id>
puffle email domain verify --id <id> --poll <poll>

​
Overview

POST /api/email/domains/{id}/verify (verifyEmailDomain) has two modes:
  • Trigger mode (default). Pre-marks the domain verifying, kicks 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 status. Use this on every polling tick — re-triggering verification on each tick restarts the async DNS checker and can cause visible flicker between verifying, failed, and back to verifying.

​
AI agent notes

DNS dependency. Verification only succeeds after the required DKIM/SPF/DMARC records resolve on the domain. Creating the domain via createEmailDomain auto-syncs these records when Puffle can manage the zone; 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
required

Email domain (email_domains.id) UUID.

Minimum string length: 1

Query Parameters

​
poll
enum<string>

If true, skip triggering a verification check and only read the current live status. Use this on every polling tick so the async DNS checker is not 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 the verification service rejected the records. dns_records is always refreshed with the live expected values.

​
domain
object
required

Verified email domain row.