curl -X POST "https://developer.encrata.com/api/lookup/email/validity" \
-H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com"}'
import requests
resp = requests.post(
"https://developer.encrata.com/api/lookup/email/validity",
headers={"Authorization": "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={"email": "test@example.com"},
)
print(resp.json())
const resp = await fetch("https://developer.encrata.com/api/lookup/email/validity", {
method: "POST",
headers: {
Authorization: "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({ email: "test@example.com" }),
});
const data = await resp.json();
{
"email": "satya@microsoft.com",
"status": "valid",
"reason": "deliverable",
"disposable": false,
"confidence": "high",
"role": false,
"role_name": "",
"did_you_mean": "",
"domain": "microsoft.com",
"provider": "microsoft",
"free_provider": false,
"mx": ["microsoft-com.mail.protection.outlook.com"],
"domain_trust": { "grade": "A", "spf": true, "dkim": true, "dmarc": true },
"person_signal": { "count": 1, "sources": ["hibp"] },
"provider_answered": true,
"message": "Mailbox exists and accepts mail, safe to send.",
"validity": "valid",
"credits": 1,
"cached": false
}
{
"email": "user@tempmail.com",
"status": "invalid",
"reason": "disposable",
"disposable": true,
"role_name": "",
"did_you_mean": "",
"provider_answered": false,
"message": "Undeliverable, will bounce or is not worth sending.",
"validity": "invalid",
"credits": 1,
"cached": false
}
{
"email": "satya@microsoft.com",
"status": "valid",
"reason": "deliverable",
"provider_answered": true,
"message": "Mailbox exists and accepts mail, safe to send.",
"validity": "valid",
"credits": 0,
"cached": true
}
{ "code": "bad_request", "error": "Invalid email address" }
Email
Email Validity
Check if an email address is deliverable, invalid, or disposable. 1 credit, with free repeats for 6 months.
POST
/
api
/
lookup
/
email
/
validity
curl -X POST "https://developer.encrata.com/api/lookup/email/validity" \
-H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com"}'
import requests
resp = requests.post(
"https://developer.encrata.com/api/lookup/email/validity",
headers={"Authorization": "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={"email": "test@example.com"},
)
print(resp.json())
const resp = await fetch("https://developer.encrata.com/api/lookup/email/validity", {
method: "POST",
headers: {
Authorization: "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({ email: "test@example.com" }),
});
const data = await resp.json();
{
"email": "satya@microsoft.com",
"status": "valid",
"reason": "deliverable",
"disposable": false,
"confidence": "high",
"role": false,
"role_name": "",
"did_you_mean": "",
"domain": "microsoft.com",
"provider": "microsoft",
"free_provider": false,
"mx": ["microsoft-com.mail.protection.outlook.com"],
"domain_trust": { "grade": "A", "spf": true, "dkim": true, "dmarc": true },
"person_signal": { "count": 1, "sources": ["hibp"] },
"provider_answered": true,
"message": "Mailbox exists and accepts mail, safe to send.",
"validity": "valid",
"credits": 1,
"cached": false
}
{
"email": "user@tempmail.com",
"status": "invalid",
"reason": "disposable",
"disposable": true,
"role_name": "",
"did_you_mean": "",
"provider_answered": false,
"message": "Undeliverable, will bounce or is not worth sending.",
"validity": "invalid",
"credits": 1,
"cached": false
}
{
"email": "satya@microsoft.com",
"status": "valid",
"reason": "deliverable",
"provider_answered": true,
"message": "Mailbox exists and accepts mail, safe to send.",
"validity": "valid",
"credits": 0,
"cached": true
}
{ "code": "bad_request", "error": "Invalid email address" }
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 theAuthorization header.
In the API playground, enter the full value Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx in the
Authorization field.
Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Request
Request bodies are capped at 1 MiB. Anything larger returns
413.Example request
curl -X POST "https://developer.encrata.com/api/lookup/email/validity" \
-H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com"}'
import requests
resp = requests.post(
"https://developer.encrata.com/api/lookup/email/validity",
headers={"Authorization": "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={"email": "test@example.com"},
)
print(resp.json())
const resp = await fetch("https://developer.encrata.com/api/lookup/email/validity", {
method: "POST",
headers: {
Authorization: "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({ email: "test@example.com" }),
});
const data = await resp.json();
Response
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.The matched role local-part when
role is true (e.g. support). This field
is always present and is "" when no role is found.Known issue:
did_you_mean is currently not populated;
john.smith@gmial.com returns "".The domain’s resolved mail servers (MX hosts) in preference order. This is
null when the domain has no mail route.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.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.Technical probe detail when available:
mx_host, message, catch_all, and
greylisted. This is null when the domain has no mail route.Domain registration and DNS detail:
registrar, created_at, expires_at,
age_days, nameservers, dnssec, and a.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.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.true when the mailbox provider itself answered the probe. false means the
verdict rests on DNS and heuristics alone.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.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.
| Status | code | error | Cause |
|---|---|---|---|
| 400 | bad_request | Invalid request body | Malformed JSON |
| 400 | bad_request | Invalid email address | email missing or not a valid address |
| 402 | insufficient_credits | (not verified) | No credits and not a free repeat |
| 405 | method_not_allowed | Only POST method is allowed | Wrong method |
| 413 | payload_too_large | Request body too large. | Body over 1 MiB |
curl -X POST "https://developer.encrata.com/api/lookup/email/validity" \
-H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"email": "test@example.com"}'
import requests
resp = requests.post(
"https://developer.encrata.com/api/lookup/email/validity",
headers={"Authorization": "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
json={"email": "test@example.com"},
)
print(resp.json())
const resp = await fetch("https://developer.encrata.com/api/lookup/email/validity", {
method: "POST",
headers: {
Authorization: "Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({ email: "test@example.com" }),
});
const data = await resp.json();
{
"email": "satya@microsoft.com",
"status": "valid",
"reason": "deliverable",
"disposable": false,
"confidence": "high",
"role": false,
"role_name": "",
"did_you_mean": "",
"domain": "microsoft.com",
"provider": "microsoft",
"free_provider": false,
"mx": ["microsoft-com.mail.protection.outlook.com"],
"domain_trust": { "grade": "A", "spf": true, "dkim": true, "dmarc": true },
"person_signal": { "count": 1, "sources": ["hibp"] },
"provider_answered": true,
"message": "Mailbox exists and accepts mail, safe to send.",
"validity": "valid",
"credits": 1,
"cached": false
}
{
"email": "user@tempmail.com",
"status": "invalid",
"reason": "disposable",
"disposable": true,
"role_name": "",
"did_you_mean": "",
"provider_answered": false,
"message": "Undeliverable, will bounce or is not worth sending.",
"validity": "invalid",
"credits": 1,
"cached": false
}
{
"email": "satya@microsoft.com",
"status": "valid",
"reason": "deliverable",
"provider_answered": true,
"message": "Mailbox exists and accepts mail, safe to send.",
"validity": "valid",
"credits": 0,
"cached": true
}
{ "code": "bad_request", "error": "Invalid email address" }
Notes
- Each validation costs 1 credit. Repeat checks of the same address during
the 6-month free-repeat window are free (
credits: 0). cachedandcreditsare independent.cachedreports a cache hit on the deliverability verdict;credits: 0is the billing signal.- Disposable detection runs first; disposable domains are flagged (
disposable: true) and markedinvalid. - A corroborated catch-all can be promoted from
catch-alltovalidviaperson_signal.
Bulk jobs
To validate a whole list, submit it as a bulk job instead of looping this endpoint. One entrypoint handles every lookup - settype=validity - and a
webhook delivers the finished file when it’s done.
curl -X POST "https://developer.encrata.com/api/jobs/bulk" \
-H "Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-F "type=validity" \
-F "download_link=true" \
-F "file=@list.csv"
- Up to 1,000,000 emails per job, charged 1 credit per email.
download_link=truereturns adownload_urlin thebulk.completedwebhook; fetch it with your API key.- Export filters:
all,valid,invalid,catch-all,risky.
Was this page helpful?