Skip to main content
POST
Email Validity

Authentication

Requires an API key in the Authorization header.

Request

string
required
The email address to validate. The legacy key e is still accepted.

Example request

Response

string
The email address that was validated (normalized to lowercase).
string
The public verdict - one of valid, invalid, catch-all, or risky.
string
Machine-readable explanation, e.g. deliverable, syntax, disposable, null_mx, no_mail_route, hard_reject, mailbox_full, unverifiable, greylist_unresolved, ip_blocked, unreachable, catch_all, or catchall_corroborated.
boolean
true when the domain is a known disposable/temporary provider.
string
Provider-calibrated confidence - high, medium, or low.
boolean
true for role/shared mailboxes (e.g. support@). A flag only - role accounts still deliver.
string
The matched role local-part when role is true (e.g. support).
string
A suggested correction when a likely typo is detected (e.g. gmial.com).
string
The domain part of the address.
string
Mailbox provider classification - google, microsoft, yahoo, or other.
boolean
true for free consumer mailbox providers (Gmail, Outlook, etc.).
string
The canonicalized address (e.g. Gmail dot/plus normalization).
string[]
The domain’s resolved mail servers (MX hosts) in preference order.
object
Outbound-security posture (non-voting): grade (A–F), spf, dmarc, dmarc_policy, mta_sts, tls_rpt, plus the raw DNS records when present.
object
OSINT corroboration: count of independent hits and the sources that hit (hibp, gravatar, github, gitlab, pgp). A positive signal on a catch-all domain promotes the status to valid.
object
Technical probe detail when available: mx_host, code, message, catch_all, and greylisted.
object
Domain registration/DNS detail (registrar, creation date, age) when available.
object
Per-MX infrastructure and TLS detail when available.
object
Identity footprint signals (breaches, gravatar, registered services) when available.
string
ISO 8601 timestamp of when the check ran.
string
Human-readable explanation of the verdict.
string
deprecated
Legacy mirror of status, retained for backward compatibility.
number
Credits charged for this request. 1 on a fresh charge, or 0 when you were already charged for this address within the billing window (a free repeat). This is per-customer and independent of cached - a cached result is still charged 1 if it’s your first request for that address in the window.
number
Duplicate of credits, included for usage tracking.
boolean
true when the report was served from Encrata’s shared enrichment cache (a performance optimization, not a billing signal). A cached result can still cost 1 credit - only a free repeat (credits: 0) is free.
boolean
Duplicate of cached, included for usage tracking.

Errors

Errors return a JSON body of the form {"error": "<message>"} with the matching HTTP status code.

Notes

  • Each validation costs 1 credit. Repeat checks of the same address within the billing window are free (credits: 0, cached: true).
  • Disposable detection runs first; disposable domains are flagged (disposable: true) and marked invalid.
  • A corroborated catch-all can be promoted from catch-all to valid via person_signal.
  • Rate limited to 60 requests per minute.

Bulk (async jobs, up to 1,000,000)

For validating a whole list, use the async job pipeline instead of calling the single endpoint in a loop. Submit the addresses (raw JSON list or an uploaded CSV/TXT/XLSX file), then poll the job until it completes. Limit: 1,000,000 emails per job (50 MB body max). Charges 1 credit per email.
  • POST /api/agent/validity-jobs: body { "emails": ["a@example.com", ...], "file_name": "list.csv" }, or a multipart/form-data upload with a file field. Returns 202 with a job { id, status, total_emails, ... }.
  • GET /api/agent/validity-jobs: list your jobs (page, page_size).
  • GET /api/agent/validity-jobs?id=<id>: poll live status + counts (processed_count, valid_count, invalid_count, catch_all_count, risky_count, credits_used).
  • GET /api/agent/validity-jobs/results?id=<id>&page=&page_size=&status=: paginated result rows ({ email, status, reason, provider }). Optional status filter (valid, invalid, catch-all, risky).
  • GET /api/agent/validity-jobs/download?id=<id>: stream the full results as CSV.
  • POST /api/agent/validity-jobs/cancel?id=<id>: cancel an in-flight job.
  • POST /api/agent/validity-jobs/retry?id=<id>: re-queue failed chunks.
  • DELETE /api/agent/validity-jobs?id=<id>: delete a job (or ?all=1 for every job).
Jobs run in resumable chunks in the background, so a large list completes without a long-held HTTP request.
202