Skip to main content
POST
Email Validity

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.

Request

string
required
The email address to validate. This is the only accepted key.
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).
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
The domain’s email-authentication posture (non-voting). Not domain age or reputation: grade (A-F), spf, dkim, dkim_selectors, dmarc, dmarc_policy, mta_sts, tls_rpt, bimi, bimi_record, and dnssec, 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[]
An array of per-MX infrastructure and TLS detail objects, one entry per resolved mail server.
object
Identity footprint signals (breaches, gravatar, registered services) when available.
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 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.
boolean
true when the deliverability verdict was served from Encrata’s cache (a performance optimization, not a billing signal). Omitted when false. A cached result can still cost 1 credit - only a free repeat (credits: 0) is free.

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 within the billing 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, status checks, and download options.