电子邮件验证 API 工作流程：借助 FairValid 从沙盒走向生产环境

电子邮件验证 API 工作流程：从沙盒测试到生产结果

问题：你是一名开发者，正在为自己的系统添加电子邮件验证功能。从第一次测试调用到获得可靠的生产结果，需要经过哪些步骤？

简要回答：先使用 Test 密钥和免费沙盒。然后切换到仅包含所需权限范围的 Live 密钥。每次提交都附带幂等键。读取任务状态并分页获取结果。分别处理每种结果和每个错误代码。以下步骤遵循FairValid 客户 API 参考文档。

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

在 API 密钥页面创建一个 Test 密钥，并将其保存在你的服务器上。参考文档使用两个环境变量：FAIRVALID_API_KEY 和 FAIRVALID_BASE_URL。Test 密钥不会调用服务提供方，也不消耗积分。

Test 密钥仅接受 example.com 域名下的一小组保留地址。这些地址会模拟有效、无效、全收（Catch-all）、未知、待处理和不可用等结果。你可以在API 参考文档的“免费沙盒”部分找到具体地址。测试任务返回固定且可重复的状态：已完成、待处理、失败或已取消。批量测试任务支持查询状态、获取结果和取消。

沙盒会向你展示上述特定结果，但并未覆盖集成可能经历的所有路径，因此请为第 7 步中描述的错误代码单独规划处理方式。

批量测试任务的限制为每个工作区每小时 20 个新任务，或每 30 天 100 个。超过任一限制都会返回 HTTP 429。完全相同的重试仍会返回原任务。

第 2 步：切换到具有所需权限范围的 Live 密钥

在生产环境中，请创建具有 submit 权限范围的 Live 密钥。批量提交使用 POST /api/v1/jobs，单个地址使用 POST /api/v1/verifications。如果该密钥还需要读取任务状态和结果，请添加 read 权限范围。Live 密钥还可以拥有 balance 权限范围。另外，GET /api/v1/balance 用于读取工作区的可用积分和预留积分。完整密钥仅显示一次，因此请在创建时妥善保存。

Live 任务使用你工作区的验证队列和积分余额。密钥权限范围、密钥上限、工作区访问权限和处理限制仍然全部适用。

第 3 步：使用幂等键提交任务

每个任务以 JSON 格式接受 1 至 5,000 个地址，大小不超过 2 MiB。每次提交任务以及每次实时提交单个地址时，都要发送 Idempotency-Key 请求头。该键长度须为 8 至 128 个字符，可使用字母、数字、点、冒号、下划线或连字符。

• 新任务会返回 HTTP 202，并附带 UUID 格式的 job_id。
• 匹配的重试会返回 HTTP 200，并附带同一个任务。
• 使用已用过的幂等键但请求体有变化时，会返回 HTTP 409 idempotency_conflict。

如果无法确定请求是否已成功送达，请使用相同的 API 密钥、相同的幂等键和相同的规范化请求体进行重试。重放仅限于同一个 API 密钥，因此更换该凭据后重新提交可能会产生第二次运行。只有在确实需要全新运行时才使用新的幂等键，而新的运行可能会被扣费。

第 4 步：读取任务并分页获取结果

使用 GET /api/v1/jobs/{id} 读取任务。其状态可能为排队中、运行中、已暂停、取消中、已取消或已完成。使用 GET /api/v1/jobs/{id}/results 读取结果。每页最多返回 50 条结果，并附带一个已签名的 next_cursor。将该值作为 cursor 查询参数传入，它会保留你最初的筛选条件和搜索内容。

筛选条件包括 all、valid、invalid、catch_all、unknown、still_checking 和 not_checked。如需停止任务，可通过 POST /api/v1/jobs/{id}/cancel 请求取消，但已在进行中的工作仍可能完成。

参考文档还介绍了已签名的完成事件，并提供了 Webhook 管理的链接。

第 5 步：将每种结果视为独立状态

结果指南解释了每种结果的含义：

• 有效：可用的肯定性检查结果。它从不保证邮件一定能送达收件箱。
• 无效：该地址未通过检查。
• 全收（Catch-all）：该域名可能接受许多地址，因此邮箱级别的结论可能不太确定。使用前请查看详细信息。
• 未知：检查未能给出可靠的答案。
• 仍在检查：尚无最终答案。

该指南将技术故障和未处理项目与“未知”分开描述，API 也将 unknown、still_checking 和 not_checked 作为独立的筛选条件提供。请在你自己的数据中用不同的字段或状态保存这些状态，而不要将它们合并为“未知”。

第 6 步：在核对前了解积分预留

API 参考文档指出，检查被接纳处理时会预留工作区积分。随后，结果将遵循与控制台相同的扣费和退还规则。FairValid 定价说明指出，积分预留会为正在运行的检查保留额度，最终结果决定是否扣费：

• 有效或无效：每个已完成结果扣 1 积分。
• 未知或全收（Catch-all）：最终不扣除验证积分。预留的积分会被释放或退还。
• 仍在检查：暂无最终扣费。预留并不等于已完成扣费。
• 技术故障和未处理的工作：最终不扣除验证积分。预留会被释放或退还。

如果你在任务进行中查看余额，请记住预留积分还不是最终扣费。请在结果最终确定后再进行核对。每个账户每月包含 300 个免费积分。这些积分会优先使用，且不会结转到下月。只要账户保持开通，已购买的积分就会一直保留可用。

第 7 步：按原因处理错误，而不是套用单一重试规则

• 401：密钥缺失、已被撤销或缺少所需权限范围。请修正凭据或其权限范围。
• 402 key_cap_reached：新请求将超出该密钥的终身上限，且未创建任何任务或预留。该上限计入已扣除的积分以及为已接受的唯一身份预留的积分。由于这是终身限制，它不会随时间恢复，等待也无法解除。请让有权限的人员检查该密钥的上限设置。上限本身无法为工作区增加积分。
• 422：地址无效或超出列表限制。请修正输入。
• 503 live_verification_unavailable：在运营暂停期间，新的实时提交可能返回此错误，且不会预留积分。请稍后使用相同的幂等键重试。在一次结果不确定的提交之后收到 503，并不能证明没有创建任务，因此请重复使用原来的幂等键。

每个错误都包含代码、消息和请求 ID。请将三者全部记录下来，以便联系支持团队时使用。

合理的工作顺序

1. 基于沙盒构建集成，并确认每种模拟结果都按预期处理。
2. 为上述错误代码添加明确的处理逻辑。
3. 创建一个 Live 密钥，只授予所需的最小权限范围，并设置符合预算的上限。
4. 先从一个小型实时任务开始。将其结果和积分状态与控制台进行对比，然后再扩大规模。

如果你想试用这一工作流程，可以在免费沙盒中测试各种模拟结果，无需消耗任何积分。API 参考文档提供了确切的请求细节。