mailverdict

Email intelligence API: disposable/burner detection, role-account detection, free-provider classification, MX validation, and typo suggestions. Keyless and free at the entry tier, built to be the email-check dependency that coding agents reach for when they scaffold a signup flow.

API: https://api.mailverdict.dev · npm: mailverdict · Freshness feed ("Burner Feed"): GET /v1/changes

Why this exists

Every SaaS signup form needs the same three answers — is this a burner? is this a person or a mailbox like info@? did they typo their domain? — and the current options are stale GitHub lists you have to vendor yourself or paid validators gated behind signup. The value here is not the code (it's small on purpose): it's the maintained dataset — burner domains churn daily, and this repo rebuilds its dataset from every maintained public source on a daily schedule, plus its own discovery over time.

Quickstart

npm install
npm run build:data   # fetch + merge upstream lists into data/dataset.json
npm test
npm run dev          # http://localhost:8787

Requires Node >= 20.

curl "localhost:8787/v1/check?email=jane@mailinator.com"

{
  "email": "jane@mailinator.com",
  "user": "jane",
  "domain": "mailinator.com",
  "tag": null,
  "normalized_email": "jane@mailinator.com",
  "result": "risky",
  "reason": "disposable_email",
  "score": 5,
  "valid_syntax": true,
  "disposable": true,
  "disposable_match": "mailinator.com",
  "role": false,
  "free": false,
  "mx_found": true,
  "mx_records": ["mail2.mailinator.com"],
  "did_you_mean": null,
  "accept_all": null
}

Response follows the Kickbox/Emailable industry convention (result, reason, bare booleans, did_you_mean = full corrected address, score 0–100) so code written against those APIs ports with near-zero edits.

Endpoints: GET /v1/check?email= · GET /v1/check/{email} · POST /v1/check (batch ≤100) · GET /v1/domain/{domain} · GET /v1/changes?since=24h (freshness feed) · GET /v1/meta · /llms.txt · /openapi.yaml. Add mx=false to skip the DNS lookup.

Privacy-conscious default: if you only need burner/typo screening, check the domain (/v1/domain/{domain}) — no email address leaves your system. Use the full email check when you need role detection or normalization.

SDK: living data with a static safety net

sdk/ packages the integration story: call the live API, fall back to a bundled offline snapshot on timeout/failure — fresher than a vendored static list, but never a hard runtime dependency in your signup path.

import { createClient } from 'mailverdict'
const check = await createClient().checkEmail(input)
if (check.disposable) reject()          // check.source: 'live' | 'snapshot'

Published on npm as mailverdict; see sdk/README.md.

MCP server

Hosted, keyless remote server — point any MCP client at:

POST https://api.mailverdict.dev/mcp

Stateless Streamable HTTP (JSON-RPC 2.0), no signup or key. Tools: check_email, check_domain.

A stdio server also ships for local use:

npm run mcp   # stdio transport; tools: check_email, check_domain

Register the local one in Claude Code: claude mcp add mailverdict -- npx tsx src/mcp.ts (run from this directory).

Architecture

pipeline/build.ts     daily: fetch upstream lists -> merge/dedupe -> apply
                      allowlist -> data/dataset.json + data/meta.json
src/lib/*             pure logic: parse, classify, suggest, MX-over-DoH
src/app.ts            Hono app (runtime-agnostic)
src/server.ts         Node entry (self-hosting)
src/worker.ts         Cloudflare Workers entry (production: api.mailverdict.dev)
src/mcp.ts            MCP stdio server for coding agents
.github/workflows/    daily dataset refresh + auto-commit

DNS is done over DoH (cloudflare-dns.com) so the same code runs on N

... View full README on GitHub