EmailScore
Production Edge Gatewayhttps://api.emailscore.io
Email checks & diagnostics|openapi.json
OverviewEmail Intelligence

Overview & Workflows

Email validation, risk scoring, identity signals, and bounce diagnostics.

EmailScore helps teams decide which email addresses to accept, which contacts need further verification, and how to respond when delivery fails.

A risk recommendation does not prove mailbox ownership, human identity, or successful delivery. End-to-end API timing includes network and lookup work beyond engine evaluation.

Diagnostic processing can involve an external service when configured. Do not infer offline processing, zero retention, or compliance commitments from the scoring architecture; review the privacy policy for data-handling information.

  • Screen signups: review disposable addresses, domain problems, and suspicious patterns.
  • Score domains: check a domain on its own with POST /v1/domain, or up to 10,000 with POST /v1/domain/bulk, using the same domain check embedded in every email result.
  • Evaluate contact lists: screen batches and prioritize further verification.
  • Recognize email aliases: use normalization and fingerprints in your own workflows.
  • Diagnose delivery failures: classify supplied mailserver errors and review next actions.
OverviewBearer Token

Authentication

Authenticate API requests using standard HTTP Bearer tokens in the Authorization header.

Pass your secret API key in the Authorization header on every request using the standard Bearer scheme. API keys begin with the prefix es_live_ followed by 32 alphanumeric characters.

Requests sent without an Authorization header or with an invalid key will return an HTTP 401 Unauthorized response with a machine-readable JSON error payload.

Keep your secret API keys safe. Never expose secret keys in client-side applications, public repositories, or mobile app bundles.
Header Format
Authorization: Bearer es_live_demo12345
Never expose secret keys on public clients or web browsers.
OverviewIntegration

Quickstart by Language

Ready-to-run API integration commands for cURL, Ruby, Python, Node.js, Go, PHP, and Rust.

Select your programming language from the code console on the right, or copy the terminal command to evaluate an email.

Terminal One-Liner (cURL)
curl -sS -X POST "https://api.emailscore.io/v1/email" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "[email protected]"}'
OverviewResponses

Response Formats

Choose between full diagnostic payloads, compact representations, or sparse field bitmask projections.

By default, EmailScore returns a comprehensive evaluation document with nested audit objects, security signals, and provider details. For edge runtimes or mobile clients with strict latency budgets, use specialized format representations.

Format QueryDescription
(default)Detailed diagnostic object with domain, syntax, risk, and identity signals.
?format=compactFlattened response containing the main decision fields.
?fields=score,decision,identity.fingerprintReturn only the requested fields.
OverviewBandwidth

Wire Stream Compression

Reduce transferred payload size with HTTP compression; savings depend on the data.

The API supports standard HTTP compression on both inbound request bodies and outbound responses. When querying bulk endpoints with thousands of addresses, transmitting compressed payloads dramatically cuts round-trip network transit times.

  • gzip: Universal compression supported across all HTTP clients (Accept-Encoding: gzip).
  • brotli (br): Optimized for high compression density (Accept-Encoding: br).
  • zstd: Ultra-fast decompression designed for high-concurrency microservice clusters (Accept-Encoding: zstd).
OverviewTelemetry

Decision Matrix

Use allow, challenge, and deny recommendations in your application policy.

EmailScore maps address, domain, and identity signals to a score from 0 to 100 and a decision recommendation. Neither the score nor the recommendation establishes mailbox ownership, human identity, or successful delivery.

DecisionScore RangeRecommended ActionCriteria
ALLOW70 – 100Consider accepting under your policyLower-risk combination of address, domain, and identity signals.
CHALLENGE40 – 69Request additional verification or reviewAmbiguous signals that merit another check.
DENY0 – 39Apply your rejection or review policyHigher-risk indicators; inspect the supporting reason.
OverviewDeliverability

Post-Flight SMTP Bounce Diagnostics

Automate bounce suppression and retry scheduling from raw SMTP DSN strings.

When downstream mail transfer agents (SendGrid, Postmark, Amazon SES, Mailgun) encounter delivery failures, pass the raw SMTP error string to POST /v1/bounce/diagnose.

The engine categorizes the failure into prune_permanent, retry_transient, or investigate_block with an explicit deliverability action. Uses 5 credits per diagnosis. This interprets a supplied delivery failure; it does not predict future bounces.

OverviewQuotas

Rate Limits & Telemetry Headers

Inspect real-time quota consumption and execution timing via HTTP response headers.

Every response from the EmailScore edge gateway includes standard telemetry headers to help your application manage quota budgets and benchmark response times.

HeaderTypeDescription
X-RateLimit-LimitintegerMaximum number of requests permitted per minute.
X-RateLimit-RemainingintegerRemaining request quota in the current 60-second window.
X-RateLimit-ResetintegerUnix timestamp in seconds when the quota counter resets.
Server-TimingstringDetailed millisecond telemetry breakdown (e.g. edge;dur=0.21, dns;dur=0.08).
OverviewHTTP Codes

Standard HTTP Status & Error Codes

Conventional HTTP status codes returned by the edge gateway.

EmailScore uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, 4xx range indicate client errors, and 5xx range indicate edge gateway errors.

Status CodeStatus TextDescription
200OKRequest executed successfully. Returns verification or diagnostic results.
400Bad RequestMalformed request payload, missing required fields, invalid JSON syntax, or more than 10,000 items in one batch.
401UnauthorizedMissing or invalid Bearer API key in Authorization header.
404Not FoundRequested resource or endpoint route does not exist.
413Payload Too LargeRequest body larger than 2 MB.
429Too Many RequestsRate limit exceeded. Check X-RateLimit-Reset before retrying.
500Internal Server ErrorEngine error. If persistent, reach out to EmailScore developer support.
503Service UnavailableEdge gateway temporarily degraded. Safe to retry with exponential backoff.
Reference/Core REST Methods

