Hermes

Documentation

Validate email addresses in real-time with a single API call. Create a free account to get your API key.

Quick Start

Authenticate with your API key via Authorization: Bearer <key> or x-api-key header.

curl -X POST https://hermes.leutsch.dev/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "checkSmtp": true}'

Endpoints

POST /v1/validateValidate a single email
POST /api/v1/validateSame endpoint (prefixed)
POST /api/v1/batchPro
Validate up to 100 emails

Request Body

FieldTypeDefaultDescription
emailstring—Email address to validate (required)
checkMxbooleantrueCheck MX records for the domain
checkSmtpbooleanfalseVerify mailbox via SMTP (Starter+)
checkDisposablebooleantrueCheck against disposable blocklist

For batch validation, send emails: string[] instead of email (max 100).

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

Fields gated by plan show checked: false on lower plans. Upgrade to unlock full results.

syntaxAll
RFC-compliant email format validation
mxAll
DNS MX record lookup with A record fallback
disposableAll
5,200+ disposable domain blocklist
smtpStarter+
Live SMTP mailbox verification
roleStarter+
Role-based address detection (admin@, info@, ...)
freeProviderStarter+
Free email provider detection (Gmail, Yahoo, ...)
subAddressStarter+
Subaddress/plus-addressing detection (user+tag@)
highRiskTldStarter+
High-risk TLD flagging (.tk, .xyz, .top, ...)
deliverabilityStarter+
Deliverability status (deliverable / risky / undeliverable)
catchAllPro
Catch-all domain detection
spfPro
SPF DNS record validation
dmarcPro
DMARC DNS record and policy check
typoPro
Domain typo suggestions (gmial.com → gmail.com)

Error Responses

400Invalid JSON body or missing email
401Invalid or missing API key
403Feature not available on your plan / request limit reached
429Rate limit exceeded