跳转到内容

邮箱可投递性检测 API

每次上传选择一种任务类型：可投递性检测使用 email_check，头像检测使用 email_avatar。两者均采用下方的异步批量任务流程。

可投递性检测 (email_check)

检测邮箱是否有效且可正常收信。仅支持 Gmail、Yandex、Mail.ru、iCloud、Outlook 和 Yahoo。

头像检测 (email_avatar)

检测邮箱是否有公开头像并返回头像链接。仅支持 Gmail、Yandex 和 Mail.ru。

仅处理所列邮箱服务及其支持的别名域名；其他域名不检测、不交付、不计费。

输入格式

上传文本文件，每行一个受支持的邮箱地址。

user@gmail.com
another@yandex.com

创建任务

POST https://api.numberchecker.ai/v1/tasks

Terminal window
curl --location 'https://api.numberchecker.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="email_check"'

头像检测 (email_avatar)

Terminal window
curl --location 'https://api.numberchecker.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="email_avatar"'

API 会返回任务 ID。请保存该 ID，并使用它轮询任务状态。

上传响应

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "0.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

检查任务状态

POST https://api.numberchecker.ai/v1/gettasks

Terminal window
curl --location 'https://api.numberchecker.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

请持续轮询，直到 status 变为 exported。pending 和 processing 都不表示任务已完成。

处理中的响应

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

导出响应

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "2.000000",
    "currency": "USD"
  }
}

结果字段

可投递性检测 (email_check)

字段描述示例
email提交文件中的输入邮箱地址。user@gmail.com
activated输入值是否被识别为已激活或已注册。yes

头像检测 (email_avatar)

字段描述示例
email提交文件中的输入邮箱地址。user@gmail.com
activated该邮箱是否有公开头像。yes
avatar头像图片地址；账号使用默认占位头像时为空。https://…
name服务商公开的显示名；没有则为空。John Doe

结果文件处理

仅在任务导出后通过 result_url 下载文件。后续处理时请保留返回的列名。

响应字段

字段描述
created_at任务创建时间。
updated_at最近一次任务状态更新时间。
task_id任务唯一标识符。
statuspending、processing、exported 或 failed。
total处理的输入值总数。
success成功处理的值。
failure处理失败的值。
result_url任务导出后的下载地址。
actual_amount最终结算金额（如有）。
estimated_amount创建任务时返回的预估金额。

状态码

Status描述
200请求成功。
202任务创建成功，已应用预估费用。
400文件无效、不支持的任务类型，或有效条目过少。
401API 密钥缺失或无效。
402账户余额不足。
403该产品对您的账户不可用（已下架或仅对白名单客户开放），请联系客服。
404未找到任务。
413上传文件过大。
500服务器内部错误，请稍后重试。
503产品临时不可用（运营方暂停维护），不会扣费，请稍后重试。

操作说明

  • 任务为异步处理，请使用任务 ID 轮询状态。
  • 上传前请检查产品专属的输入限制。
  • 失败行会在导出结果中报告，并反映在任务计数器中。
  • 以上字段基于当前线上 sample；上游导出结构变化时，字段也可能变化。