Email Verifier API 快速入门

当验证需要成为您自己的产品或导入流程的一部分时，请使用 API。创建具有 verify:read 和 verify:write 权限范围的令牌，对其保密，并调用您登录时使用的同一主机。在示例中，请替换 https://YOUR-TREKMAIL-HOST 和 YOUR_API_TOKEN。

1. 创建令牌

1. 打开 控制面板 → AI Agents & API。
2. 创建令牌。
3. 启用 verify:read 和 verify:write。
4. 安全保存令牌。它只显示一次。

每次请求都应发送此令牌：

Authorization: Bearer YOUR_API_TOKEN

将令牌存放在机密存储或环境变量中。不要将其放入浏览器端代码、公共代码库、支持请求或导出的联系人文件。如果怀疑令牌已泄露，请将其撤销并在控制面板中创建替代令牌。

2. 验证一个地址

使用 POST /api/v1/verify 立即获取单个地址的结果。省略 mode 时，默认使用 Quick。

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

响应包含稳定的顶层字段，例如地址、状态、可信度评分、提供商、风险因素和剩余点数。checks 对象记录详细依据；当某项检查不可用或 Deep 模式提供额外信息时，其内容可能有所不同。

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

先读取 status 和 trust_score。各个检查键只应视为辅助信息，不能保证收件箱归属或邮件送达。

单地址 endpoint 的路由限制为每分钟 60 次请求。如果您在注册过程中检查用户输入的地址，请先完成基本的客户端验证再调用它；服务暂时不可用时，应显示清晰的错误，而不是无限期阻止用户继续操作。

3. 提交批量任务

批量请求接收 JSON emails 数组，而不是上传文件。请加入幂等键，避免网络重试创建第二个任务。

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"September contacts",
    "mode":"deep",
    "emails":["first@example.com","second@example.net"]
  }'

列表最多可包含 50,000 个条目。TrekMail 会规范化重复项，并从任务中拒绝语法无效的条目。响应会报告任务 ID、接受数量、少量拒绝样本、收取的点数以及 Deep 计价明细。

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe 是按完整 Deep 费率收费的数量。skip 是按常规费率收费的数量，因为提供商无法提供有用的邮箱级依据。该响应给出了本次提交的权威成本。

提交完整列表前，请在您自己的导入程序中移除非地址值。API 会对地址去重并报告拒绝数量，但源数据验证能留下更清晰的审计记录。如果从应用程序的角度看请求已超时，请使用相同的幂等键重试同一批量请求，并在新建另一次提交之前检查返回的任务 ID。

4. 轮询并下载

使用 GET /api/v1/verify/bulk/{jobId} 轮询任务，直到其进入最终状态：

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

响应包含 status、total、processed、progress、summary、创建时间和完成时间。已完成和部分完成的任务会包含分页的 results 数组。

请以合理的间隔轮询，并逐步延长等待时间。任务可能会在工作开始前保持待处理状态；当接收提供商能提供额外依据时，Deep 处理可能耗时更久。不要仅凭列表大小假设固定的完成时间。

结果可用后，您可以请求较小的结果页面或查找已知地址：

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

将处理后的任务下载为 CSV：

curl -o results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

API 导出筛选条件为 all、safe 和 safe_risky（Safe + Valid + Risky）。

如需停止待处理或正在运行的任务，请使用取消 endpoint。系统会退还未处理工作的点数，并保留所有已处理行：

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

只有在您希望同时移除验证器任务记录及其结果时才删除任务。如果任务仍在运行，请先将其取消，再使用带幂等键的删除 endpoint。完整参考文档展示了这两种调用。

5. 处理常见响应

• 402：账户需要更多点数。
• 422：检查请求正文、所选模式或批量请求必需的幂等键。
• 429：降低速度并逐步延长等待时间后重试。
• 503：验证暂时不可用。请稍后重试；失败的单地址验证会退还点数。

生产集成检查清单

1. 将令牌保存在服务器端，并且只授予所需的两个验证器权限范围。
2. 调用批量 API 前验证并规范化联系人输入。
3. 保存任务 ID、已提交列表标识符、幂等键以及返回的 credits_charged 值。
4. 轮询时逐步延长等待时间，不要使用紧密循环。
5. 在 15 天保留期结束前保存或处理 CSV。
6. 在您自己的应用程序中管理同意、退订和抑制决定。验证结果不能替代这些决定。

有关所有 endpoints、权限范围和响应字段，请参阅 Email Verifier REST API 参考。