Email Validity
curl --request POST \
--url https://developer.encrata.com/api/lookup/email/validity \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "<string>"
}
'import requests
url = "https://developer.encrata.com/api/lookup/email/validity"
payload = { "email": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({email: '<string>'})
};
fetch('https://developer.encrata.com/api/lookup/email/validity', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://developer.encrata.com/api/lookup/email/validity",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://developer.encrata.com/api/lookup/email/validity"
payload := strings.NewReader("{\n \"email\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://developer.encrata.com/api/lookup/email/validity")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://developer.encrata.com/api/lookup/email/validity")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"email": "satya@microsoft.com",
"status": "valid",
"reason": "deliverable",
"disposable": false,
"confidence": "high",
"role": false,
"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
}
{
"email": "user@tempmail.com",
"status": "invalid",
"reason": "disposable",
"disposable": true,
"provider_answered": false,
"message": "Undeliverable, will bounce or is not worth sending.",
"validity": "invalid",
"credits": 1
}
{
"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
}
{ "error": "bad email", "code": "bad_email" }
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
Email Validity
curl --request POST \
--url https://developer.encrata.com/api/lookup/email/validity \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "<string>"
}
'import requests
url = "https://developer.encrata.com/api/lookup/email/validity"
payload = { "email": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({email: '<string>'})
};
fetch('https://developer.encrata.com/api/lookup/email/validity', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://developer.encrata.com/api/lookup/email/validity",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://developer.encrata.com/api/lookup/email/validity"
payload := strings.NewReader("{\n \"email\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://developer.encrata.com/api/lookup/email/validity")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://developer.encrata.com/api/lookup/email/validity")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"email": "satya@microsoft.com",
"status": "valid",
"reason": "deliverable",
"disposable": false,
"confidence": "high",
"role": false,
"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
}
{
"email": "user@tempmail.com",
"status": "invalid",
"reason": "disposable",
"disposable": true,
"provider_answered": false,
"message": "Undeliverable, will bounce or is not worth sending.",
"validity": "invalid",
"credits": 1
}
{
"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
}
{ "error": "bad email", "code": "bad_email" }
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.
Authorization: Bearer YOUR_API_KEY
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
curl -X POST "https://developer.encrata.com/api/lookup/email/validity" \
-H "Authorization: Bearer YOUR_API_KEY" \
-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 YOUR_API_KEY"},
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 YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ email: "test@example.com" }),
});
const data = await resp.json();
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.
| Status | Message | Cause |
|---|---|---|
400 | bad body | Malformed JSON |
400 | email required | No email supplied |
400 | bad email | Address fails RFC syntax parsing |
401 | bad key / unauthorized | Missing or invalid API key |
402 | insufficient credits | No credits remaining and not a free repeat |
405 | POST only | Wrong HTTP method |
413 | body too large | Request body exceeds 1 MiB |
500 | internal error | Unexpected server failure |
502 | validation unavailable | No validity status could be produced |
{
"email": "satya@microsoft.com",
"status": "valid",
"reason": "deliverable",
"disposable": false,
"confidence": "high",
"role": false,
"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
}
{
"email": "user@tempmail.com",
"status": "invalid",
"reason": "disposable",
"disposable": true,
"provider_answered": false,
"message": "Undeliverable, will bounce or is not worth sending.",
"validity": "invalid",
"credits": 1
}
{
"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
}
{ "error": "bad email", "code": "bad_email" }
Notes
- Each validation costs 1 credit. Repeat checks of the same address within
the billing 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 YOUR_API_KEY" \
-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?