Email Lookup
Email Validity
Check if an email address is deliverable, invalid, or disposable. 1 credit, with free repeats for 6 months.
POST
Email Validity
Authentication
Requires an API key in theAuthorization 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 markedinvalid. - A corroborated catch-all can be promoted from
catch-alltovalidviaperson_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 amultipart/form-dataupload with afilefield. Returns202with 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 }). Optionalstatusfilter (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=1for every job).
202
Email Validity