API Endpoints

REST interfaces for single and batch email screening, identity signals, and bounce diagnostics.

Core Verification

Evaluate an email address for quality, risk, and identity signals

POST/v1/email

Evaluate syntax, domain and DNS signals, disposable-address indicators, and identity patterns. Returns a risk score, decision recommendation, and supporting signals for signup screening, contact evaluation, and alias handling. A result does not establish mailbox ownership, human identity, or successful delivery. Uses 1 credit per address check. The domain part of every address is scored by the same check as `/v1/domain`, and that result is returned as `domain_verdict`, so the two endpoints never disagree about a domain.

Request Headers

Authorizationstringrequired

Your secret API key.

Content-Typestringrequired

Must be `application/json`.

Query Parameters

emailstringoptional

Email address to evaluate via GET query parameter (alternative to POST JSON body).

formatstringoptionaldefault: full

Set to `compact` for an ultra-fast, flattened 10-field response omitting deep sub-objects.

options:fullcompact
fieldsstringoptional

Comma-separated sparse field projection to minimize payload size and latency.

Request Body (JSON)

emailstringoptional

The raw email address to score.

formatstringoptional

Optional format override in request body (`full` or `compact`).

fieldsstringoptional

Optional sparse field projection override in request body.

Response Attributes

emailstringoptional

Original email address evaluated.

local_partstringoptional

Extracted local part (username) before the @ symbol.

domainstringoptional

Extracted domain name after the @ symbol.

scoreintegeroptional

Deterministic quality score from 0 (fraudulent/dead) to 100 (high confidence legitimate).

decisionstringoptional

Risk-based policy recommendation: `allow`, `challenge`, or `deny`. Review supporting signals; this is not proof of ownership, human identity, or delivery.

options:allowchallengedeny
risk_levelstringoptional

Categorical risk assessment.

options:lowmediumhighcritical
recommendationstringoptional

Clean, actionable signup gatekeeper directive.

evaluation_time_msnumberoptional

Server-side evaluation time in milliseconds for this request; not an end-to-end API latency guarantee.

identityobjectoptional

Canonical identity deduplication object.

normalized_emailstringoptional

Canonical email (lowercase, stripped Gmail dots and +alias extensions).

fingerprintstringoptional

SHA-256 cryptographic hash of normalized email for account deduplication and sybil attack blocking.

local_partstringoptional

Base local part.

domainstringoptional

Canonical domain name.

has_subaddressingbooleanoptional

Whether email contains plus-aliasing (e.g. [email protected]).

subaddressstringoptional

The extracted subaddress tag if present, else null.

has_dot_stuffingbooleanoptional

Whether email contains dot stuffing patterns (e.g. [email protected]).

classificationobjectoptional

Domain and account classification.

account_typestringoptional

Organizational account category.

options:businessconsumer_freeeducationgovernmentdisposable
is_business_emailbooleanoptional

True if domain belongs to a commercial corporate organization.

is_free_providerbooleanoptional

True for consumer webmail (Gmail, Yahoo, Outlook, ProtonMail, etc.).

is_disposablebooleanoptional

True if provider is a temporary or throwaway inbox service.

is_role_accountbooleanoptional

True for generic functional handles (admin@, support@, info@, billing@).

tld_tierstringoptional

TLD abuse reputation tier.

options:premiumstandardsuspicious
syntaxobjectoptional

RFC 5321 / 5322 syntax validation and auto-correction.

is_valid_formatbooleanoptional

True if email conforms to RFC standards.

did_you_meanstringoptional

Did-you-mean suggestion for mistyped domains (e.g. `[email protected]` for `[email protected]`).

email_qualityobjectoptional

Local-part quality signals (sanitized production contract).

scoreintegeroptional

Quality score for the username component (0-100).

is_role_accountbooleanoptional

True if handle is a shared organizational role account.

has_subaddressingbooleanoptional

True if subaddress delimiter detected.

has_dot_stuffingbooleanoptional

True if dot stuffing detected.

domain_qualityobjectoptional

Domain reputation and DomainLedger dynamic maturity.

scoreintegeroptional

Domain quality score (0-100).

domainstringoptional

Domain evaluated.

registered_datestringoptional

Original domain registration date (YYYY-MM-DD).

registered_atintegeroptional

Unix epoch timestamp of registration.

age_daysintegeroptional

Domain age in days calculated in real-time.

provider_typestringoptional

Domain infrastructure type.

options:disposablepublic_freecustom_corporategeneric_hosted
tld_tierstringoptional

TLD tier.

options:premiumstandardsuspicious
is_deadbooleanoptional

True if domain is NXDOMAIN, abandoned, or dropped.

is_parkedbooleanoptional

True if domain is parked or holding page.

lengthintegeroptional

Character length of the domain name.

statusstringoptional

Domain status.

options:activedeadparkedno_mx
dnsobjectoptional

Live DNS and mail server routing.

has_mxbooleanoptional

True if domain has valid MX or fallback mail exchangers.

mx_recordsarrayoptional

List of resolved mail exchanger hosts.

vendorstringoptional

Detected email infrastructure vendor (e.g. Google Workspace, Microsoft 365).

has_spfbooleanoptional

True if SPF records are configured.

has_dmarcbooleanoptional

True if DMARC policy is published.

resolution_statusstringoptional

DNS resolution status code.

domain_verdictobjectoptional

Verdict on the domain part alone. Same values `/v1/domain` returns for this domain.

