Email verification in one POST request.

Send an email address, get back a clear verdict, a 0–100 score, and every check we ran. Bearer-token auth, JSON in and out, no SDK required.

Authentication

Every request needs an Authorization: Bearer <token> header. Generate a token from API keys in your dashboard. Tokens are scoped to a single account.

Verify an email

POST /api/v1/verify with a JSON body containing an email. One verification spends one credit, whatever the verdict.

curl -X POST https://clearmx.app/api/v1/verify \
  -H "Authorization: Bearer cmx_live_your_token" \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@getpalladio.com"}'

{
  "email": "ana@getpalladio.com",
  "normalized_email": "ana@getpalladio.com",
  "result": "deliverable",
  "score": 100,
  "reason": "mailbox_exists",
  "checks": {
    "syntax": true,
    "domain": "getpalladio.com",
    "mx": true,
    "implicit_mx": false,
    "disposable": false,
    "role": false,
    "no_reply": false,
    "free": false,
    "accept_all": false,
    "tag": null,
    "irregular_characters": false,
    "provider": "google",
    "secure_gateway": null,
    "smtp": { "status": "ok", "code": 250, "accept_all": false },
    "smtp_skipped": null,
    "typo_suggestion": null
  },
  "credits_used": 1
}

Reading the result

Branch on result, not on score. result is one of four values and is always authoritative. score (0–100) is a confidence number for ranking addresses within a verdict — an unknown is deliberately scored mid-range, so a score threshold on its own would misfile it. reason gives the single deciding signal and checks gives all of them.

For completeness: once a verdict is decidable, the score thresholds are 80 for deliverable and 50 for risky. But unknown is assigned before those thresholds are ever reached, which is exactly why a score comparison is not a substitute for reading result.

deliverable additionally requires SMTP mailbox confirmation on a non-catch-all domain — a valid MX record alone caps the score at 75 and returns risky / mailbox_unconfirmed. (Breaking change note: the former valid_mx reason is retired; confirmed mailboxes return mailbox_exists.)

The checks object

Every check we ran, always present. Disposable, role and catch-all are risk signals: they deduct from the score and can never make an address deliverable.

Errors

A syntactically invalid email is a normal result (200 + undeliverable), not an error. Errors are reserved for request problems, and every one is a JSON body with an error key. None of the responses below spends a credit.

Volume and limits

There is no published per-key request limit today; if we introduce one we will document it here first. Two things do throttle in practice: live mailbox probes are rate-limited per destination domain (so hammering one domain returns smtp_skipped: "rate_limited" rather than a verdict), and large one-off lists are far better served by a CSV bulk import in the dashboard than by thousands of concurrent single calls. Bulk verification is dashboard-only for now — there is no bulk API endpoint yet.

API FAQ

See also: Email verification API guide · Bulk verification