Documentation
Validate email addresses in real-time with a single API call. Create an account to get an API key.
Quick Start
Authenticate with Authorization: Bearer <key> or x-api-key header.
curl -X POST https://hermes.leutsch.dev/api/v1/validate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "checkSmtp": true}'
Endpoints
POST /api/v1/validate— Validate a single emailPOST /api/v1/batch— Pro tier; validates up to 100 emails
Request Body
| Field | Type | Default | Description |
|---|---|---|---|
| string | — | Email address to validate (required) | |
| checkMx | boolean | true | Check MX records for the domain |
| checkSmtp | boolean | false | Verify mailbox via SMTP (Starter+) |
| checkDisposable | boolean | true | Check against disposable blocklist |
For batch requests, send emails: string[] instead (max 100 items).
Response Format
{
"email": "user@example.com",
"valid": true,
"score": 0.95,
"deliverability": "deliverable",
"syntax": { "valid": true },
"mx": {
"checked": true,
"records": ["alt1.gmail-smtp-in.l.google.com", "..."],
"valid": true
},
"smtp": { "checked": true, "valid": true, "message": "Email accepted" },
"disposable": { "checked": true, "isDisposable": false },
"catchAll": { "checked": true, "isCatchAll": false },
"role": { "checked": true, "isRole": false },
"freeProvider": { "checked": true, "isFree": true },
"typo": { "checked": true, "hasSuggestion": false },
"subAddress": { "checked": true, "hasSubAddress": false },
"spf": { "checked": true, "hasRecord": true, "record": "v=spf1 include:_spf.google.com ~all" },
"dmarc": { "checked": true, "hasRecord": true, "policy": "reject" },
"highRiskTld": { "checked": true, "isHighRisk": false },
"details": {
"localPart": "user",
"domain": "example.com",
"mxPreferences": [5, 10, 20]
}
}
Validation Checks
Plan-gated features display checked: false on lower tiers.
| Check | Plan | Purpose |
|---|---|---|
| syntax | All | RFC-compliant email format validation |
| mx | All | DNS MX record lookup with A record fallback |
| disposable | All | 5,200+ disposable domain blocklist |
| smtp | Starter+ | Live SMTP mailbox verification |
| role | Starter+ | Role-based address detection (admin@, info@, ...) |
| freeProvider | Starter+ | Free email provider detection (Gmail, Yahoo, ...) |
| subAddress | Starter+ | Subaddress/plus-addressing detection (user+tag@) |
| highRiskTld | Starter+ | High-risk TLD flagging (.tk, .xyz, .top, ...) |
| deliverability | Starter+ | Deliverability status (deliverable / risky / undeliverable) |
| catchAll | Pro | Catch-all domain detection |
| spf | Pro | SPF DNS record validation |
| dmarc | Pro | DMARC DNS record and policy check |
| typo | Pro | Domain typo suggestions (gmial.com → gmail.com) |
Error Responses
| Code | Meaning |
|---|---|
| 400 | Invalid JSON body or missing email |
| 401 | Invalid or missing API key |
| 403 | Feature not available on plan / request limit reached |
| 429 | Rate limit exceeded |