https://api.emailscore.ioOverview & 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.
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.
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.
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 Query | Description |
|---|---|
| (default) | Detailed diagnostic object with domain, syntax, risk, and identity signals. |
| ?format=compact | Flattened response containing the main decision fields. |
| ?fields=score,decision,identity.fingerprint | Return only the requested fields. |
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).
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.
| Decision | Score Range | Recommended Action | Criteria |
|---|---|---|---|
| ALLOW | 70 – 100 | Consider accepting under your policy | Lower-risk combination of address, domain, and identity signals. |
| CHALLENGE | 40 – 69 | Request additional verification or review | Ambiguous signals that merit another check. |
| DENY | 0 – 39 | Apply your rejection or review policy | Higher-risk indicators; inspect the supporting reason. |
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.
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.
| Header | Type | Description |
|---|---|---|
| X-RateLimit-Limit | integer | Maximum number of requests permitted per minute. |
| X-RateLimit-Remaining | integer | Remaining request quota in the current 60-second window. |
| X-RateLimit-Reset | integer | Unix timestamp in seconds when the quota counter resets. |
| Server-Timing | string | Detailed millisecond telemetry breakdown (e.g. edge;dur=0.21, dns;dur=0.08). |
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 Code | Status Text | Description |
|---|---|---|
| 200 | OK | Request executed successfully. Returns verification or diagnostic results. |
| 400 | Bad Request | Malformed request payload, missing required fields, invalid JSON syntax, or more than 10,000 items in one batch. |
| 401 | Unauthorized | Missing or invalid Bearer API key in Authorization header. |
| 404 | Not Found | Requested resource or endpoint route does not exist. |
| 413 | Payload Too Large | Request body larger than 2 MB. |
| 429 | Too Many Requests | Rate limit exceeded. Check X-RateLimit-Reset before retrying. |
| 500 | Internal Server Error | Engine error. If persistent, reach out to EmailScore developer support. |
| 503 | Service Unavailable | Edge gateway temporarily degraded. Safe to retry with exponential backoff. |
API Endpoints
REST interfaces for single and batch email screening, identity signals, and bounce diagnostics.
Evaluate an email address for quality, risk, and identity signals
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
Your secret API key.
Must be `application/json`.
Query Parameters
Email address to evaluate via GET query parameter (alternative to POST JSON body).
fullSet to `compact` for an ultra-fast, flattened 10-field response omitting deep sub-objects.
fullcompactComma-separated sparse field projection to minimize payload size and latency.
Request Body (JSON)
The raw email address to score.
Optional format override in request body (`full` or `compact`).
Optional sparse field projection override in request body.
Response Attributes
Original email address evaluated.
Extracted local part (username) before the @ symbol.
Extracted domain name after the @ symbol.
Deterministic quality score from 0 (fraudulent/dead) to 100 (high confidence legitimate).
Risk-based policy recommendation: `allow`, `challenge`, or `deny`. Review supporting signals; this is not proof of ownership, human identity, or delivery.
allowchallengedenyCategorical risk assessment.
lowmediumhighcriticalClean, actionable signup gatekeeper directive.
Server-side evaluation time in milliseconds for this request; not an end-to-end API latency guarantee.
Canonical identity deduplication object.
Canonical email (lowercase, stripped Gmail dots and +alias extensions).
SHA-256 cryptographic hash of normalized email for account deduplication and sybil attack blocking.
Base local part.
Canonical domain name.
Whether email contains plus-aliasing (e.g. [email protected]).
The extracted subaddress tag if present, else null.
Whether email contains dot stuffing patterns (e.g. [email protected]).
Domain and account classification.
Organizational account category.
businessconsumer_freeeducationgovernmentdisposableTrue if domain belongs to a commercial corporate organization.
True for consumer webmail (Gmail, Yahoo, Outlook, ProtonMail, etc.).
True if provider is a temporary or throwaway inbox service.
True for generic functional handles (admin@, support@, info@, billing@).
TLD abuse reputation tier.
premiumstandardsuspiciousRFC 5321 / 5322 syntax validation and auto-correction.
True if email conforms to RFC standards.
Did-you-mean suggestion for mistyped domains (e.g. `[email protected]` for `[email protected]`).
Local-part quality signals (sanitized production contract).
Quality score for the username component (0-100).
True if handle is a shared organizational role account.
True if subaddress delimiter detected.
True if dot stuffing detected.
Domain reputation and DomainLedger dynamic maturity.
Domain quality score (0-100).
Domain evaluated.
Original domain registration date (YYYY-MM-DD).
Unix epoch timestamp of registration.
Domain age in days calculated in real-time.
Domain infrastructure type.
disposablepublic_freecustom_corporategeneric_hostedTLD tier.
premiumstandardsuspiciousTrue if domain is NXDOMAIN, abandoned, or dropped.
True if domain is parked or holding page.
Character length of the domain name.
Domain status.
activedeadparkedno_mxLive DNS and mail server routing.
True if domain has valid MX or fallback mail exchangers.
List of resolved mail exchanger hosts.
Detected email infrastructure vendor (e.g. Google Workspace, Microsoft 365).
True if SPF records are configured.
True if DMARC policy is published.
DNS resolution status code.
Verdict on the domain part alone. Same values `/v1/domain` returns for this domain.
Domain risk score from 0 to 100.
Recommendation for the domain alone: `allow`, `challenge`, or `deny`.
allowchallengedenyCategorical risk assessment for the domain.
lowmediumhighcriticalShort explanation of the domain decision.
Domain risk flags (see `/v1/domain` for the list). Empty array for a clean domain.
`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.
completepartialSecurity 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]"}'{
"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": []
}Screen and score a batch of email addresses
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
Your secret API key.
Must be `application/json`.
Optional compression header. Highly recommended for payloads with >1,000 emails.
Query Parameters
Optional sparse fieldset projection to minimize response payload bandwidth.
Request Body (JSON)
Array of email addresses to clean and score (up to 10,000 per request).
Format selector (batch always outputs compact result rows).
Optional field mask.
Response Attributes
Total number of emails received in the batch.
Number of emails successfully evaluated.
Total server-side processing duration in milliseconds.
Aggregate classification counts across the batch.
Total high-confidence legitimate emails.
Total moderate-risk / role-based emails.
Total invalid, disposable, or fraudulent emails.
Per-email evaluation records.
Original email evaluated.
Quality score from 0 to 100.
Actionable decision.
allowchallengedenyRisk category.
lowmediumhighcriticalOrganization category.
businessconsumer_freeeducationgovernmentdisposableTrue if domain belongs to a commercial enterprise.
True if temporary/burner email provider.
Typo suggestion if domain was mistyped, else null.
SHA-256 canonical identity hash.
Sanitized public security flags.
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]"]}'{
"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."
}
]
}Score a domain on its own, without an email address
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
Your secret API key.
Must be `application/json`.
Query Parameters
Domain to evaluate via GET query parameter (alternative to POST JSON body).
Request Body (JSON)
The domain name to score, without a local part or `@`.
Response Attributes
Domain evaluated.
Domain risk score from 0 (dead, disposable, or unusable for mail) to 100 (established domain with working mail).
Risk-based policy recommendation: `allow`, `challenge`, or `deny`. It describes the domain only, not any mailbox on it.
allowchallengedenyCategorical risk assessment.
lowmediumhighcriticalShort explanation of the decision.
Domain risk flags (listed in the endpoint description). Empty array for a clean domain.
`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.
completepartialSuggested domain when the input looks like a typo of a known provider (e.g. `gmail.com` for `gmial.com`), else null.
Server-side evaluation time in milliseconds for this request; not an end-to-end API latency guarantee.
Domain reputation, registration age, and status.
Domain quality score (0-100).
Domain evaluated.
Original domain registration date (YYYY-MM-DD).
Unix epoch timestamp of registration.
Domain age in days, calculated at request time.
Domain infrastructure type.
disposablepublic_freecustom_corporategeneric_hostedTLD abuse reputation tier.
premiumstandardsuspiciousTrue if domain is NXDOMAIN, abandoned, or dropped.
True if domain is parked or a holding page.
Character length of the domain name.
Domain status.
activedeadparkedno_mxMail DNS for the domain. Unknown when `evidence` is `partial`.
True if domain has valid MX or fallback mail exchangers.
List of resolved mail exchanger hosts.
Detected email infrastructure vendor (e.g. Google Workspace, Microsoft 365).
True if SPF records are configured.
True if DMARC policy is published.
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"}'{
"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"
}
}Score a batch of domains
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
Your secret API key.
Must be `application/json`.
Optional compression header. Recommended for large batches.
Request Body (JSON)
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
Number of domains received in the batch.
Number of domains evaluated.
Total server-side processing duration in milliseconds for the batch.
Decision counts across the batch.
Domains with an `allow` decision.
Domains with a `challenge` decision.
Domains with a `deny` decision, including invalid entries.
Per-domain verdicts in submission order. Each equals the `/v1/domain` result for that domain without `domain_quality`, `dns`, and `evaluation_time_ms`.
Normalized domain (trimmed, lowercased, trailing dot removed), or the trimmed input for an invalid entry.
Domain risk score from 0 to 100.
Recommendation for the domain: `allow`, `challenge`, or `deny`.
allowchallengedenyCategorical risk assessment.
lowmediumhighcriticalShort explanation of the decision.
Domain risk flags (listed in the endpoint description). Empty array for a clean domain.
`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.
completepartialSuggested 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"]}'{
"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
}
]
}Parse raw SMTP error diagnostics into structured deliverability actions
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
Your secret API key.
Must be `application/json`.
Request Body (JSON)
The raw SMTP response line or error string returned by the receiving mailserver.
Optional recipient email address associated with the bounce event.
Response Attributes
Echo of the input diagnostic string.
Associated email address if provided in request.
Standard RFC deliverability classification.
hard_bounce_user_unknownsoft_bounce_mailbox_fullip_or_domain_blacklistedauthentication_failuretransient_network_timeoutRecommended handling of the supplied failure: review permanent suppression for `prune_permanent`, or retry policy for `retry_transient`.
prune_permanentretry_transientProbability [0.0 to 1.0] that this bounce is an unrecoverable hard bounce.
Confidence level of category classification.
Concrete engineering and deliverability guidance.
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]"}'{
"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
}Schemas & Models
Data structures and object definitions used in request bodies and response payloads.
CheckSingleRequest
Data schema model for CheckSingleRequest.
Attributes
The raw email address to score.
Optional format override in request body (`full` or `compact`).
Optional sparse field projection override in request body.
CheckSingleResponse
Data schema model for CheckSingleResponse.
Attributes
Original email address evaluated.
Extracted local part (username) before the @ symbol.
Extracted domain name after the @ symbol.
Deterministic quality score from 0 (fraudulent/dead) to 100 (high confidence legitimate).
Risk-based policy recommendation: `allow`, `challenge`, or `deny`. Review supporting signals; this is not proof of ownership, human identity, or delivery.
allowchallengedenyCategorical risk assessment.
lowmediumhighcriticalClean, actionable signup gatekeeper directive.
Server-side evaluation time in milliseconds for this request; not an end-to-end API latency guarantee.
Canonical identity deduplication object.
Canonical email (lowercase, stripped Gmail dots and +alias extensions).
SHA-256 cryptographic hash of normalized email for account deduplication and sybil attack blocking.
Base local part.
Canonical domain name.
Whether email contains plus-aliasing (e.g. [email protected]).
The extracted subaddress tag if present, else null.
Whether email contains dot stuffing patterns (e.g. [email protected]).
Domain and account classification.
Organizational account category.
businessconsumer_freeeducationgovernmentdisposableTrue if domain belongs to a commercial corporate organization.
True for consumer webmail (Gmail, Yahoo, Outlook, ProtonMail, etc.).
True if provider is a temporary or throwaway inbox service.
True for generic functional handles (admin@, support@, info@, billing@).
TLD abuse reputation tier.
premiumstandardsuspiciousRFC 5321 / 5322 syntax validation and auto-correction.
True if email conforms to RFC standards.
Did-you-mean suggestion for mistyped domains (e.g. `[email protected]` for `[email protected]`).
Local-part quality signals (sanitized production contract).
Quality score for the username component (0-100).
True if handle is a shared organizational role account.
True if subaddress delimiter detected.
True if dot stuffing detected.
Domain reputation and DomainLedger dynamic maturity.
Domain quality score (0-100).
Domain evaluated.
Original domain registration date (YYYY-MM-DD).
Unix epoch timestamp of registration.
Domain age in days calculated in real-time.
Domain infrastructure type.
disposablepublic_freecustom_corporategeneric_hostedTLD tier.
premiumstandardsuspiciousTrue if domain is NXDOMAIN, abandoned, or dropped.
True if domain is parked or holding page.
Character length of the domain name.
Domain status.
activedeadparkedno_mxLive DNS and mail server routing.
True if domain has valid MX or fallback mail exchangers.
List of resolved mail exchanger hosts.
Detected email infrastructure vendor (e.g. Google Workspace, Microsoft 365).
True if SPF records are configured.
True if DMARC policy is published.
DNS resolution status code.
Verdict on the domain part alone. Same values `/v1/domain` returns for this domain.
Domain risk score from 0 to 100.
Recommendation for the domain alone: `allow`, `challenge`, or `deny`.
allowchallengedenyCategorical risk assessment for the domain.
lowmediumhighcriticalShort explanation of the domain decision.
Domain risk flags (see `/v1/domain` for the list). Empty array for a clean domain.
`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.
completepartialSecurity exception and anomaly triggers (e.g. `SUSPICIOUS_HANDLE_PATTERN`, `DISPOSABLE_DOMAIN`, `NO_MX_RECORDS`). Empty array for clean addresses.
CheckBulkRequest
Data schema model for CheckBulkRequest.
Attributes
Array of email addresses to clean and score (up to 10,000 per request).
Format selector (batch always outputs compact result rows).
Optional field mask.
CheckBulkResponse
Data schema model for CheckBulkResponse.
Attributes
Total number of emails received in the batch.
Number of emails successfully evaluated.
Total server-side processing duration in milliseconds.
Aggregate classification counts across the batch.
Total high-confidence legitimate emails.
Total moderate-risk / role-based emails.
Total invalid, disposable, or fraudulent emails.
Per-email evaluation records.
Original email evaluated.
Quality score from 0 to 100.
Actionable decision.
allowchallengedenyRisk category.
lowmediumhighcriticalOrganization category.
businessconsumer_freeeducationgovernmentdisposableTrue if domain belongs to a commercial enterprise.
True if temporary/burner email provider.
Typo suggestion if domain was mistyped, else null.
SHA-256 canonical identity hash.
Sanitized public security flags.
Standardized gatekeeper policy recommendation.
DomainSingleRequest
Data schema model for DomainSingleRequest.
Attributes
The domain name to score, without a local part or `@`.
DomainSingleResponse
Data schema model for DomainSingleResponse.
Attributes
Domain evaluated.
Domain risk score from 0 (dead, disposable, or unusable for mail) to 100 (established domain with working mail).
Risk-based policy recommendation: `allow`, `challenge`, or `deny`. It describes the domain only, not any mailbox on it.
allowchallengedenyCategorical risk assessment.
lowmediumhighcriticalShort explanation of the decision.
Domain risk flags (listed in the endpoint description). Empty array for a clean domain.
`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.
completepartialSuggested domain when the input looks like a typo of a known provider (e.g. `gmail.com` for `gmial.com`), else null.
Server-side evaluation time in milliseconds for this request; not an end-to-end API latency guarantee.
Domain reputation, registration age, and status.
Domain quality score (0-100).
Domain evaluated.
Original domain registration date (YYYY-MM-DD).
Unix epoch timestamp of registration.
Domain age in days, calculated at request time.
Domain infrastructure type.
disposablepublic_freecustom_corporategeneric_hostedTLD abuse reputation tier.
premiumstandardsuspiciousTrue if domain is NXDOMAIN, abandoned, or dropped.
True if domain is parked or a holding page.
Character length of the domain name.
Domain status.
activedeadparkedno_mxMail DNS for the domain. Unknown when `evidence` is `partial`.
True if domain has valid MX or fallback mail exchangers.
List of resolved mail exchanger hosts.
Detected email infrastructure vendor (e.g. Google Workspace, Microsoft 365).
True if SPF records are configured.
True if DMARC policy is published.
DNS resolution status code.
DomainBulkRequest
Data schema model for DomainBulkRequest.
Attributes
Array of domains to score (1 to 10,000 per request). A raw JSON array of strings is also accepted as the whole body.
DomainBulkResponse
Data schema model for DomainBulkResponse.
Attributes
Number of domains received in the batch.
Number of domains evaluated.
Total server-side processing duration in milliseconds for the batch.
Decision counts across the batch.
Domains with an `allow` decision.
Domains with a `challenge` decision.
Domains with a `deny` decision, including invalid entries.
Per-domain verdicts in submission order. Each equals the `/v1/domain` result for that domain without `domain_quality`, `dns`, and `evaluation_time_ms`.
Normalized domain (trimmed, lowercased, trailing dot removed), or the trimmed input for an invalid entry.
Domain risk score from 0 to 100.
Recommendation for the domain: `allow`, `challenge`, or `deny`.
allowchallengedenyCategorical risk assessment.
lowmediumhighcriticalShort explanation of the decision.
Domain risk flags (listed in the endpoint description). Empty array for a clean domain.
`complete` when DNS was looked up. `partial` when it was not, so MX, SPF, and DMARC are unknown.
completepartialSuggested domain when the input looks like a typo of a known provider, else null.
BounceDiagnoseRequest
Data schema model for BounceDiagnoseRequest.
Attributes
The raw SMTP response line or error string returned by the receiving mailserver.
Optional recipient email address associated with the bounce event.
BounceDiagnoseResponse
Data schema model for BounceDiagnoseResponse.
Attributes
Echo of the input diagnostic string.
Associated email address if provided in request.
Standard RFC deliverability classification.
hard_bounce_user_unknownsoft_bounce_mailbox_fullip_or_domain_blacklistedauthentication_failuretransient_network_timeoutRecommended handling of the supplied failure: review permanent suppression for `prune_permanent`, or retry policy for `retry_transient`.
prune_permanentretry_transientProbability [0.0 to 1.0] that this bounce is an unrecoverable hard bounce.
Confidence level of category classification.
Concrete engineering and deliverability guidance.
Processing latency in milliseconds.
HealthResponse
Data schema model for HealthResponse.
Attributes
Cluster operational health status.
okdegradedEngine runtime identifier and major version.
Canonical API authority domain.
Primary email scoring route.
Verified throughput range per single HTTP connection.
Maximum allowable emails in a single bulk batch request.
Output format projections supported by the engine.
Syntax directive for bitmask sparse field projection.
Supported transparent stream compression algorithms.
Active heuristic and database engines in current deployment.
ErrorResponse
Data schema model for ErrorResponse.
Attributes
Standardized error message or machine-readable reason code.
Optional extended error explanation or remediation steps.
{
"error": "Invalid or revoked API key"
}