Verify before
you send.

01Overview

A privacy-preserving alternative to ZeroBounce / NeverBounce. Runs on your own infrastructure, never sends mail, and exposes one clean HTTP API.

Each address goes through a five-stage pipeline. The result is a single flat JSON object — every field at the top level next to is_reachable, no nested syntax / mx / smtp / misc / debug sub-objects.

Verdicts

safe mailbox exists and looks deliverable. risky deliverable but flagged (disposable, role, catch-all, full inbox). invalid syntax / domain / mailbox failure. unknown network or provider issue — try again later.

License

Dual-licensed: AGPL-3.0 for open source use, or a commercial license from Autter for proprietary software. See LICENSE.md.

02Quickstart

Run it locally

git clone https://github.com/sagnik11/email-checker.git
cd email-checker
npm install
npm run dev
# server now listening on http://127.0.0.1:8080

Validate an address

curl -X POST http://127.0.0.1:8080/v1/check_email \
  -H 'content-type: application/json' \
  -d '{"to_email":"someone@gmail.com"}'

const res = await fetch("http://127.0.0.1:8080/v1/check_email", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ to_email: "someone@gmail.com" }),
});
const data = await res.json();
console.log(data.is_reachable); // "safe" | "risky" | "invalid" | "unknown"

import requests

resp = requests.post(
    "http://127.0.0.1:8080/v1/check_email",
    json={"to_email": "someone@gmail.com"},
    timeout=30,
)
print(resp.json()["is_reachable"])

Submit a bulk job

Bulk mode requires worker.enable = true, Postgres, and RabbitMQ. See Self-hosting.

# 1. submit
curl -X POST http://127.0.0.1:8080/v1/bulk \
  -H 'content-type: application/json' \
  -H 'x-api-secret: YOUR_SECRET' \
  -d '{"input":["alice@example.com","bob@example.com"]}'
# → { "job_id": 42 }

# 2. poll progress
curl http://127.0.0.1:8080/v1/bulk/42

# 3. download results when complete
curl 'http://127.0.0.1:8080/v1/bulk/42/results?format=csv' -o results.csv

03API reference

Seven endpoints. /health, /ready, /version, and / are unauthenticated. All /v1/* endpoints require an x-api-secret header when header_secret is configured (see Authentication).

{ "ok": true }

{
  "ok": true,
  "dependencies": {
    "postgres": { "ok": true },
    "rabbitmq": { "ok": true, "queue": "check_email" }
  }
}

{
  "ok": false,
  "dependencies": {
    "postgres": { "ok": false, "error": "..." },
    "rabbitmq": { "ok": true, "queue": "check_email" }
  }
}

{ "version": "0.2.0", "smtp_port": 25 }

{
  "input": "someone@gmail.com",
  "is_reachable": "safe",

  "email_address": "someone@gmail.com",
  "email_username": "someone",
  "email_domain": "gmail.com",
  "normalized_email": "someone@gmail.com",
  "is_valid_syntax": true,
  "syntax_suggestion": null,

  "is_disposable_email": false,
  "is_role_account": false,
  "is_b2c_provider": true,
  "gravatar_url": null,
  "has_been_pwned": null,

  "mx_accepts_mail": true,
  "mx_records": ["gmail-smtp-in.l.google.com"],
  "mx_preferred_host": "gmail-smtp-in.l.google.com",
  "mx_preferred_priority": 5,
  "mx_lookup_error_type": null,
  "mx_lookup_error_message": null,

  "smtp_can_connect": true,
  "smtp_has_full_inbox": false,
  "smtp_is_catch_all": false,
  "smtp_is_deliverable": true,
  "smtp_is_disabled_account": false,
  "smtp_error_type": null,
  "smtp_error_message": null,
  "smtp_error_description": null,

  "backend_name": "backend-dev",
  "check_started_at": "2026-01-01T00:00:00.000Z",
  "check_completed_at": "2026-01-01T00:00:01.200Z",
  "check_duration_ms": 1200,
  "check_duration_seconds": 1,
  "check_duration_nanos": 200000000,
  "verification_method_type": "smtp",
  "verification_method_host": "gmail-smtp-in.l.google.com",
  "verification_method_smtp_port": 25,
  "verification_method_provider": "gmail",
  "verification_method_chosen": "smtp",
  "verification_method_requested": null,
  "verification_method_fallback": null
}

curl -N "http://127.0.0.1:8080/v1/check_email/stream?email=foo@example.com"

const url = new URL("/v1/check_email/stream", window.location.origin);
url.searchParams.set("email", "foo@example.com");

const es = new EventSource(url);
es.addEventListener("syntax",       (e) => console.log("syntax",       JSON.parse(e.data)));
es.addEventListener("mx",           (e) => console.log("mx",           JSON.parse(e.data)));
es.addEventListener("smtp_connect", (e) => console.log("smtp_connect", JSON.parse(e.data)));
es.addEventListener("smtp_rcpt",    (e) => console.log("smtp_rcpt",    JSON.parse(e.data)));
es.addEventListener("done",  (e) => { console.log("result", JSON.parse(e.data)); es.close(); });
es.addEventListener("error", (e) => { console.error(e); es.close(); });

{ "job_id": 42 }

{
  "job_id": 42,
  "created_at": "2026-01-01T00:00:00.000Z",
  "finished_at": null,
  "total_records": 1000,
  "total_processed": 532,
  "summary": {
    "total_safe": 410,
    "total_risky": 64,
    "total_invalid": 51,
    "total_unknown": 7
  },
  "job_status": "running"
}

{ "results": [ /* CheckEmailResponse, ... */ ] }

