实时邮箱验证会在用户仍停留在表单页面时检查地址。它会在点击“提交”到进入下一屏幕之间的几百毫秒内运行，并回答一个问题：这个地址是否应该进入你的数据库？实时邮箱验证 API 会替你做出判断。它会检查语法、域名及其 MX 记录、一次性邮箱和角色邮箱信号、全收件行为，以及在你请求时检查邮箱本身。然后，它会返回一个结构化结果，供你的代码执行后续操作。
本指南面向正在为注册、结账或潜在客户表单添加这道验证关卡的开发者。内容涵盖这些检查的作用、如何调用 API、如何将每种状态转化为产品决策，以及当邮件服务器响应缓慢时如何保持速度。示例使用 BillionVerify 邮箱验证 API，但其中的设计建议适用于任何服务提供商。
什么是实时邮箱验证？
实时邮箱验证是在地址输入的瞬间运行的检查，而不是等到营销活动发送时才在几天后进行。用户输入一个地址。你的前端或后端将其发送到邮箱检查 API。API 会返回 valid、invalid 或 catchall 等状态，以及背后的信号。然后，你的应用会允许注册、阻止注册，或要求用户修正拼写错误。
关键在于时机。用户仍在填写表单时，像 gmial.com 这样的拼写错误无需任何成本即可修正。欢迎邮件退信后，同样的拼写错误就会让你失去客户。错误地址也会损害你的发件人信誉，因为每次硬退信都会告诉邮箱服务商，你正在向未经确认的地址发送邮件。实时邮箱验证会在入口处拦截这些地址。
它还有助于防范欺诈：实时检查可以在账户创建前标记一次性收件箱。
实时邮箱验证与批量邮箱验证
两种方式使用相同的检查项。它们的区别在于运行时机，以及可用的处理时间。
- 实时验证 一次处理一个地址，在用户请求过程中执行。它有严格的时间限制，通常远低于一秒，因为缓慢的表单会导致用户放弃注册。它能防止错误数据进入系统。
- 批量验证 在后台处理整个列表。可能需要几分钟或几小时，期间没有人需要盯着屏幕等待。它会清理系统中已有的数据，例如在大型营销活动前，或 CRM 导入后进行清理。
大多数团队两者都需要。实时检查可以保持新数据的清洁，而定期执行批量邮箱验证则能捕获那些随着时间推移而失效的地址，例如已经离职员工的邮箱。想了解更深入的对比，请参阅实时与批量邮箱验证。
实时检查究竟测试什么
邮箱验证 API 会执行一系列检查，从成本较低的检查开始，逐步进行到成本较高的检查。每项检查都会排除一种不同类型的无效地址。
语法
第一项检查是格式。是否恰好有一个 @？本地部分是否由允许的字符组成？域名看起来像域名吗？语法检查会拒绝明显的垃圾地址，例如 john@@example 或 jane.example.com。它速度很快，也不需要网络调用。但语法完全正确，并不能说明邮箱是否存在。
域名和 MX 记录
接下来，API 会在 DNS 中查询域名。没有 MX 记录的域名无法接收邮件，因此无论地址看起来多么规范，都没有用处。这可以发现拼写错误的域名和已失效的公司域名。BillionVerify 会在 mx_records 中返回找到的 MX 主机；当域名看起来像常见域名的拼写错误时，domain_suggestion 还可以提供可能的修正建议。
一次性、角色型和免费提供商信号
有些地址确实存在，但仍然不太适合你的产品：
- 一次性 地址来自临时收件箱服务，通常会在几小时内停止工作。请参阅一次性邮箱检测的工作原理。
- 角色型 地址，例如
info@或support@，会发送给团队，而不是某个个人。它们通常可以送达，但参与度往往较低。 - 免费提供商 地址，例如 Gmail，对消费者来说很正常，但在 B2B 表单中值得记录。
API 会将这些信息报告为标记（is_disposable、is_role、is_free），这样你就可以根据产品需求做出决定。
Catch-all 域名
某些邮件服务器会接受发送到其域名下任何地址的邮件，无论该地址真实存在与否。对于这类 catch-all 域名，邮箱检查无法证明某个特定收件箱确实存在。Catch-all 结果并不代表结果不好，而是表示确定性较低，因此评分比标签更重要。Catch-all 邮箱检测介绍了其工作原理以及它为何重要。
SMTP 邮箱检查
最深入的检查会通过 SMTP 向收件人的邮件服务器询问该邮箱是否会接受邮件，但不会实际发送邮件。它可以发现真实域名下已经不存在的地址，例如前员工的收件箱。由于依赖其他人的服务器，这也是最慢的一步。在 BillionVerify 中，它由 check_smtp 参数控制。如果省略该参数，API 会执行 SMTP 检查；发送 check_smtp: false 即可跳过检查。
域名信誉
BillionVerify 还可以返回一个 domain_reputation 对象，其中包含该域名邮件服务器 IP 的黑名单结果。该信息仅供参考：不会改变状态、评分或费用。
如何调用实时邮箱验证 API
使用 BillionVerify，单次实时检查只需发送一个 HTTPS 请求。基础 URL 是 https://api.billionverify.com/v1，您的 API 密钥应放在 BV-API-KEY 请求头中。请将该密钥保存在您的服务器上。切勿将其放入浏览器代码中。
下面是一个基于 API 参考文档 的最简请求：
curl -X POST https://api.billionverify.com/v1/verify/single \
-H "BV-API-KEY: sk_xxx" \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","check_smtp":true}'
该请求包含三个参数：
| 参数 | 默认值 | 作用 |
|---|---|---|
email | 必填 | 要验证的地址 |
check_smtp | 开启 | 设置为 false 以跳过实时 SMTP 邮箱检查 |
force_refresh | false | 跳过缓存结果；新鲜结果会像新检查一样计费 |
成功的响应会将结果封装在标准结构中。以下是一个可送达地址的简化示例：
{
"success": true,
"code": "0",
"message": "Success",
"data": {
"email": "user@example.com",
"status": "valid",
"score": 0.95,
"is_deliverable": true,
"is_disposable": false,
"is_catchall": false,
"is_role": false,
"is_free": false,
"domain": "example.com",
"mx_records": ["mail.example.com"],
"check_smtp": true,
"reason": "smtp_deliverable",
"domain_suggestion": "",
"response_time": 250,
"credits_used": 1
}
}
如果您更喜欢使用 SDK，BillionVerify 为 Node.js、Python、TypeScript、Go、PHP 和 Java 提供官方 SDK。在 Node.js 中，执行 npm install billionverify-sdk 即可获得一个包含 verify 方法的客户端；在 Python 中，软件包名称为 billionverify。
读取响应：状态、评分和原因
status 字段是大多数代码分支判断的依据。以下是每种状态的含义，以及注册表单的合理默认处理方式：
| 状态 | 含义 | 注册表单默认处理 |
|---|---|---|
valid | 邮箱存在且可以接收邮件 | 接受 |
invalid | 地址不存在或无法接收邮件 | 拒绝，并要求填写其他地址 |
disposable | 临时邮箱 | 拒绝，或在限制条件下接受 |
catchall | 域名接受所有地址 | 接受并进行监控 |
role | 共享邮箱，例如 info@ | 接受，也可以标记给销售团队 |
unknown | 无法确认邮件送达率 | 接受，稍后重新检查 |
score 提供了一个介于 0 和 1 之间的更精细信号。粗略来说，valid 结果的评分为 0.85 到 1.0，catchall 约为 0.55 到 0.75，unknown 为 0.3 到 0.6，disposable 为 0.1，invalid 为 0。role 结果会保留底层检查的评分。你可以使用评分为边界情况设置自己的阈值，例如，在高价值表单中，仅接受评分高于某个值的全收件地址。
reason 字段解释判定结果。invalid 结果可能附带 invalid_syntax、no_mx_records 或 mailbox_not_found，每种原因都对应不同的用户提示。语法问题表示“请检查格式”。邮箱不存在表示“此邮箱不存在”。验证原因页面列出了所有原因，并说明哪些 unknown 原因值得重试。
有两个字段可以直接帮助用户：domain_suggestion 可以用于显示“你是不是想输入 gmail.com？”提示，而 is_disposable 可以解释为什么拒绝一次性地址。
围绕延迟预算设计注册流程
难点在于将验证融入表单，同时不拖慢流程。先设定预算。确定你愿意让用户等待多久，例如提交时等待 300 到 500 毫秒。一切都取决于这个数字。
BillionVerify 的产品文案显示，缓存结果耗时低于 200 毫秒，而完整 SMTP 检查平均需要 1–3 秒。这个差距让你有两种不错的设计：
- 设置超时的完整检查。 开启 SMTP，并设置 2–3 秒的超时时间调用 API。大多数结果会及时返回，并明确告知是
valid还是invalid。如果触发超时，则先放行，之后再重新检查。 - 立即快速检查，之后深度检查。 使用
check_smtp: false调用 API。这只能确定明确的情况：语法错误、没有 MX 记录的域名、一次性邮箱地址和角色邮箱地址。使用正常域名的地址会以unknown返回，原因是smtp_unverifiable，这是预期行为。先接受该地址，然后从后台任务中再次开启 SMTP 调用。如果邮箱不存在，则标记该账户，并要求用户确认其地址。
一些前端习惯也会有所帮助：
- 在失去焦点或提交时验证，而不是每次击键都验证。 检查
j、jo、joh会浪费调用次数和额度。 - 先运行本地语法检查， 避免为明显错误多进行一次往返请求。
- 从后端调用 API。 服务器保存 API 密钥并记录结果；浏览器只显示结果。
关于文案、错误提示位置以及何时显示提示等 UX 细节，请参阅注册过程中的邮箱验证。
失败关闭还是失败开放？处理超时和未知情况
适用于大多数产品的模式是：明确错误时失败关闭，不确定时失败开放。
- 失败关闭意味着阻止注册。当 API 表明地址明确无效时这样做：状态为
invalid，并带有invalid_syntax或no_mx_records；或者在一次性账号会造成损害的表单中，遇到disposable地址时也这样做。 - 失败开放意味着允许用户继续，然后稍后跟进。当结果不确定时这样做：状态为
unknown、域名是全收域名，或 API 尚未返回结果而你设置的超时已触发。
为什么不也阻止不确定的地址？因为其中有很多是真实用户。企业邮件服务器经常会对 SMTP 检查进行灰名单处理或限速，因此阻止这些地址会损失真实注册。接受该地址，为记录添加标签，稍后重新检查。
为 API 调用设置客户端超时，使其符合你的延迟预算。超时时，将结果视为 unknown：接受请求、存储标记，并将后台重新检查任务加入队列。稍后重试 unknown 结果，不要在当前请求中重试。
示例：在 Node.js 注册时验证邮箱
下面的示例展示了注册处理程序中的快速检查（设计 2）。它使用文档中说明的 REST 端点和响应字段、超时设置，以及上述失败时放行或阻止的规则。请根据你的框架调整名称。
const BLOCK = new Set(['invalid', 'disposable']);
async function checkEmail(email) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 400);
try {
const response = await fetch('https://api.billionverify.com/v1/verify/single', {
method: 'POST',
headers: {
'BV-API-KEY': process.env.BV_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ email, check_smtp: false }),
signal: controller.signal,
});
const body = await response.json();
if (!body.success) return { allow: true, recheck: true };
const { status, reason, domain_suggestion } = body.data;
if (BLOCK.has(status)) {
return { allow: false, reason, suggestion: domain_suggestion };
}
return { allow: true, recheck: status === 'unknown' || status === 'catchall' };
} catch {
// Timeout or network error: fail open and re-check in the background.
return { allow: true, recheck: true };
} finally {
clearTimeout(timer);
}
}
在不使用 SMTP 的情况下，大多数真实邮箱地址会返回 unknown，并获得 recheck 标记。保存账户后，后台任务会为每条标记为 recheck 的记录调用相同的端点，并启用 SMTP。Node.js 教程将介绍更完整的设置，包括官方 SDK。相同的请求也可通过 Python 或任何带有 HTTP 客户端的语言发送。
速率限制、缓存与成本
实时检查位于你的注册流程中，因此它的限制也会成为你的限制。请提前规划。
速率限制。 BillionVerify 通过针对每个账户的限制来保护其容量。当达到限制时，API 会返回 HTTP 429，并附带代码 1003 和 Retry-After 标头。请退避并重试，同时保留你自己的故障放行规则，确保限制不会阻止真实用户。
缓存。 结果会被缓存，因此重复检查能够快速返回。重新检查过去 24 小时内你的账户已经验证过的地址是免费的。只有在确实需要最新结果时，才使用 force_refresh: true，因为它会跳过缓存，并按新检查计费。
成本。 单次检查通常使用 1 个积分，该用量显示在 credits_used 中。所有 unknown 结果都是免费的，语法错误也不收费。请在提交时进行验证，而不是每次击键都验证，也不要重新检查最近已经验证过的地址。BillionVerify 每天登录时会赠送 20 个免费积分，每月最多 600 个，足以用于构建和测试集成。付费积分包列在定价页面。
超越表单：批量、文件和 Webhook
实时验证会逐个处理新地址。对于其他场景，同一个 API 还提供以下入口：
- 小批量。
POST /verify/bulk可在一次请求中检查最多 50 个地址，适用于 CRM 同步或导入页面。 - 大型列表。
POST /verify/file接受 CSV、TXT 或 XLSX 文件，并在后台处理。 - Webhook。 无需轮询文件任务，只需为
file.completed和file.failed事件注册 Webhook。请参阅 邮箱验证 Webhook 指南，了解签名检查和重试。 - 仅检查临时邮箱。
POST /verify/disposable只回答是否为临时邮箱，不消耗额度。
一种常见配置是：每个表单都进行实时检查，每晚对标记为 recheck 的记录执行批量检查，并在大型营销活动前处理文件任务。
实时邮箱验证清单
上线前，请逐项检查以下清单：
- API 密钥存放在服务器上，绝不放在浏览器中。
- 在调用 API 前，先在本地检查语法。
- 请求路径使用
check_smtp: false，并设置符合延迟预算的超时时间。 invalid和disposable有清晰、具体的错误消息。unknown、catchall和超时情况采用宽松失败策略，并加入队列以便重新检查。domain_suggestion用于提供拼写错误提示。- 429 响应采用退避策略，不阻塞用户。
- 结果与用户记录一起存储，以便之后衡量退信率。
常见问题
什么是实时邮箱验证 API？
实时邮箱验证 API 会在用户提交表单时检查单个邮箱地址，并在几分之一秒内返回结果。它会执行语法、域名、MX、一次性邮箱、角色邮箱和全捕获检查，并可选择执行 SMTP 邮箱检查，让你的应用在地址进入数据库前接受、阻止或标记该地址。
实时邮箱验证与批量验证有何不同？
实时邮箱验证会在用户请求中一次检查一个地址，因此必须快速响应。批量验证则会在后台检查整个列表，可能需要更长时间。使用实时检查来保持新数据清洁，使用批量检查来清理已有数据。
我应该在每次注册时都运行 SMTP 检查吗？
这取决于你的延迟预算。SMTP 检查用于确认邮箱，因此没有它，大多数真实地址都会返回 unknown。如果可以等待 2–3 秒，请在提交时运行检查并设置超时。如果不行，请使用 check_smtp: false 运行快速检查，然后在后台任务中执行 SMTP 检查。
我应该如何处理全捕获和未知结果？
接受这些结果，并稍后重新检查。全捕获域名会接受所有地址，因此邮箱检查无法证明收件箱存在；而未知结果表示检查未能完成。阻止这些用户会损失真实注册；为其添加标签并重新检查，可以保持数据清洁，同时不会影响转化率。
我可以从浏览器调用邮箱检查 API 吗？
不可以。这样会暴露你的 API 密钥。请从后端调用 API，并仅返回判断结果。
实时邮箱验证有多快？
使用 BillionVerify 时，缓存结果会在 200 ms 内返回，完整的 SMTP 检查平均需要 1–3 秒。因此，不带 SMTP 的快速检查应放在请求路径中，而 SMTP 检查应在后台执行。
邮箱验证 API 的费用是多少？
在 BillionVerify 中，单次检查通常使用 1 个积分，每个 unknown 结果均免费。每天登录即可获得 20 个免费积分，每月最多 600 个积分；付费积分包可在价格页面购买。force_refresh 会跳过缓存，并按新检查计费。
实时验证邮箱
实时邮箱验证意味着更少的退信、更少的虚假账户，以及更少因拼写错误而流失的用户。在请求路径中加入快速检查，将慢速检查移至后台，并让明确失败的结果阻止请求，同时允许不确定的结果通过。创建一个免费的 BillionVerify 账户，获取 API 密钥，并从上方文档发起您的第一次邮箱验证 API 调用。