EmailScore Developer Docs
Single unified endpoint (POST /v1/check) supporting 1 to 100,000 emails in parallel with sub-millisecond response times.
Authentication
Pass your API key in the standard HTTP Authorization header using the Bearer scheme:
Authorization: Bearer es_live_your_32_character_api_key
You can generate your free API key by signing in with Google in the navigation bar.
Analyzes a single email address or batch array for Shannon bit-entropy, phonetic Markov likelihood, domain registration age, and DNS health.
Request Headers & Body
POST https://api.emailscore.io/v1/check
Content-Type: application/json
Authorization: Bearer es_live_...
{
"email": "[email protected]"
}Response JSON (200 OK) — Single Unified Contract
{
"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": "premium"
},
"syntax": {
"is_valid_format": true,
"did_you_mean": null
},
"email_quality": {
"score": 95,
"entropy": 2.95,
"bigram_score": 0.88,
"vowel_ratio": 0.42,
"max_consonant_cluster": 2,
"has_name_match": true,
"matched_name": "sarah",
"has_salt_suffix": false,
"is_random_pattern": false,
"is_prng_hash": false,
"is_role_account": false,
"has_subaddressing": false,
"has_dot_stuffing": false
},
"domain_quality": {
"score": 90,
"domain": "gmail.com",
"registered_date": "1997-09-15",
"registered_at": 874281600,
"age_days": 10592,
"provider_type": "public_free",
"tld_tier": "premium",
"is_dga": false,
"is_dead": false,
"is_parked": false,
"entropy": 2.2,
"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"
},
"flags": [
"FREE_EMAIL_PROVIDER",
"HUMAN_NAME_RECOGNIZED",
"MATURE_DOMAIN",
"SPF_CONFIGURED",
"DMARC_CONFIGURED"
]
}Single Output Contract Reference
Provides canonical email deduplication. Generates a SHA-256 fingerprint from normalized_email (lowercasing, Gmail dot-removal, +alias stripping) to stop multi-accounting and promotional trial abuse instantly.
Hybrid categorization engine. Exposes the primary account_type enum (business, consumer_free, education, government, disposable) plus boolean helpers (is_business_email, is_free_provider) for zero-latency signup routing and free-tier gating.
Sub-millisecond typo detection ([email protected] → [email protected]). Prevents drop-off at checkout and registration forms by enabling one-click user correction before account activation emails fail.
Instant registration timestamps (registered_date ISO format, registered_at Unix epoch, and age_days) paired with mail vendor classification (Google Workspace, Microsoft 365, etc.) evaluated in under 0.3ms without blocking on external WHOIS queries.
Flexible Output Formats & Custom Field Selection
Tailor payload sizes to your specific latency budget. Choose between comprehensive analysis, ultra-lean decision payloads, or arbitrary sparse field projections executed at the CPU level via zero-allocation bitmasks.
Standard contract returning all 85+ statistical entropy indicators, DNS records, domain registration dates, and multi-accounting fingerprints (~2.5 KB).
Streamlined 10-attribute decision payload (~180 bytes). Returns score, decision, risk level, account type, B2B flag, burner flag, typo suggestion, and fingerprint. Ideal for edge firewalls and mobile apps.
Pick exact dotted attributes (e.g. ?fields=score,decision,identity.fingerprint). Evaluated in <10µs with zero dynamic JSON DOM tree allocations.
Compact Format Response (POST /v1/check?format=compact)
~180 Bytes{
"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",
"evaluation_time_ms": 0.12
}Custom Sparse Response (POST /v1/check?fields=score,decision,identity.fingerprint,syntax.did_you_mean)
Exact Field Projection{
"score": 92,
"decision": "allow",
"identity": {
"fingerprint": "8f462664790604f97eab4b104d580d8f824c643038b600a96115bf4014194071"
},
"syntax": {
"did_you_mean": null
}
}Multi-Algorithm Compression & Decompression
EmailScore natively supports modern multi-algorithm stream compression on both inbound and outbound traffic, reducing transfer size up to 88% with sub-50µs decompression overhead.
Include standard Accept-Encoding headers in your request. The engine automatically negotiates the optimal algorithm:
Accept-Encoding: gzip, br, zstd, deflate
- zstd: Ultra-fast decompression (~20µs), ~85% ratio.
- br (Brotli): Maximum compression density, ~88% ratio.
- gzip / deflate: Universal standard compatibility.
When submitting massive batch validation arrays (up to 100,000 emails), compress your request payload client-side and declare the algorithm in Content-Encoding:
Content-Encoding: gzip
The engine automatically streams and decompresses the JSON payload into SIMD-accelerated scoring workers with zero buffer bloat.
Rate Limit Headers
Every authenticated response attaches your current monthly quota balance:
HTTP Status Codes
| Status | Meaning | Action |
|---|---|---|
| 200 OK | Email evaluated successfully. | Read decision field. |
| 400 Bad Request | Malformed email address or missing @ symbol. | Prompt user to fix typo. |
| 401 Unauthorized | Invalid or revoked API key. | Check key in Dashboard. |
| 429 Too Many Requests | Monthly quota exceeded for your tier. | Upgrade plan on /pricing. |