scoreintegeroptional

Domain risk score from 0 to 100.

decisionstringoptional

Recommendation for the domain alone: `allow`, `challenge`, or `deny`.

options:allowchallengedeny
risk_levelstringoptional

Categorical risk assessment for the domain.

options:lowmediumhighcritical
recommendationstringoptional

Short explanation of the domain decision.

flagsarrayoptional

Domain risk flags (see `/v1/domain` for the list). Empty array for a clean domain.

evidencestringoptional

`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.

options:completepartial
flagsarrayoptional

Security exception and anomaly triggers (e.g. `SUSPICIOUS_HANDLE_PATTERN`, `DISPOSABLE_DOMAIN`, `NO_MX_RECORDS`). Empty array for clean addresses.

curl -sS -X POST "https://api.emailscore.io/v1/email" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
Response
{
  "email": "[email protected]",
  "local_part": "sarah.jenkins",
  "domain": "gmail.com",
  "score": 92,
  "decision": "allow",
  "risk_level": "low",
  "recommendation": "Allow signup: high confidence legitimate user.",
  "evaluation_time_ms": 0.28,
  "identity": {
    "normalized_email": "[email protected]",
    "fingerprint": "8f462664790604f97eab4b104d580d8f824c643038b600a96115bf4014194071",
    "local_part": "sarah.jenkins",
    "domain": "gmail.com",
    "has_subaddressing": false,
    "subaddress": null,
    "has_dot_stuffing": false
  },
  "classification": {
    "account_type": "consumer_free",
    "is_business_email": false,
    "is_free_provider": true,
    "is_disposable": false,
    "is_role_account": false,
    "tld_tier": "standard"
  },
  "syntax": {
    "is_valid_format": true,
    "did_you_mean": null
  },
  "email_quality": {
    "score": 95,
    "is_role_account": false,
    "has_subaddressing": false,
    "has_dot_stuffing": false
  },
  "domain_quality": {
    "score": 98,
    "domain": "gmail.com",
    "registered_date": "1995-08-13",
    "registered_at": 874281600,
    "age_days": 10592,
    "provider_type": "public_free",
    "tld_tier": "premium",
    "is_dead": false,
    "is_parked": false,
    "length": 9,
    "status": "active"
  },
  "dns": {
    "has_mx": true,
    "mx_records": [
      "gmail-smtp-in.l.google.com"
    ],
    "vendor": "Google (Gmail Consumer)",
    "has_spf": true,
    "has_dmarc": true,
    "resolution_status": "resolved"
  },
  "domain_verdict": {
    "score": 99,
    "decision": "allow",
    "risk_level": "low",
    "recommendation": "Allow: established domain with working mail.",
    "flags": [],
    "evidence": "complete"
  },
  "flags": []
}
Core Verification

Screen and score a batch of email addresses

POST/v1/email/bulk(/v1/email/batch)

Screen contact lists for address-quality and risk signals. Returns summary statistics and per-address results for review and further verification decisions. Batch results do not confirm mailbox ownership or guarantee delivery. Uses 1 credit per address check.

Request Headers

Authorizationstringrequired

Your secret API key.

Content-Typestringrequired

Must be `application/json`.

Accept-Encodingstringoptional

Optional compression header. Highly recommended for payloads with >1,000 emails.

Query Parameters

fieldsstringoptional

Optional sparse fieldset projection to minimize response payload bandwidth.

Request Body (JSON)

emailsarrayoptional

Array of email addresses to clean and score (up to 10,000 per request).

formatstringoptional

Format selector (batch always outputs compact result rows).

fieldsstringoptional

Optional field mask.

Response Attributes

totalintegeroptional

Total number of emails received in the batch.

processedintegeroptional

Number of emails successfully evaluated.

evaluation_time_msnumberoptional

Total server-side processing duration in milliseconds.

summaryobjectoptional

Aggregate classification counts across the batch.

allowintegeroptional

Total high-confidence legitimate emails.

challengeintegeroptional

Total moderate-risk / role-based emails.

denyintegeroptional

Total invalid, disposable, or fraudulent emails.

resultsarrayoptional

Per-email evaluation records.

emailstringoptional

Original email evaluated.

scoreintegeroptional

Quality score from 0 to 100.

decisionstringoptional

Actionable decision.

options:allowchallengedeny
risk_levelstringoptional

Risk category.

options:lowmediumhighcritical
account_typestringoptional

Organization category.

options:businessconsumer_freeeducationgovernmentdisposable
is_business_emailbooleanoptional

True if domain belongs to a commercial enterprise.

is_disposablebooleanoptional

True if temporary/burner email provider.

did_you_meanstringoptional

Typo suggestion if domain was mistyped, else null.

fingerprintstringoptional

SHA-256 canonical identity hash.

flagsarrayoptional

Sanitized public security flags.

recommendationstringoptional

Standardized gatekeeper policy recommendation.

curl -sS -X POST "https://api.emailscore.io/v1/email/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept-Encoding: gzip" \
  -d '{"emails": ["[email protected]", "[email protected]", "[email protected]"]}'
Response
{
  "total": 3,
  "processed": 3,
  "evaluation_time_ms": 1.42,
  "summary": {
    "allow": 2,
    "challenge": 0,
    "deny": 1
  },
  "results": [
    {
      "email": "[email protected]",
      "score": 92,
      "decision": "allow",
      "risk_level": "low",
      "account_type": "consumer_free",
      "is_business_email": false,
      "is_disposable": false,
      "did_you_mean": null,
      "fingerprint": "8f462664790604f97eab4b104d580d8f824c643038b600a96115bf4014194071",
      "flags": [],
      "recommendation": "Allow signup: high confidence legitimate user."
    },
    {
      "email": "[email protected]",
      "score": 98,
      "decision": "allow",
      "risk_level": "low",
      "account_type": "business",
      "is_business_email": true,
      "is_disposable": false,
      "did_you_mean": null,
      "fingerprint": "207a9dc3e6aa00898ec0ffbeec946e382cc094bc028f0ee0434407b46618e4bc",
      "flags": [],
      "recommendation": "Allow signup: high confidence legitimate user."
    },
    {
      "email": "[email protected]",
      "score": 0,
      "decision": "deny",
      "risk_level": "critical",
      "account_type": "disposable",
      "is_business_email": false,
      "is_disposable": true,
      "did_you_mean": null,
      "fingerprint": "e57ff311c15b13e90b8f056d3cff4c980387b32a265691079d3be4737d26bbad",
      "flags": [
        "DISPOSABLE_DOMAIN"
      ],
      "recommendation": "Deny signup: disposable or temporary email addresses are not accepted."
    }
  ]
}
Core Verification

Score a domain on its own, without an email address

POST/v1/domain

Score a domain by itself: registration age, dead or parked status, disposable providers, mail DNS (MX, SPF, DMARC), random-looking names and brand look-alikes, TLD tier, and typo detection. Returns a risk score, decision recommendation, and the domain and DNS facts behind it. `/v1/email` runs this same domain check on the domain part of every address and embeds the result as `domain_verdict`, so the two endpoints never disagree about a domain. `evidence` is `complete` when DNS was looked up, or `partial` when it was not; with `partial`, mail facts (MX, SPF, DMARC) are unknown rather than absent. Uses 1 credit per domain check. Flags: - `TYPO_DOMAIN_SUGGESTION`, `DOMAIN_TYPO_SUSPECTED`: looks like a misspelling of a known provider; see `did_you_mean`. - `ZERO_DAY_DOMAIN`: registered 30 days ago or less. - `VERY_YOUNG_DOMAIN`: registered 31 to 89 days ago. - `DISPOSABLE_DOMAIN`: temporary or throwaway inbox provider. - `DEAD_DOMAIN`: does not resolve (NXDOMAIN), abandoned, or dropped. - `PARKED_DOMAIN`: parked or holding page. - `SUSPICIOUS_TLD`: TLD with a high abuse rate. - `SUSPICIOUS_DOMAIN_PATTERN`: random-looking name, brand look-alike, or other name-pattern penalty. - `NO_MX_RECORDS`: DNS answered and the domain has no mail servers. - `DNS_LOOKUP_INCOMPLETE`: the DNS lookup did not finish; mail facts are unknown, not missing. - `NULL_MX_RECORD`: publishes a null MX (RFC 7505), declaring it accepts no mail. - `BOGON_MX_RECORD`: MX points to a private or reserved address. - `NO_MX_A_RECORD_ONLY`: no MX; mail would fall back to the A record. - `GENERIC_HOSTING_PROVIDER`: unrecognized domain without the MX plus SPF or DMARC setup of a maintained organization. - `UNESTABLISHED_DOMAIN`: nothing on record establishes the domain (no registration history or reputation), and no more specific flag explains the held verdict.

Request Headers

Authorizationstringrequired

Your secret API key.

Content-Typestringrequired

Must be `application/json`.

Query Parameters

domainstringoptional

Domain to evaluate via GET query parameter (alternative to POST JSON body).

Request Body (JSON)

domainstringoptional

The domain name to score, without a local part or `@`.

Response Attributes

domainstringoptional

Domain evaluated.

scoreintegeroptional

Domain risk score from 0 (dead, disposable, or unusable for mail) to 100 (established domain with working mail).

decisionstringoptional

Risk-based policy recommendation: `allow`, `challenge`, or `deny`. It describes the domain only, not any mailbox on it.

options:allowchallengedeny
risk_levelstringoptional

Categorical risk assessment.

options:lowmediumhighcritical
recommendationstringoptional

Short explanation of the decision.

flagsarrayoptional

Domain risk flags (listed in the endpoint description). Empty array for a clean domain.

evidencestringoptional

`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.

