电子邮件验证 API 文档

应用程序接口状态

入门

所有 API 请求都需要使用 API 密钥进行验证。您可以在仪表板中找到您的 API 密钥。

标题"x-api-key: your-api-key"

单一验证

验证单个电子邮件地址或域的有效性、一次性状态、隐私服务和可送达性。

终点

GET /v1/verify

参数

名称	类型	需要	说明
input	string	是	要验证的电子邮件地址或域名（如 [email protected] 或 example.com）

响应字段

现场	说明
valid	表示电子邮件格式是否正确
block	表示是否应阻止电子邮件（如果一次性、隐私、applePrivateEmail、可送达或 catch_all 为 true，则为 true）。
disposable	确定电子邮件地址是临时电子邮件地址还是一次性电子邮件地址
privacy	确定邮件服务器是否使用电子邮件别名或转发器
applePrivateEmail	表示该电子邮件是否为 Apple 专用电子邮件地址
deliverable	检查邮箱是否存在并能接收邮件
domain	电子邮件地址的域名部分
email_address	电子邮件地址
catch_all	表示网域是否有接收所有电子邮件的配置，该配置接受所有收到的电子邮件，无论收件人地址如何
mx_found	表示域名是否有有效的邮件服务器（MX 记录）
remaining_credits	账户中剩余的 API 点数

黑名单/白名单：只有 block 字段反映列表成员身份。黑名单 → block：true；白名单 → block：false；不在白名单中（启用时） → block：true。不要使用有效来决定是否根据列表进行屏蔽。

答复示例

{
  "valid": true,
  "block": false,
  "disposable": false,
  "privacy": false,
  "applePrivateEmail": false,
  "deliverable": true,
  "domain": "example.com",
  "email_address": "[email protected]",
  "catch_all": false,
  "mx_found": true,
  "error": null,
  "remaining_credits": 99
}

代码示例

curl "https://api.verify-email.app/v1/[email protected]" \
  -H "X-API-Key: your-api-key"

试试看

API 密钥

您需要一个 API 密钥来测试端点。

电子邮件地址或域名

试试看

批量验证

在一次请求中验证多个电子邮件地址或域（最多 100 项）。

终点

POST /v1/verify/batch

参数

名称	类型	需要	说明
inputs	array of strings	是	要验证的电子邮件地址或域阵列

代码示例

curl -X POST "https://api.verify-email.app/v1/verify/batch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "inputs": [
      "[email protected]",
      "[email protected]"
    ]
  }'

试试看

API 密钥

您需要一个 API 密钥来测试端点。

电子邮件地址或域名

尝试使用不同的域名：

仅可交付的检查

使用 MX 和 SMTP 验证快速检查电子邮件的可送达性，无需调用外部 API。只返回与送达性相关的字段，以加快响应速度。

终点

GET /v1/verify/deliverable

参数

名称	类型	需要	说明
input	string	是	用于检查可送达性的电子邮件地址（如 [email protected]）。此端点不支持仅域输入。

响应字段

现场	说明
valid	表示电子邮件格式是否正确
deliverable	检查邮箱是否存在并能接收邮件
mx_found	表示域名是否有有效的邮件服务器（MX 记录）
catch_all	表示网域是否有接收所有电子邮件的配置，该配置接受所有收到的电子邮件，无论收件人地址如何
email_address	电子邮件地址
remaining_credits	账户中剩余的 API 点数

答复示例

{
  "valid": true,
  "deliverable": true,
  "mx_found": true,
  "catch_all": false,
  "email_address": "[email protected]",
  "remaining_credits": 99
}

代码示例

curl "https://api.verify-email.app/v1/verify/[email protected]" \
  -H "X-API-Key: your-api-key"

试试看

API 密钥

您需要一个 API 密钥来测试端点。

电子邮件地址或域名

试试看

白名单与黑名单

通过按用户的黑名单和白名单规则控制要封锁的邮箱与域名。这些列表直接决定每次验证响应中的 block 字段。

{}

block 字段

每次验证响应都包含 block 字段。根据您的列表决定是否封锁邮箱/域名时请查看此字段：

true邮箱或其域名在黑名单中 → block: true。添加域名会封锁该域名下的所有邮箱。

true白名单已启用但邮箱/域名不在其中 → block: true。

false白名单已启用且邮箱或其域名在其中 → block: false。

—两个列表均不适用 → block 遵循正常验证结果。

概述

✘

黑名单

始终封锁指定邮箱或整个域名。例如将 example.com 加入黑名单后，任何 @example.com 的邮箱无论验证结果如何都会返回 block: true。

✔

白名单

仅允许指定邮箱或域名。白名单启用时，只有列表中的条目为 block: false，其余均为 block: true。例如添加 gmail.com 允许任意 @gmail.com，而 [email protected] 会被封锁。禁用时白名单不起作用。

可添加完整邮箱（[email protected]）或域名（example.com）。添加域名会作用于该域名下的所有邮箱。不区分大小写。

工作原理

评估顺序

先查黑名单 — 若邮箱或其域名在黑名单中，结果为 block: true。不再应用其他列表逻辑。

白名单（若已启用） — 若邮箱/域名在白名单中 → block: false。否则 → block: true。

白名单未启用 — 仅应用黑名单与正常验证。

黑名单优先：在黑名单中的地址即使也在白名单中仍保持封锁。

