Skip to content

Verify an email

Submit a job

POST /api/verify reserves the cost, queues the job, and returns 202 Accepted with a job_uuid. The response sets a Location header with the poll URL and a Retry-After hint while the job runs.

curl -X POST https://api.pricklymails.com/api/verify \
  -H "Authorization: Bearer pm_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234" \
  -d '{ "email": "someone@example.com" }'

Pass an optional Idempotency-Key header to make retries safe: the same key replays the original job instead of billing a new one (the response then carries Idempotent-Replayed: true).

Poll the result

GET /api/verify/{uuid} returns the job and its per-check results, scoped to your account. It keeps setting Retry-After until the job reaches a terminal status (completed, failed, or canceled).

Once completed, the result carries the verdict, the score, the action recommendation, and the per-check outcome:

{
    "status": "completed",
    "verdict": "risky",
    "score": 76,
    "recommendation": "send",
    "reason": "accept_all_provider",
    "checks": {
        "syntax": { "status": "valid" },
        "mx": { "status": "valid" },
        "smtp": { "status": "skipped" },
        "disposable": { "status": "valid" },
        "role": { "status": "valid" },
        "catchall": { "status": "skipped" }
    }
}

recommendation turns the honest verdict into an action for list cleaning: remove, send, or review (see Batches).

The checks

Each address runs through the checks your key enables:

  • syntax: RFC 5322 format.
  • mx: the domain has usable mail servers (a missing, null, parked, or inactive mail exchanger fails here).
  • smtp: the mailbox accepts mail (deliverability probe).
  • disposable: a known throwaway provider, matched on the address domain or its mail exchanger.
  • role: a role address such as info@ or support@.
  • free: a free webmail provider.
  • catchall: the domain accepts any address.

Typo detection always runs, regardless of the checks your key enables: when a likely misspelling is found, the response echoes a suggested correction.

Verdict and score

The result carries a deliverability verdict (valid, invalid, risky, unknown) and a 0-100 quality score. When a typo is detected, the response echoes a suggestion (for example someone@gmial.com suggests someone@gmail.com).