options:completepartial
did_you_meanstringoptional

Suggested domain when the input looks like a typo of a known provider (e.g. `gmail.com` for `gmial.com`), else null.

evaluation_time_msnumberoptional

Server-side evaluation time in milliseconds for this request; not an end-to-end API latency guarantee.

domain_qualityobjectoptional

Domain reputation, registration age, and status.

scoreintegeroptional

Domain quality score (0-100).

domainstringoptional

Domain evaluated.

registered_datestringoptional

Original domain registration date (YYYY-MM-DD).

registered_atintegeroptional

Unix epoch timestamp of registration.

age_daysintegeroptional

Domain age in days, calculated at request time.

provider_typestringoptional

Domain infrastructure type.

options:disposablepublic_freecustom_corporategeneric_hosted
tld_tierstringoptional

TLD abuse reputation tier.

options:premiumstandardsuspicious
is_deadbooleanoptional

True if domain is NXDOMAIN, abandoned, or dropped.

is_parkedbooleanoptional

True if domain is parked or a holding page.

lengthintegeroptional

Character length of the domain name.

statusstringoptional

Domain status.

options:activedeadparkedno_mx
dnsobjectoptional

Mail DNS for the domain. Unknown when `evidence` is `partial`.

has_mxbooleanoptional

True if domain has valid MX or fallback mail exchangers.

mx_recordsarrayoptional

List of resolved mail exchanger hosts.

vendorstringoptional

Detected email infrastructure vendor (e.g. Google Workspace, Microsoft 365).

