Email Checker API：如何在单次、批量和异步任务请求之间进行选择

如何为每项任务选择合适的邮箱检测 API 请求方式，并将“可投递”、“不可投递”和“无法判定”的结果映射到代码逻辑中。

调用邮箱检测 API 时，应根据等待结果的对象以及地址数量，从三种请求形式中选择一种。当用户正在等待单个地址的结果时，使用单次检测 (POST /api/v1/check)；当一小批地址同时到达时，使用同步多地址检测 (POST /api/v1/batch-check，支持 1–100 个地址，结果按输入顺序返回)；当地址已存在于文件中时，使用异步批量任务 (POST /api/v1/bulk-tasks，随后进行状态轮询)。无论采用哪种形式，请围绕三种结果（而非简单的“是/否”标志）来设计代码：可投递、不可投递和无法判定，并在调用前处理格式错误的输入。每个已完成的结果仅描述检测时刻该地址的状态。

邮箱检测 API 能回答什么，以及哪些需要您自行处理

大多数针对此主题排名的页面仅列出功能便戛然而止。集成问题的核心在于：单次调用究竟决定了什么，而您的应用程序仍需负责什么？

EmailCheckPro 的邮箱可达性检测返回“可投递”（地址在检测时刻可以接收邮件）或“不可投递”的已完成结果。邮箱头像检测增加了公共头像信号，但仅适用于 Gmail、Yandex 和 Mail.ru 地址。

您的应用程序仍需负责以下三项工作：

• 格式筛选。 完整的地址包含本地部分、@ 符号和域名。格式错误的输入属于表单错误，而非“不可投递”结论，因此请在发起调用前将其拦截。
• 确认与许可。 确认链接或您自己的许可记录涵盖了这一点。
• 时效性。 结果仅属于检测时刻。请将检测日期与结果一并存储，以便后续任务了解其时效。

将这些边界保留在代码中（而不仅仅是文档中），可以避免下文描述的最常见的集成错误。

选择邮箱检测 API 的请求形式

这三种请求形式不可互换，选择错误通常是导致表单响应缓慢或导入任务脆弱的原因。

快速决策指南：

1. 是否有用户在屏幕前等待？ 仅针对他们输入的地址使用单次检测端点。
2. 地址是否同时到达且不超过 100 个？ 发送一个多地址请求。这仍然是同步的：它是一个较大的单次调用，而不是小型批量任务。
3. 源文件是否已经是文件，或者远超几百行？ 提交批量任务，并让后台工作进程收集结果。每个产品的任务限制均适用，并列在 API 文档中。
4. 任务是否需要头像？ 首先将列表过滤为支持的 Gmail、Yandex 和 Mail.ru 域名。不支持的域名会在实时扣费前被拒绝；在头像批量文件中，这会导致准备阶段失败并返回保留状态。

对于不在文件中的几百个地址，使用多个多地址请求或仪表板的实时检测（最多支持 500 个地址）是合理的。

将结果映射到应用程序逻辑

将结果简化为布尔值是大多数集成出错的地方。使用小型的状态类型可以保持含义的完整性：

根据文档，需遵循以下三条规则：

• 在单次实时检测中，无法判定的地址会返回业务代码而非结果，且不会扣费。请将该分支视为独立状态，而不是在紧密循环中重试的错误。
• 在多地址响应中，每个项目都会说明是否存在已完成的结果。只有存在结果的项目才携带“可投递”或“不可投递”状态；其余项目属于“无法判定”或“未完成”分支。
• 无效、失败和无法判定的检测不会扣费，因此稍后重试它们除了时间外没有额外成本。请安排重试，而不是立即重复。

运行异步批量任务而不产生意外

批量任务是一个小型状态机，它应存在于后台工作进程中，而不是 Web 请求中。

1. 准备文件。 编写 TXT 或 CSV 文件，每行包含一个完整的邮箱地址。无效和重复的行会在准备过程中被移除，但预先剔除明显的垃圾数据会让您自己的统计更容易核对。
2. 提交并记录。 将 POST /api/v1/bulk-tasks 返回的任务引用保存在数据库中，同时保存源文件名、所用产品和提交时间。这样，崩溃的工作进程可以恢复任务，而不是重新提交。
3. 耐心轮询。 查询 GET /api/v1/bulk-tasks/{id} 的频率请勿超过每 30 秒一次。相比于保持连接打开的循环，检查一次后休眠的定时任务更适合此场景。
4. 及时下载。 成功的任务会在下载链接中提供一个 CSV 文件，该链接有效期为 12 小时。如果链接过期，请再次查询同一任务以获取新链接，而不是第二次上传文件。
5. 按地址合并。 由于准备过程可能会丢弃行，请始终通过邮箱地址将结果 CSV 与您的记录连接，切勿通过行号连接。