04Schemas

Mirrored from openapi.yaml. Use the YAML spec to generate clients (Swagger UI, Redoc, openapi-generator, etc.).

CheckEmailResponse

Verdict

Syntax

Misc

MX

SMTP

Debug / metadata

ProxyConfig

SOCKS5 tunnel for the SMTP connection.

WebhookConfig

Per-result webhook delivered by the worker for each address in a bulk job. POSTs JSON { result: CheckEmailResponse, extra: any } to on_each_email.url with the merged headers.

{
  "webhook": {
    "on_each_email": {
      "url": "https://your-app/hooks/email-result",
      "headers": { "authorization": "Bearer ..." },
      "extra":   { "list_id": "q4-cleanup" }
    }
  }
}

05Authentication

Send the configured secret with every protected request:

x-api-secret: YOUR_SECRET

When header_secret is unset, all routes are open. When it's set, missing or wrong values return 400. /health, /ready, /version, and / are always unauthenticated.

06CORS

The default is * (all origins allowed). Restrict it for production:

EMAIL_CHECKER__CORS__ORIGINS=https://app.example.com,https://www.app.example.com

Comma-separated string or JSON array. The server sends Access-Control-Allow-Headers: content-type, x-api-secret, authorization and a 24-hour preflight cache.

07Configuration

Loaded by src/config.ts in this priority order (later overrides earlier):

1. Built-in defaults
2. backend_config.toml (or path passed via --config)
3. Double-underscore env vars: EMAIL_CHECKER__<SECTION>__<KEY>
4. PORT env var → http_port fallback (Heroku / Fly / Render)

Common settings

Throttling

Worker mode

Single-underscore aliases

These bypass the TOML overlay and are read directly by the checker. Useful for cloud providers that pass env vars through a flat namespace.

08Deployment

docker build -t email-validator .
docker run -p 8080:8080 \
  -e EMAIL_CHECKER__HTTP_HOST=0.0.0.0 \
  -e EMAIL_CHECKER__HEADER_SECRET=YOUR_SECRET \
  email-validator

fly launch --no-deploy
fly secrets set \
  EMAIL_CHECKER__HEADER_SECRET=YOUR_SECRET \
  EMAIL_CHECKER__ALLOW_BROWSER_WITHOUT_SECRET=true
fly deploy

npm install
npm run build
EMAIL_CHECKER__HTTP_HOST=0.0.0.0 \
EMAIL_CHECKER__HEADER_SECRET=YOUR_SECRET \
npm start

09Self-hosting

Worker mode

Async bulk processing requires a worker, RabbitMQ, and Postgres. The API and worker can run as a single inline process or as separate scaled processes.

Inline (single process)

# with worker.enable = true in backend_config.toml
email-validator serve --config ./backend_config.toml

Separate processes (recommended for production)

# API
EMAIL_CHECKER__WORKER__ENABLE=false email-validator serve

# Worker (any number of replicas)
email-validator worker --config ./backend_config.toml

Workers consume from the check_email RabbitMQ queue with prefetch = worker.rabbitmq.concurrency (default 5). Single-shot RPC checks have higher priority than bulk job tasks. Transient SMTP failures (unknown) are requeued once before being persisted.

Postgres schema

src/storage/postgres.ts auto-migrates on startup. Two tables:

• v1_bulk_job — id, created_at, total_records.
• v1_task_result — id, job_id, created_at, result (jsonb), extra (jsonb), error.

Aggregate progress is computed on the fly — no separate counters to keep in sync.

RabbitMQ