has_spfbooleanoptional

True if SPF records are configured.

has_dmarcbooleanoptional

True if DMARC policy is published.

resolution_statusstringoptional

DNS resolution status code.

curl -sS -X POST "https://api.emailscore.io/v1/domain" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.com"}'
Response
{
  "domain": "acme.com",
  "score": 91,
  "decision": "allow",
  "risk_level": "low",
  "recommendation": "Allow: established domain with working mail.",
  "flags": [],
  "evidence": "complete",
  "did_you_mean": null,
  "evaluation_time_ms": 0.08,
  "domain_quality": {
    "score": 85,
    "domain": "acme.com",
    "registered_date": "1997-09-15",
    "registered_at": 874281600,
    "age_days": 10600,
    "provider_type": "custom_corporate",
    "tld_tier": "premium",
    "is_dead": false,
    "is_parked": false,
    "length": 8,
    "status": "active"
  },
  "dns": {
    "has_mx": true,
    "mx_records": [
      "mx1.acme.com"
    ],
    "vendor": "Google Workspace",
    "has_spf": true,
    "has_dmarc": true,
    "resolution_status": "preloaded_ledger"
  }
}
Core Verification

Score a batch of domains

POST/v1/domain/bulk(/v1/domain/batch)

Score up to 10,000 domains in one request. Each result is produced by the same domain check as `/v1/domain`, so a domain's bulk result always equals its single `/v1/domain` result without `domain_quality`, `dns`, and `evaluation_time_ms`. Send `{"domains": [...]}` or a raw JSON array of strings. Results come back in the order submitted. Valid domains are returned normalized (trimmed, lowercased, trailing dot removed); an invalid entry is returned as submitted (trimmed) with the `INVALID_FORMAT` flag. Uses 1 credit per submitted domain, invalid entries included. Guest trial tokens (`es_temp_...`) cannot use bulk and receive 403 `registration_required`. `evidence` is `complete` when DNS was looked up, or `partial` when it was not; with `partial`, mail facts (MX, SPF, DMARC) are unknown rather than absent. Flags: - `INVALID_FORMAT`: the entry is not a valid domain name. - `TYPO_DOMAIN_SUGGESTION`, `DOMAIN_TYPO_SUSPECTED`: looks like a misspelling of a known provider; see `did_you_mean`. - `ZERO_DAY_DOMAIN`: registered 30 days ago or less. - `VERY_YOUNG_DOMAIN`: registered 31 to 89 days ago. - `DISPOSABLE_DOMAIN`: temporary or throwaway inbox provider. - `DEAD_DOMAIN`: does not resolve (NXDOMAIN), abandoned, or dropped. - `PARKED_DOMAIN`: parked or holding page. - `SUSPICIOUS_TLD`: TLD with a high abuse rate. - `SUSPICIOUS_DOMAIN_PATTERN`: random-looking name, brand look-alike, or other name-pattern penalty. - `NO_MX_RECORDS`: DNS answered and the domain has no mail servers. - `DNS_LOOKUP_INCOMPLETE`: the DNS lookup did not finish; mail facts are unknown, not missing. - `NULL_MX_RECORD`: publishes a null MX (RFC 7505), declaring it accepts no mail. - `BOGON_MX_RECORD`: MX points to a private or reserved address. - `NO_MX_A_RECORD_ONLY`: no MX; mail would fall back to the A record. - `GENERIC_HOSTING_PROVIDER`: unrecognized domain without the MX plus SPF or DMARC setup of a maintained organization. - `UNESTABLISHED_DOMAIN`: nothing on record establishes the domain (no registration history or reputation), and no more specific flag explains the held verdict.

Request Headers

Authorizationstringrequired

Your secret API key.

Content-Typestringrequired

Must be `application/json`.

Accept-Encodingstringoptional

Optional compression header. Recommended for large batches.

Request Body (JSON)

domainsarrayoptional

Array of domains to score (1 to 10,000 per request). A raw JSON array of strings is also accepted as the whole body.

Response Attributes

totalintegeroptional

Number of domains received in the batch.

processedintegeroptional

Number of domains evaluated.

evaluation_time_msnumberoptional

Total server-side processing duration in milliseconds for the batch.

summaryobjectoptional

Decision counts across the batch.

allowintegeroptional

Domains with an `allow` decision.

challengeintegeroptional

Domains with a `challenge` decision.

denyintegeroptional

Domains with a `deny` decision, including invalid entries.

resultsarrayoptional

Per-domain verdicts in submission order. Each equals the `/v1/domain` result for that domain without `domain_quality`, `dns`, and `evaluation_time_ms`.

domainstringoptional

Normalized domain (trimmed, lowercased, trailing dot removed), or the trimmed input for an invalid entry.

scoreintegeroptional

Domain risk score from 0 to 100.

decisionstringoptional

Recommendation for the domain: `allow`, `challenge`, or `deny`.

options:allowchallengedeny
risk_levelstringoptional

Categorical risk assessment.

options:lowmediumhighcritical
recommendationstringoptional

Short explanation of the decision.

flagsarrayoptional

Domain risk flags (listed in the endpoint description). Empty array for a clean domain.

evidencestringoptional

