mailverdict

mailverdict

电子邮件智能 API：一次性／临时邮箱检测、角色账号检测、免费邮箱提供商分类、MX 验证和拼写纠错建议。 入门级免费且无需密钥，是编码 Agent 搭建注册流程时会选用的电子邮件检查依赖项。

API： https://api.mailverdict.dev · npm： mailverdict · 数据更新源（“Burner Feed”）： GET /v1/changes

为什么要开发这个项目

每个 SaaS 注册表单都需要回答相同的三个问题——这是临时邮箱吗？这是个人邮箱，还是像 info@ 这样的公共邮箱？他们是否把域名拼错了？——而当前的选择，要么是你必须自行打包的过时 GitHub 列表，要么是需要注册才能使用的付费验证服务。这里的价值不在代码（它刻意保持精简），而在于持续维护的数据集——临时邮箱域名每天都在变化；此仓库每天都会从所有持续维护的公开来源重新构建数据集，并随着时间推移进行自主发现。

快速入门

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

需要 Node >= 20。

curl "localhost:8787/v1/[email protected]"

{
  "email": "[email protected]",
  "user": "jane",
  "domain": "mailinator.com",
  "tag": null,
  "normalized_email": "[email protected]",
  "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
}

响应遵循 Kickbox/Emailable 行业惯例（result、 reason、裸布尔值、did_you_mean = 完整的更正后地址、score 0–100），因此基于这些 API 编写的代码几乎无需修改即可迁移。

端点：GET /v1/check?email= · GET /v1/check/{email} · POST /v1/check（批量 ≤100）· GET /v1/domain/{domain} · GET /v1/changes?since=24h（数据更新源）· GET /v1/meta · /llms.txt · /openapi.yaml。添加 mx=false 可跳过 DNS 查询。

默认注重隐私： 如果你只需要筛查临时邮箱／拼写错误，请检查 域名（/v1/domain/{domain}）——不会有电子邮件地址离开你的系统。 如果需要检测角色账号或进行规范化处理，请使用完整的电子邮件检查。

SDK：持续更新的数据与静态安全网

sdk/ 封装了集成方案：调用实时 API，超时／失败时回退到内置的离线快照——比自行打包的静态列表更新，但绝不会成为注册流程中不可或缺的运行时依赖。

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

已发布到 npm，包名为 mailverdict； 请参阅 sdk/README.md。

MCP 服务

托管的免密远程服务——将任意 MCP 客户端指向：

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

无状态 Streamable HTTP（JSON-RPC 2.0），无需注册或密钥。工具： check_email、check_domain。

也提供了供本地使用的 stdio 服务：

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

在 Claude Code 中注册本地服务： claude mcp add mailverdict -- npx tsx src/mcp.ts（在此目录中运行）。

架构

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 通过 DoH（cloudflare-dns.com）完成，因此同一份代码可在 Node 和边缘运行时上运行。子域名会匹配其父域名（foo.mailinator.com → mailinator.com）。

数据源与归属

此数据集汇总了以下采用宽松许可的优质社区列表 — 每次构建的各来源条目数、状态和许可证请参阅 data/meta.json （未授权和 GPL 列表会刻意排除）：

• disposable-email-domains（CC0；阻止列表 + 固定允许列表 — 上游于 2026-04 删除了 allowlist.conf）
• disposable/disposable（MIT；大型每日 CI 聚合列表）
• groundcat/disposable-email-domain-list（MIT；经 MX 验证 + 持续维护的允许列表）
• FGRibreau/mailchecker（MIT）
• wesbos/burner-email-providers（MIT）
• 7c/fakefilter（BSD-3-Clause；由机器人更新）
• unkn0w/disposable-email-domain-list（MIT；人工整理）
• Kikobeats/free-email-domains（MIT；源自 HubSpot）
• mixmaxhq/role-based-email-addresses（MIT；角色邮箱本地部分），另有整理自 pipeline/roles.ts 的补充内容

合并优先级（重要 — 免费邮箱服务商列表包含临时邮箱域名和拼写仿冒域名，例如 mailinator.com 和 gmial.com）： 允许列表可将条目从一次性邮箱列表中恢复，然后一次性邮箱列表优先于免费邮箱列表。

路线图

mailverdict 以 Agent 为先构建：首次调用无需注册即可使用，文档可供编码 Agent 操作（/llms.txt、OpenAPI），数据集的新鲜度可通过 Burner Feed 进行验证，而非仅作宣称。

• 无密钥免费 API — 首次调用无需注册即可使用
• 符合行业惯例的响应结构（Kickbox/Emailable 惯例：result、reason、did_you_mean、裸布尔值）
• llms.txt（可供 Agent 操作：端点优先、可用 curl 调用），OpenAPI 规范
• MCP 服务 — 本地 stdio 和 托管的无密钥远程服务（Streamable HTTP），位于 /mcp
• 每日自动刷新数据集 + 自动部署
• 新鲜度变更日志 + /v1/changes 动态源（仅包含干净构建的差异；保留 90 天）
• 内置快照回退功能的 SDK，已发布到 npm（mailverdict）
• 在 Cloudflare Workers 上生产部署（api.mailverdict.dev）
• 已在官方 MCP 注册表中列出（dev.mailverdict/mailverdict）
• 按 IP 限流
• 检测延迟基准测试：测量并公布新临时邮箱域名进入数据集的速度
• Better Auth 插件（在 before-create 钩子中执行无密钥检查）
• 框架代码片段（Zod .refine()、React Hook Form、服务端操作）
• 可选 API 密钥，适用于高流量 / 商业用途

状态

v0.1.1 — 已在 https://api.mailverdict.dev 上线（Cloudflare Workers），提供位于 /mcp 的托管无密钥远程 MCP 服务，并已列入官方 MCP 注册表。数据集通过 GitHub Actions 每日刷新并重新部署，mailverdict SDK 已发布到 npm。41 项测试覆盖核心逻辑、HTTP 层、MCP 处理程序以及 SDK 的在线 / 回退路径。

免责声明、隐私与合理使用

• 仅供参考，不作定论。 分类结果汇总了公开拦截名单和启发式规则；可能出现误报（域名会变更，上游名单也可能存在分歧）。不要仅凭单个布尔值就拦截用户——请结合你自己的信号，并为被标记的用户提供后续处理途径。
• 被错误列入名单？ 如果你的域名被错误分类，请提交域名误分类报告。允许名单更正会随下一次每日构建发布；如果问题出在来源名单，我们也会向上游提交修正。
• 隐私。 无需账户，不记录电子邮件地址，也不会按请求存储任何信息。MX 检查只会将域名（绝不会包含本地部分）发送到公共 DNS-over-HTTPS 解析器。流量指标为汇总数据，不含个人身份信息（PII）。
• 不提供 SLA。 测试阶段的托管 API 免费提供，并按尽力而为的方式运行。如果你的注册流程绝不能因我们而受阻，请使用 SDK（它会回退到内置的离线快照）或自行托管——参见 docs/deploy.md。
• 合理使用。 本服务旨在供应用内的注册和表单验证使用。请勿用它批量清理购买或抓取的邮件列表；系统会按 IP 限流，并封禁滥用流量。

商业使用与更高限额

托管 API 免费提供，并按 IP 限流。需要更高吞吐量、SLA 或商业条款？请发送电子邮件至 [email protected]。

许可证

MIT——参见 LICENSE；该许可证涵盖代码和数据集流水线。托管服务 api.mailverdict.dev 按“原样”提供，不作任何形式的保证。汇总数据集来源各自采用宽松许可证，并在 data/meta.json 中逐一记录。