Hermes
Get started

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 email
  • POST /api/v1/batch — Pro tier; validates up to 100 emails

Request Body

Field Type Default Description
email 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

WordPress Plugin

The Hermes Email Validation plugin checks email fields in Contact Form 7, WPForms, Gravity Forms, Elementor Pro Forms and Ninja Forms when a form is submitted. No code needed.

  1. Download the plugin ZIP in your dashboard under Integrations.
  2. In WordPress, go to Plugins → Add New Plugin → Upload Plugin and activate it.
  3. Create an API key and paste it under Settings → Hermes.

If Hermes cannot be reached, forms are always accepted. Results are cached, so the same address only uses one validation per week.