API

Base URL: /api/v1. Authenticate with Authorization: Bearer YOUR_KEY (or x-api-key).

Verify one address

curl -H "Authorization: Bearer $KEY" "https://HOST/api/v1/verify?email=jane@gmial.com"

curl -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"email":"jane@gmial.com"}' https://HOST/api/v1/verify

Verify a batch (max 100)

curl -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"emails":["a@example.com","info@acme.io"]}' https://HOST/api/v1/verify

Batch calls return instantly with syntax, DNS and disposable checks. Mailbox-level checks run only if a slot is free; for full mailbox results on bigger lists, use a list job.

Check a whole list (up to 50,000)

# Create (charges 1 credit per address, returns 202)
curl -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"name":"leads.csv","emails":["a@example.com","b@example.com"]}' https://HOST/api/v1/lists

# Progress: processed, percent, counts, etaSeconds
curl -H "Authorization: Bearer $KEY" https://HOST/api/v1/lists/lst_123

# Results (JSON, or ?format=csv)
curl -H "Authorization: Bearer $KEY" "https://HOST/api/v1/lists/lst_123/results?format=csv"

Lists run in the background. Slow or greylisting mail servers are rechecked automatically (after 5, 20 and 60 minutes). We email the account owner when the list finishes; send "notify": false to opt out.

Response

{
  "input": "jane@gmial.com",
  "status": "undeliverable",        // deliverable | risky | undeliverable | unknown
  "reason": "possible_typo",        // machine-readable reason code
  "score": 0,                       // 0-100
  "suggestion": "jane@gmail.com",
  "checks": { "syntax": true, "mxFound": false, "disposable": false, "role": false,
              "freeProvider": false, "catchAll": "unknown", "mailbox": "not_checked" }
}

Reason codes

invalid_syntax, empty_input, too_long, invalid_domain, null_mx, no_mx_records, no_mx_a_fallback, dns_error, dns_timeout, disposable, role_account, possible_typo, catch_all, mailbox_not_found, mailbox_full, mailbox_ok, mailbox_not_checked, smtp_error, provider_blocked

Limits