可达性 CSV 将每个地址与其结果配对。头像 CSV 还会说明是否找到了公共头像并提供头像链接；即使头像存在，该链接也可能为空，因此请将空链接视为正常值。

日常集成运维

一旦请求形式和状态正确，一些运维习惯可以保持集成的稳定性：

• 仅使用服务器端密钥。 API 密钥会消耗账户余额，该余额由 Web 检测、REST 调用、批量任务和 MCP 访问共享。切勿将其发布在浏览器或移动端代码中。
• 在变更点进行检测。 在创建或编辑地址时进行检测，然后在您自己的重新检测窗口内重复使用存储的结果，而不是在每次页面浏览时都进行调用。
• 表单处“失败即开放”，流水线中“失败即关闭”。 如果注册期间检测缓慢或未决，允许用户继续操作并标记该地址。在发送流水线中，请保留被标记的行，直到它们获得已完成的结果。
• 保护您自己的端点。 如果您的应用暴露了“检测此地址”的路由，请对其进行速率限制并返回一致的消息。OWASP 邮箱验证指南警告不要让表单泄露账户是否存在。
• 为 AI 客户端提供 MCP 端点。 https://emailcheckpro.com/mcp 支持单次检测、每次调用最多 100 个地址、产品列表和余额查询。基于文件的批量工作请保留在 Web 工作流或 REST API 上。

当前的请求限制和使用详情发布在 EmailCheckPro API 文档中；请直接阅读文档，而不是硬编码假设。

符合 API 预期的格式检查

成本最低的调用是您从未为格式错误的输入发起的调用。以下两个参考资料有助于您选择合理的筛选标准：

• WHATWG HTML 标准定义了浏览器用于 type="email" 字段的模式。它有意偏离了完整的邮件标准以保持实用性，这使其成为合理的服务器端基准。
• RFC 5321 描述了邮件传输中使用的地址形式。请将其视为针对引号本地部分等边缘情况的格式参考，而不是任何检测服务工作原理的描述。

在实践中：修剪空格，移除从文档中复制的尾随标点符号，将域名小写，保持本地部分原样，仅拒绝明显缺少本地部分、@ 或域名的输入。拒绝加号或长顶级域名的过于严格的模式会拒之门外真实用户，应予以避免。

常见问题解答

团队何时应从多地址调用切换到批量任务？

当地址已经存在于文件中，或者任务需要多次连续的多地址调用才能处理完列表时，请进行切换。多地址请求适用于同时到达且需要在同一响应中获得答案的 100 个以内的地址组。批量任务适用于可以等待的预处理导出文件，因为结果稍后以 CSV 形式返回，且工作进程只需每 30 秒或更低频率轮询状态。

应用程序应如何存储邮箱检测 API 的结果？

保留输入的地址、所用产品、文字形式的结果、检测日期和地址来源。该记录使支持团队能够解释决策，使重新检测任务能够优先选择最旧的结果，并使“无法判定”或“未完成”的行与“不可投递”的行分开。避免仅存储原始响应负载作为记录，因为其他系统将依赖于 API 的格式。

可投递结果可以替代确认邮件吗？

不能。可投递结果仅告知地址在检测时刻是否可以接收邮件，且检测本身不会发送任何内容。确认链接回答了另一个问题：输入地址的人是否控制该地址并同意接收消息。许多注册流程使用检测在发送前拦截无效地址，然后依靠确认来获取许可和所有权证明。

重试未完成检测的最安全方法是什么？

将它们放入带有延迟的队列中，而不是在失败的请求中重试。无法判定、失败和无效的检测不会扣费，但立即重试很少改变结果，且可能拖慢您自己的服务。安排定时重试，限制尝试次数并记录每次尝试的日期，可以保持记录的准确性，并让审核人员查看哪些地址仍然没有已完成的结果。

了解更多

选择适合您工作流下一步的产品信息。

• 查看产品文档 →
• 联系团队 →