批量邮箱验证 API：实用的批处理任务工作流程

批量邮箱验证 API：实用的批处理任务工作流程

问题：你自己的系统里有一份很长的地址列表。如何通过 FairValid API 分批发送，安全地处理错误，并读回结果，同时不弄乱额度？

简要回答：先用测试密钥在沙盒中开始。然后将列表拆分为每个最多 5,000 个地址的任务，并为每个任务分配独立的幂等键。使用正式密钥提交每个任务，检查其状态，并按结果类别分页浏览结果。将待处理的检查、技术故障和“未知”结果视为三种不同的情况。

已于 2026年11月13日 依据 FairValid 的API 参考文档、结果指南和额度规则核查相关依据。

第 1 步：先基于沙盒进行开发

API 参考文档指出，应在 API 密钥下创建测试密钥，将其保存在服务器上，并与基础 URL 一起配置到环境变量中。测试密钥适用于 example.com 域名下的保留地址。它们不会调用服务提供方，也不消耗额度。测试密钥只能访问其自身的模拟任务。

测试任务会返回确定性的状态：已完成、待处理、失败或已取消。请查阅 API 参考文档获取确切的沙盒地址，并用它们确认你的代码能处理这些状态。这些用例只展示其设计时预设的结果，并不能覆盖集成中的每个分支，因此请另行检查你自己的错误处理路径。

第 2 步：改用具有正确权限范围的正式密钥

API 参考文档指出，在生产环境中，需要具有 submit 权限范围的正式密钥才能创建任务。添加 read 权限范围即可读取任务状态和结果。正式密钥还可以拥有 balance 权限范围。完整的密钥只显示一次，因此请在创建时将其安全地保存在服务器上。密钥被吊销后将无法再发起新请求。

正式任务会使用你工作区的验证队列和额度余额。密钥权限范围、密钥上限、工作区访问权限和处理限制依然适用。正式密钥并不意味着无限制访问。

第 3 步：拆分列表并提交任务

每个任务可接受 1 至 5,000 个 JSON 格式的地址，大小不超过 2 MiB。以下是一种实用做法：

1. 将列表分块。举例来说，12,000 个地址可拆分为三个任务，分别包含 5,000、5,000 和 2,000 个地址。
2. 为每个分块分配独立且固定不变的 Idempotency-Key，并记录你的哪些行进入了哪个分块。在你这边保留这一映射关系，便于将结果关联回你的记录。
3. 提交到任务端点。新任务会返回 HTTP 202 以及 UUID 格式的 job_id。匹配的重试请求会返回 HTTP 200 以及同一个任务。这意味着在超时后，你可以使用相同的键重新发送相同的请求，并取回已有的任务。

第 4 步：处理两种看似相同的错误

以下两种响应都可能阻止提交，但含义不同：

• HTTP 503 live_verification_unavailable 可能在运营暂停期间返回。根据 API 参考文档，此时不会预扣额度。请稍后使用相同的 Idempotency-Key 重试。
• HTTP 402 key_cap_reached 表示新请求将超出该密钥的终身消费上限。该上限计入已扣除的额度，以及为已接受的唯一标识预留的额度。此时不会创建任务，也不会预扣额度。终身上限不会随时间恢复，因此等待无法解决问题。请在 API 密钥设置中检查该密钥的上限，或改用剩余上限足以完成该工作的密钥。密钥上限也无法为工作区增加额度，它只限制该密钥可消耗的额度。

请将这两种响应与权限错误和处理限制分开记录，以便正确的人收到正确的告警。

第 5 步：跟踪任务状态，然后分页读取结果

任务端点会返回任务的当前状态和摘要。任务状态可能为排队中、运行中、已暂停、取消中、已取消或已完成。如果你请求取消，已在处理中的工作仍可能完成。

结果端点每次最多返回 50 条结果，并附带已签名的 next_cursor。将该值作为 cursor 查询参数传入，它会沿用你最初的筛选条件和搜索内容。筛选条件包括 all、valid、invalid、catch_all、unknown、still_checking 和 not_checked。你可以用它们只提取需要决策的行，例如所有标记为“未知”的结果。

第 6 步：将结果转化为决策

结果指南将结果描述为依据，而非送达保证：

• 有效表示一次可用的肯定性检查结果，但绝不保证邮件一定能送达收件箱。
• 无效表示该地址未通过检查。
• 全收（Catch-all）表示该域名可能接受大量地址，因此关于具体邮箱的结论可能不太确定。使用该地址前请先查看详细信息。
• 未知表示检查未能给出可靠的答案。
• 仍在检查表示尚无最终答案。请继续轮询，不要将其视为“未知”。

技术故障和未处理的条目属于单独的类别。FairValid 的额度规则指出，它们不会被重新标记为“未知”。

第 7 步：了解额度预留

API 参考文档指出，在检查被纳入处理时，会预留工作区额度。结果遵循与控制台相同的扣费和返还规则。根据额度规则，每个已完成的“有效”或“无效”结果消耗一个额度。“未知”和未确定的“全收”结果最终不扣除任何验证额度，因为预扣的额度会被释放或返还。“待处理”不是最终结果。技术故障和未处理的工作同样最终不扣除额度。返还的额度保留其原有的批次和到期规则。

余额端点会报告正式工作区的可用额度和预扣额度。当其 free_allowance_held 字段为 true 时，免费额度处于冻结状态，不计入 available_credits 或 free_available。付费额度仍然可用。原始账户每月在注册日获得 300 个免费额度，未使用的免费额度不会结转。额外的工作区不会获得额外的免费额度。系统优先使用免费额度，只要账户保持开通，付费额度就不会过期。

简易检查清单

• 使用测试密钥和文档中列出的沙盒用例进行测试。
• 使用具有 submit 和 read 权限范围的正式密钥，并设置与计划工作量相符的上限。
• 每个分块不超过 5,000 个地址，并为每个分块使用固定不变的幂等键。
• 遇到 503 时，稍后使用相同的键重试。遇到 402 时不要等待，而应处理上限问题。
• 使用已签名的游标分页浏览结果，并按结果类别筛选。
• 在你的数据中将待处理、技术故障和“未知”分开处理。

如果你想试用这一工作流程，可以在首次正式提交前创建测试密钥，并在不消耗额度的情况下运行沙盒任务。API 参考文档提供了完整的端点详情。