`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.

options:completepartial
did_you_meanstringoptional

Suggested domain when the input looks like a typo of a known provider, else null.

curl -sS -X POST "https://api.emailscore.io/v1/domain/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept-Encoding: gzip" \
  -d '{"domains": ["google.com", "gmial.com", "not a domain"]}'
Response
{
  "total": 3,
  "processed": 3,
  "evaluation_time_ms": 41.7,
  "summary": {
    "allow": 1,
    "challenge": 0,
    "deny": 2
  },
  "results": [
    {
      "domain": "google.com",
      "score": 100,
      "decision": "allow",
      "risk_level": "low",
      "recommendation": "Allow: established domain with working mail.",
      "flags": [],
      "evidence": "complete",
      "did_you_mean": null
    },
    {
      "domain": "gmial.com",
      "score": 0,
      "decision": "deny",
      "risk_level": "critical",
      "recommendation": "Deny: disposable or temporary email addresses are not accepted.",
      "flags": [
        "TYPO_DOMAIN_SUGGESTION",
        "DOMAIN_TYPO_SUSPECTED",
        "DISPOSABLE_DOMAIN"
      ],
      "evidence": "partial",
      "did_you_mean": "gmail.com"
    },
    {
      "domain": "not a domain",
      "score": 0,
      "decision": "deny",
      "risk_level": "critical",
      "recommendation": "Deny: not a valid domain.",
      "flags": [
        "INVALID_FORMAT"
      ],
      "evidence": "partial",
      "did_you_mean": null
    }
  ]
}
Post-Flight Diagnostics

Parse raw SMTP error diagnostics into structured deliverability actions

POST/v1/bounce/diagnose(/v1/bounce/batch)

Classify supplied mailserver error messages and recommend a next action, such as suppressing a permanently failed address, retrying a temporary failure, or investigating a block. This analyzes a delivery failure that has already occurred; it does not predict a future bounce. Metered at **5 credits** per diagnosis. Processing can use an external service when configured; do not assume that all diagnostics are evaluated offline.

Request Headers

Authorizationstringrequired

Your secret API key.

Content-Typestringrequired

Must be `application/json`.

Request Body (JSON)

diagnosticstringoptional

The raw SMTP response line or error string returned by the receiving mailserver.

emailstringoptional

Optional recipient email address associated with the bounce event.

Response Attributes

diagnosticstringrequired

Echo of the input diagnostic string.

emailstringoptional

Associated email address if provided in request.

categorystringrequired

Standard RFC deliverability classification.

options:hard_bounce_user_unknownsoft_bounce_mailbox_fullip_or_domain_blacklistedauthentication_failuretransient_network_timeout
actionstringrequired

Recommended handling of the supplied failure: review permanent suppression for `prune_permanent`, or retry policy for `retry_transient`.

options:prune_permanentretry_transient
permanent_hard_bounce_probabilitynumberrequired

Probability [0.0 to 1.0] that this bounce is an unrecoverable hard bounce.

confidencenumberrequired

Confidence level of category classification.

recommendationstringrequired

Concrete engineering and deliverability guidance.

evaluation_time_msnumberrequired

Processing latency in milliseconds.

curl -sS -X POST "https://api.emailscore.io/v1/bounce/diagnose" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"diagnostic": "550 5.1.1 <[email protected]>: Recipient address rejected: User unknown in virtual mailbox table", "email": "[email protected]"}'
Response
{
  "diagnostic": "550 5.1.1 <[email protected]>: Recipient address rejected: User unknown in virtual mailbox table",
  "email": "[email protected]",
  "category": "hard_bounce_user_unknown",
  "action": "prune_permanent",
  "permanent_hard_bounce_probability": 0.96,
  "confidence": 1,
  "recommendation": "Permanently remove recipient address from mailing lists. Mailbox does not exist or was rejected permanently by the target server.",
  "evaluation_time_ms": 245.8
}
Data Contracts/JSON Schemas

Schemas & Models

Data structures and object definitions used in request bodies and response payloads.

Schema Modelobject

CheckSingleRequest

Data schema model for CheckSingleRequest.

Attributes

emailstringrequired

The raw email address to score.

formatstringoptional

Optional format override in request body (`full` or `compact`).

fieldsstringoptional

Optional sparse field projection override in request body.

Schema Modelobject

CheckSingleResponse

Data schema model for CheckSingleResponse.

Attributes

emailstringoptional

Original email address evaluated.

local_partstringoptional

Extracted local part (username) before the @ symbol.

domainstringoptional

Extracted domain name after the @ symbol.

scoreintegeroptional

Deterministic quality score from 0 (fraudulent/dead) to 100 (high confidence legitimate).

decisionstringoptional

Risk-based policy recommendation: `allow`, `challenge`, or `deny`. Review supporting signals; this is not proof of ownership, human identity, or delivery.

options:allowchallengedeny
risk_levelstringoptional

Categorical risk assessment.

options:lowmediumhighcritical
recommendationstringoptional

Clean, actionable signup gatekeeper directive.

evaluation_time_msnumberoptional

Server-side evaluation time in milliseconds for this request; not an end-to-end API latency guarantee.

identityobjectoptional

Canonical identity deduplication object.

normalized_emailstringoptional

Canonical email (lowercase, stripped Gmail dots and +alias extensions).

fingerprintstringoptional

SHA-256 cryptographic hash of normalized email for account deduplication and sybil attack blocking.

local_partstringoptional

Base local part.

domainstringoptional

Canonical domain name.

has_subaddressingbooleanoptional

Whether email contains plus-aliasing (e.g. [email protected]).

subaddressstringoptional

The extracted subaddress tag if present, else null.

has_dot_stuffingbooleanoptional

Whether email contains dot stuffing patterns (e.g. [email protected]).

classificationobjectoptional

Domain and account classification.

account_typestringoptional

Organizational account category.

options:businessconsumer_freeeducationgovernmentdisposable
is_business_emailbooleanoptional

True if domain belongs to a commercial corporate organization.

is_free_providerbooleanoptional

True for consumer webmail (Gmail, Yahoo, Outlook, ProtonMail, etc.).

is_disposablebooleanoptional

True if provider is a temporary or throwaway inbox service.

is_role_accountbooleanoptional

True for generic functional handles (admin@, support@, info@, billing@).

tld_tierstringoptional

TLD abuse reputation tier.

options:premiumstandardsuspicious
syntaxobjectoptional

RFC 5321 / 5322 syntax validation and auto-correction.

is_valid_formatbooleanoptional

True if email conforms to RFC standards.

did_you_meanstringoptional

Did-you-mean suggestion for mistyped domains (e.g. `[email protected]` for `[email protected]`).

email_qualityobjectoptional

Local-part quality signals (sanitized production contract).

scoreintegeroptional

Quality score for the username component (0-100).

is_role_accountbooleanoptional

True if handle is a shared organizational role account.

has_subaddressingbooleanoptional

True if subaddress delimiter detected.

has_dot_stuffingbooleanoptional

True if dot stuffing detected.

domain_qualityobjectoptional

Domain reputation and DomainLedger dynamic maturity.

scoreintegeroptional

Domain quality score (0-100).

domainstringoptional

Domain evaluated.

registered_datestringoptional

Original domain registration date (YYYY-MM-DD).

registered_atintegeroptional

Unix epoch timestamp of registration.

age_daysintegeroptional

Domain age in days calculated in real-time.

provider_typestringoptional

Domain infrastructure type.

options:disposablepublic_freecustom_corporategeneric_hosted
tld_tierstringoptional

TLD tier.

options:premiumstandardsuspicious
is_deadbooleanoptional

True if domain is NXDOMAIN, abandoned, or dropped.

is_parkedbooleanoptional

True if domain is parked or holding page.

lengthintegeroptional

Character length of the domain name.

statusstringoptional

Domain status.

options:activedeadparkedno_mx
dnsobjectoptional

Live DNS and mail server routing.

has_mxbooleanoptional

True if domain has valid MX or fallback mail exchangers.

mx_recordsarrayoptional

List of resolved mail exchanger hosts.

vendorstringoptional

Detected email infrastructure vendor (e.g. Google Workspace, Microsoft 365).

has_spfbooleanoptional

True if SPF records are configured.

has_dmarcbooleanoptional

True if DMARC policy is published.

resolution_statusstringoptional

DNS resolution status code.

domain_verdictobjectoptional

Verdict on the domain part alone. Same values `/v1/domain` returns for this domain.

scoreintegeroptional

Domain risk score from 0 to 100.

decisionstringoptional

Recommendation for the domain alone: `allow`, `challenge`, or `deny`.

options:allowchallengedeny
risk_levelstringoptional

Categorical risk assessment for the domain.

options:lowmediumhighcritical
recommendationstringoptional

Short explanation of the domain decision.

flagsarrayoptional

Domain risk flags (see `/v1/domain` for the list). Empty array for a clean domain.

evidencestringoptional

`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.

