Skip to main content
POST

Overview

Email Validity checks whether an address is safe to send to: is it deliverable, invalid, disposable, a catch-all domain that accepts anything, or otherwise risky. Each result carries a status, a machine-readable reason, and a confidence score, plus enrichment signals: domain trust, breach exposure, gravatar, person-signal, and mail-security records (DKIM/BIMI/DNSSEC). Use it to scrub a list before a send and cut bounces. Validate a single address here (1 credit), or run a whole list through the bulk job pipeline below.

Authentication

Requires an API key in the Authorization header. In the API playground, enter the full value Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx in the Authorization field.

Request

string
required
The email address to validate.
Request bodies are capped at 1 MiB. Anything larger returns 413.

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_dns, no_mail_route, hard_reject, unverifiable, greylist_unresolved, ip_blocked, unreachable, abuse_reported, 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). This field is always present and is "" when no role is found.
string
A suggested correction when available. This field is always present and is "" when empty.
Known issue: did_you_mean is currently not populated; john.smith@gmial.com returns "".
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[] | null
The domain’s resolved mail servers (MX hosts) in preference order. This is null when the domain has no mail route.
object
The domain’s email-authentication posture (non-voting). Not domain age or reputation: grade (A-F), spf, dkim, dkim_selectors, dmarc, dmarc_policy, tls_rpt, bimi, bimi_record, and dnssec. mta_sts is a string: enforce, testing, or none. Raw records are returned in spf_record, dmarc_record, tls_rpt_record, and mta_sts_record.
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, message, catch_all, and greylisted. This is null when the domain has no mail route.
object
Domain registration and DNS detail: registrar, created_at, expires_at, age_days, nameservers, dnssec, and a.
object[] | null
An array of per-MX infrastructure and TLS detail objects, one entry per resolved mail server. This is null when the domain has no mail route.
object
Identity footprint signals. breaches is an object with count, exposed_data, and services, where each service contains name, date, and data_types. The object can also contain gravatar_url and registered_services, whose entries contain name, category, and url.
boolean
true when the mailbox provider itself answered the probe. false means the verdict rests on DNS and heuristics alone.
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 during the 6-month free-repeat window. 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.
boolean
Whether the deliverability verdict was served from Encrata’s cache. This field is always present as true or false. It is a performance signal, not a billing signal. A cached result can still cost 1 credit.

Errors

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

Notes

  • Each validation costs 1 credit. Repeat checks of the same address during the 6-month free-repeat window are free (credits: 0).
  • cached and credits are independent. cached reports a cache hit on the deliverability verdict; credits: 0 is the billing signal.
  • 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.

Bulk jobs

To validate a whole list, submit it as a bulk job instead of looping this endpoint. One entrypoint handles every lookup - set type=validity - and a webhook delivers the finished file when it’s done.
  • Up to 1,000,000 emails per job, charged 1 credit per email.
  • download_link=true returns a download_url in the bulk.completed webhook; fetch it with your API key.
  • Export filters: all, valid, invalid, catch-all, risky.
See the Bulk Operations guide for the webhook payload and download options.