匹配内容

邮箱验证 — API 会拿完整邮箱地址和域名与两个列表比对，任一项匹配即应用该列表规则。

域名验证 — 仅将域名与黑名单及（若启用）白名单比对。

快速参考

白名单已启用	在黑名单中	在白名单中	block 值
否	是	—	`true`
否	否	—	正常
是	是	任意	`true`
是	否	是	`false`
是	否	否	`true`

列表 API 端点

所有列表端点均需请求头：X-API-Key: your-api-key

黑名单

GET/v1/blacklist

列出黑名单条目

POST/v1/blacklist

添加邮箱或域名 · { "value": "..." }

DELETE/v1/blacklist

移除条目 · value=...

白名单

GET/v1/whitelist

列出白名单条目

POST/v1/whitelist

添加邮箱或域名 · { "value": "..." }

DELETE/v1/whitelist

移除条目 · value=...

GET/v1/whitelist/enabled

获取白名单状态 · { "enabled": boolean }

PUT/v1/whitelist/enabled

启用/禁用白名单 · { "enabled": true | false }

代码示例 (cURL)

✘

黑名单

GET/v1/blacklist

列出黑名单条目

curl "https://api.verify-email.app/v1/blacklist" \
  -H "X-API-Key: your-api-key"

POST/v1/blacklist

添加邮箱或域名

curl -X POST "https://api.verify-email.app/v1/blacklist" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "value": "[email protected]"
  }'

DELETE/v1/blacklist

移除条目

curl -X DELETE "https://api.verify-email.app/v1/[email protected]" \
  -H "X-API-Key: your-api-key"

✔

白名单

GET/v1/whitelist

列出白名单条目

curl "https://api.verify-email.app/v1/whitelist" \
  -H "X-API-Key: your-api-key"

POST/v1/whitelist

添加邮箱或域名

curl -X POST "https://api.verify-email.app/v1/whitelist" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "value": "[email protected]"
  }'

DELETE/v1/whitelist

移除条目

curl -X DELETE "https://api.verify-email.app/v1/[email protected]" \
  -H "X-API-Key: your-api-key"

GET/v1/whitelist/enabled

获取白名单状态

curl "https://api.verify-email.app/v1/whitelist/enabled" \
  -H "X-API-Key: your-api-key"

PUT/v1/whitelist/enabled

启用/禁用白名单

curl -X PUT "https://api.verify-email.app/v1/whitelist/enabled" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "enabled": true
  }'

值格式

[email protected] — 邮箱：有效格式，如 [email protected]
example.com — 域名：有效格式，如 example.com

无效值会以 400 拒绝。条目以规范化形式存储，重复项会合并为一条。

列表的适用位置

列表规则在验证之后应用。单次与批量邮箱验证及域名验证的响应中，block 字段已包含用户的黑名单与白名单结果。

MCP 服务器（人工智能代理集成）

使用模型上下文协议 (MCP)，将电子邮件验证直接集成到 Cursor 和 Claude Desktop 等人工智能代理中。您的人工智能助手可以在不离开编辑器的情况下验证电子邮件、检查域名和验证语法。

Docs endpoint for AI agents

The API exposes a machine-readable docs endpoint (no API key required) so AI agents and MCP clients can discover the server, available tools, and auth requirements. Use this URL in your agent or MCP configuration.

GET /v1/mcp/docs

Returns JSON with server name, description, serverUrl, docsEndpoint, authentication details, and full tool definitions.

curl "https://api.verify-email.app/v1/mcp/docs"

AI agents can GET this URL to receive server metadata, tool schemas, and integration instructions in JSON. No authentication is required for the docs endpoint.

Open docs endpoint How to add in Cursor How to add in Claude

Integration details

Authentication

All MCP tool calls require your API key in the X-API-Key header. Get your key from the dashboard.

MCP server URL: https://api.verify-email.app/mcp

Docs endpoint (for agents): https://api.verify-email.app/v1/mcp/docs

Cursor

Add the server in Cursor Settings → Tools & MCP, or add the config to .cursor/mcp.json in your project or home directory.

Claude Desktop

Add the server to your Claude Desktop config (mcpServers in claude_desktop_config.json). Use the server URL and X-API-Key header as shown below.

Response format

Tool results match the REST API response shape (valid, block, deliverable, remaining_credits, etc.). Use the block field for blacklist/whitelist decisions.

This MCP server is production-ready and uses the same API as the REST endpoints. Credits are consumed per verification as with the REST API.

设置

将以下配置添加到 .cursor/mcp.json 或 Claude Desktop 配置文件中：

{
  "mcpServers": {
    "email-checker": {
      "url": "https://api.verify-email.app/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

可用工具

工具	说明	输入	荣誉
verify_email	全面的电子邮件验证，包括语法、MX、SMTP、一次性、隐私和可送达性检查	{ email: string }	1
verify_domain	全面的域名验证，包括 MX 记录、一次性、隐私和全域检测	{ domain: string }	1
check_deliverability	使用 MX 和 SMTP 验证进行快速交付能力检查，无需调用外部 API	{ email: string }	1
verify_batch	单次请求可批量验证多达 100 个电子邮件或域	{ inputs: string[] }	1 per item
validate_email_syntax	根据 RFC 5322 进行快速本地语法验证，无需网络调用	{ email: string }	0 (free)