options:completepartial
flagsarrayoptional

Security exception and anomaly triggers (e.g. `SUSPICIOUS_HANDLE_PATTERN`, `DISPOSABLE_DOMAIN`, `NO_MX_RECORDS`). Empty array for clean addresses.

Schema Modelobject

CheckBulkRequest

Data schema model for CheckBulkRequest.

Attributes

emailsarrayrequired

Array of email addresses to clean and score (up to 10,000 per request).

formatstringoptional

Format selector (batch always outputs compact result rows).

fieldsstringoptional

Optional field mask.

Schema Modelobject

CheckBulkResponse

Data schema model for CheckBulkResponse.

Attributes

totalintegeroptional

Total number of emails received in the batch.

processedintegeroptional

Number of emails successfully evaluated.

evaluation_time_msnumberoptional

Total server-side processing duration in milliseconds.

summaryobjectoptional

Aggregate classification counts across the batch.

allowintegeroptional

Total high-confidence legitimate emails.

challengeintegeroptional

Total moderate-risk / role-based emails.

denyintegeroptional

Total invalid, disposable, or fraudulent emails.

resultsarrayoptional

Per-email evaluation records.

emailstringoptional

Original email evaluated.

scoreintegeroptional

Quality score from 0 to 100.

decisionstringoptional

Actionable decision.

options:allowchallengedeny
risk_levelstringoptional

Risk category.

options:lowmediumhighcritical
account_typestringoptional

Organization category.

options:businessconsumer_freeeducationgovernmentdisposable
is_business_emailbooleanoptional

True if domain belongs to a commercial enterprise.

is_disposablebooleanoptional

True if temporary/burner email provider.

did_you_meanstringoptional

Typo suggestion if domain was mistyped, else null.

fingerprintstringoptional

SHA-256 canonical identity hash.

flagsarrayoptional

Sanitized public security flags.

recommendationstringoptional

Standardized gatekeeper policy recommendation.

Schema Modelobject

DomainSingleRequest

Data schema model for DomainSingleRequest.

Attributes

domainstringrequired

The domain name to score, without a local part or `@`.

Schema Modelobject

DomainSingleResponse

Data schema model for DomainSingleResponse.

Attributes

domainstringoptional

Domain evaluated.

scoreintegeroptional

Domain risk score from 0 (dead, disposable, or unusable for mail) to 100 (established domain with working mail).

decisionstringoptional

Risk-based policy recommendation: `allow`, `challenge`, or `deny`. It describes the domain only, not any mailbox on it.

options:allowchallengedeny
risk_levelstringoptional

Categorical risk assessment.

options:lowmediumhighcritical
recommendationstringoptional

Short explanation of the decision.

flagsarrayoptional