• Queue: check_email (durable, priority-aware).
• Single-shot RPC pattern uses an exclusive reply queue per request.
• Concurrency knob: worker.rabbitmq.concurrency.

SOCKS5 proxy

When the host blocks port 25 outbound (most clouds do), route SMTP through a SOCKS5 proxy:

{
  "to_email": "someone@example.com",
  "proxy": {
    "host": "proxy.local",
    "port": 1080,
    "username": "user",
    "password": "pass",
    "timeout_ms": 20000
  },
  "smtp_port": 25
}

Or use a different port server-side: EMAIL_CHECKER_SMTP_PORT=587.

Observability

• Logs are JSON-lines on stdout. Set SMTP_DEBUG=true for verbose SMTP transaction logs.
• Liveness probe: GET /health; readiness probe: GET /ready.
• Queue depth: monitor RabbitMQ's management UI / Prometheus exporter.
• Job status: query v1_task_result directly or poll GET /v1/bulk/{id}.

10Architecture

Verification pipeline

Orchestrated in src/checker/checkEmail.ts. Each stage may short-circuit the rest.

1. Syntax — src/checker/syntax.ts

• RFC 5321/5322 validation via isemail.
• Gmail / Googlemail normalization: dots stripped, +alias removed; canonical form goes into normalized_email.
• Typo suggestions via Levenshtein distance < 3 against gmail.com, yahoo.com, outlook.com, hotmail.com, protonmail.com, icloud.com, yandex.com.

2. Misc — src/checker/misc.ts

• Disposable: union of mailchecker + disposable-email-domains (~96k entries) + a small hardcoded override set. Domain and parent suffixes both checked.
• Role: lowercased local part looked up in src/data/roles.txt (944 entries).
• B2C: domain looked up in src/data/b2c.txt (~96,600 entries).
• Gravatar: optional. MD5 hash + ?d=404 probe, 6 s timeout.
• HIBP: optional. v3 API, 10 s timeout. Returns true / false / null on error.

3. MX — src/checker/mx.ts

• node:dns/promises resolveMx(); sorted by priority ascending.
• Soft DNS errors (ENODATA, ENOTFOUND, NXDOMAIN, SERVFAIL) yield accepts_mail: false and invalid.
• Hard DNS errors throw → result becomes unknown.

4. SMTP — src/checker/smtp.ts · smtpParser.ts · provider.ts

• Provider detected from MX hostname: gmail, yahoo, hotmailb2c, hotmailb2b, proofpoint, mimecast, everything_else.
• TCP socket (or SOCKS5 tunnel). Port 465 → TLS automatically.
• Sequence: 220 greeting → EHLO → MAIL FROM → optional random RCPT (catch-all probe) → real RCPT → QUIT.
• Errors classified by smtpParser.ts: invalid mailbox, full inbox, disabled account, blacklisted IP, needs reverse DNS.
• Retry policy: configurable retries (default 1) on unclassified errors.

5. Reachability — calculateReachable()

Evaluated in this order:

Syntax failure short-circuits to invalid before the scoring matrix runs.

SMTP rules engine

src/data/rules.json stores per-domain and per-MX overrides applied in src/checker/rules.ts:

• SkipCatchAll — skip the random-address probe (Gmail, Hotmail, Yahoo always accept random RCPTs and would otherwise look catch-all).
• SmtpTimeout45s — bump the SMTP timeout to ≥ 45 s for slow / greylisting servers.

Repository layout

src/
  checker/   pipeline (syntax, misc, mx, smtp, scoring, rules, provider)
  http/      Express routes + auth + CORS
  worker/    RabbitMQ queue, consumer loop, task service
  storage/   storage abstraction + Postgres impl (auto-migration)
  data/      roles.txt, b2c.txt, rules.json (loaded as in-memory Sets)
  config.ts  TOML + env precedence
  runtime.ts wires config + storage + throttle + rabbit
  server.ts  HTTP entrypoint
bin/email-validator.ts   CLI (serve | worker | check)
api/index.ts             Vercel wrapper
public/                  static assets (web UI, docs, openapi.yaml)
test/                    node:test suite

11Contributing

Patches, bug reports, and feature requests welcome. Full guide: CONTRIBUTING.md.

git clone https://github.com/sagnik11/email-checker.git
cd email-checker
npm install
npm run dev      # tsx-based dev server
npm test         # node:test runner

Tests live in test/ and cover syntax, SMTP parser, reachability scoring, config loading, and throttling. New features should land with tests where practical.

12License

AGPL-3.0-or-later for open source use, or a commercial license from Autter Pte. Ltd. for proprietary software. See LICENSE / LICENSE.md.