Domain risk flags (listed in the endpoint description). Empty array for a clean domain.

evidencestringoptional

`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.

options:completepartial
did_you_meanstringoptional

Suggested domain when the input looks like a typo of a known provider (e.g. `gmail.com` for `gmial.com`), else null.

evaluation_time_msnumberoptional

Server-side evaluation time in milliseconds for this request; not an end-to-end API latency guarantee.

domain_qualityobjectoptional

Domain reputation, registration age, and status.

scoreintegeroptional

Domain quality score (0-100).

domainstringoptional

Domain evaluated.

registered_datestringoptional

Original domain registration date (YYYY-MM-DD).

registered_atintegeroptional

Unix epoch timestamp of registration.

age_daysintegeroptional

Domain age in days, calculated at request time.

provider_typestringoptional

Domain infrastructure type.

options:disposablepublic_freecustom_corporategeneric_hosted
tld_tierstringoptional

TLD abuse reputation tier.

options:premiumstandardsuspicious
is_deadbooleanoptional

True if domain is NXDOMAIN, abandoned, or dropped.

is_parkedbooleanoptional

True if domain is parked or a holding page.

lengthintegeroptional

Character length of the domain name.

statusstringoptional

Domain status.

options:activedeadparkedno_mx
dnsobjectoptional

Mail DNS for the domain. Unknown when `evidence` is `partial`.

has_mxbooleanoptional

True if domain has valid MX or fallback mail exchangers.

mx_recordsarrayoptional

List of resolved mail exchanger hosts.

vendorstringoptional

Detected email infrastructure vendor (e.g. Google Workspace, Microsoft 365).

has_spfbooleanoptional

True if SPF records are configured.

has_dmarcbooleanoptional

True if DMARC policy is published.

resolution_statusstringoptional

DNS resolution status code.

Schema Modelobject

DomainBulkRequest

Data schema model for DomainBulkRequest.

Attributes

domainsarrayrequired

Array of domains to score (1 to 10,000 per request). A raw JSON array of strings is also accepted as the whole body.

Schema Modelobject

DomainBulkResponse

Data schema model for DomainBulkResponse.

Attributes

totalintegeroptional

Number of domains received in the batch.

processedintegeroptional

Number of domains evaluated.

evaluation_time_msnumberoptional

Total server-side processing duration in milliseconds for the batch.

summaryobjectoptional

Decision counts across the batch.

allowintegeroptional

Domains with an `allow` decision.

challengeintegeroptional

Domains with a `challenge` decision.

denyintegeroptional

Domains with a `deny` decision, including invalid entries.

resultsarrayoptional

Per-domain verdicts in submission order. Each equals the `/v1/domain` result for that domain without `domain_quality`, `dns`, and `evaluation_time_ms`.

domainstringoptional

Normalized domain (trimmed, lowercased, trailing dot removed), or the trimmed input for an invalid entry.

scoreintegeroptional

Domain risk score from 0 to 100.

decisionstringoptional

Recommendation for the domain: `allow`, `challenge`, or `deny`.

options:allowchallengedeny
risk_levelstringoptional

Categorical risk assessment.

options:lowmediumhighcritical
recommendationstringoptional

Short explanation of the decision.

flagsarrayoptional

Domain risk flags (listed in the endpoint description). Empty array for a clean domain.

evidencestringoptional

`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.

options:completepartial
did_you_meanstringoptional

Suggested domain when the input looks like a typo of a known provider, else null.

Schema Modelobject

BounceDiagnoseRequest

Data schema model for BounceDiagnoseRequest.

Attributes

diagnosticstringrequired

The raw SMTP response line or error string returned by the receiving mailserver.

emailstringoptional

Optional recipient email address associated with the bounce event.

Schema Modelobject

BounceDiagnoseResponse

Data schema model for BounceDiagnoseResponse.

Attributes

diagnosticstringrequired

Echo of the input diagnostic string.

emailstringoptional

Associated email address if provided in request.

categorystringrequired

Standard RFC deliverability classification.

options:hard_bounce_user_unknownsoft_bounce_mailbox_fullip_or_domain_blacklistedauthentication_failuretransient_network_timeout
actionstringrequired

Recommended handling of the supplied failure: review permanent suppression for `prune_permanent`, or retry policy for `retry_transient`.

options:prune_permanentretry_transient
permanent_hard_bounce_probabilitynumberrequired

Probability [0.0 to 1.0] that this bounce is an unrecoverable hard bounce.

confidencenumberrequired

Confidence level of category classification.

recommendationstringrequired

Concrete engineering and deliverability guidance.

evaluation_time_msnumberrequired

Processing latency in milliseconds.

Schema Modelobject

HealthResponse

Data schema model for HealthResponse.

Attributes

statusstringoptional

Cluster operational health status.

options:okdegraded
servicestringoptional

Engine runtime identifier and major version.

domainstringoptional

Canonical API authority domain.

endpointstringoptional

Primary email scoring route.

capacitystringoptional

Verified throughput range per single HTTP connection.

max_batch_sizeintegeroptional

Maximum allowable emails in a single bulk batch request.

supported_formatsarrayoptional

Output format projections supported by the engine.

sparse_fieldsetsstringoptional

Syntax directive for bitmask sparse field projection.

compressionarrayoptional

Supported transparent stream compression algorithms.

featuresarrayoptional

Active heuristic and database engines in current deployment.

Schema Modelobject

ErrorResponse

Data schema model for ErrorResponse.

Attributes

errorstringrequired

Standardized error message or machine-readable reason code.

messagestringoptional

Optional extended error explanation or remediation steps.

Example JSON Payload
{
  "error": "Invalid or revoked API key"
}