Email Verifier REST API 参考

Email Verifier API 位于 /api/v1 下。请使用您账户登录时所用的 TrekMail 主机。以下示例使用 https://YOUR-TREKMAIL-HOST 作为 placeholder。

身份验证和权限范围

在 Authorization 请求头中传递 API 令牌：

Authorization: Bearer YOUR_API_TOKEN

创建令牌时启用权限范围：

如果客户端需要提交任务，然后读取或下载结果，请同时授予这两个权限范围。

主机和请求格式

所有示例都使用 JSON 请求正文和 Bearer 令牌。控制面板文件上传器与 API 分开：POST /verify/bulk 接收 JSON emails 数组，而不是 multipart 文件。请使用该账户和令牌所属的准确主机。不要认为一个品牌主机的令牌或余额能在另一个主机上使用。

对于 POST /verify 和 POST /verify/bulk 请求，请发送 Content-Type: application/json。令牌和幂等值应存放在客户端代码之外。

幂等性

POST /api/v1/verify/bulk 和 DELETE /api/v1/verify/bulk/{jobId} 要求提供 Idempotency-Key 请求头。为每项预期操作生成新值，并且只在重试同一操作时重复使用该值。

Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee

单地址验证和任务取消不需要此请求头。系统还会在 24 小时内针对相同规范化列表和模式检测重复批量请求，但幂等键仍是正确的重试机制。

处理不确定的网络结果

如果应用程序未收到批量请求的响应，请勿生成新的幂等键并再次提交列表。请使用同一个键重复完全相同的请求。在 TrekMail 返回任务 ID 前，将该键与源列表标识符一同保存。这样可使重试与最初预期的操作保持关联，避免不必要的第二次收费。

Endpoint 概览

请在本表的每个路径前加上 /api/v1。

读取点数余额

GET /api/v1/verify/credits

在标准 TrekMail 主机上，响应包含方案额度和已购余额：

{
  "monthly_limit": 300,
  "monthly_used": 120,
  "monthly_remaining": 180,
  "purchased_balance": 5000,
  "total_available": 5180,
  "plan": "pro",
  "trialing": false,
  "resets_at": "2026-10-01T00:00:00+00:00"
}

在 White Label 主机上，品牌产品只能使用已购点数，因此响应包含 purchased_balance 和 total_available。

请求示例：

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

在大型提交前立即读取余额。余额响应只是当时的快照，因此提交多个任务的应用程序应记录每个批量响应中收取的金额，而不是以后根据过时的数字计算。

余额字段

White Label 的余额响应特意包含较少字段，因为品牌产品只使用已购点数。

验证一个地址

POST /api/v1/verify

{
  "email": "person@example.com",
  "mode": "quick"
}

响应包含 email、status、trust_score、checks、provider、risk_factors 和 credits_remaining。在标准主机上，credits_remaining 包含 monthly 和 purchased 值。checks 的详细结构可能因模式及接收提供商所能提供的信息而异。

Quick 消耗 1 点，Deep 通常消耗 2 点，而特定提供商的例外按 1 点计算。如果收费后无法执行验证，单地址请求会退回该费用，并返回暂时不可用响应。

请求示例：

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"}'

将顶层 status、trust_score、provider 和 risk_factors 作为正常的应用程序约定。checks 包含有用的辅助依据，但上游检查被跳过、不可用或 Deep 模式获得额外信息时，具体键可能不同。

单地址结果解读

不要让应用程序将已接受的远程响应视为所有权或权限检查。订阅、退订和联系人偏好决定应单独处理。

创建批量任务

POST /api/v1/verify/bulk

{
  "emails": ["first@example.com", "second@example.net"],
  "name": "September contacts",
  "mode": "deep"
}

系统会在计价前规范化重复项。成功创建的新任务返回 201，内容如下：

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

probe 和 skip 说明 Deep 价格的计算方式。deep_savings 是与所有提交地址均按完整 Deep 费率收费相比的差额。重复列表会返回现有的 job_id 和状态，而不会启动另一个任务。

请求示例：

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

API 会在接受任务前检查提交值的电子邮件语法是否有效。如果所有条目都被拒绝，API 返回 422 且不创建任务。如果部分条目被拒绝，成功响应会报告 rejected_count，并在 rejected_sample 中提供最多五个值。不要将这份小样本当作完整的数据清理报告；请在自己的导入程序中保留源验证结果。

批量提交检查清单

1. 在自己的应用程序中读取并规范化源数据。
2. 将请求限制在 50,000 个提交条目以内。
3. 在请求前生成并持久保存幂等键。
4. 使用有意义的任务名称，以便操作人员稍后能够识别。
5. 保存 TrekMail 返回的 job_id、credits_charged 和价格明细。
6. 轮询保存的 job_id；不要根据最初的 HTTP 请求推断任务已经完成。

读取任务

GET /api/v1/verify/bulk/{jobId}

基本响应包含 job_id、name、status、total、processed、progress、summary、created_at 和 completed_at。

当已完成、部分完成或失败的任务有结果可用时，响应还会包含：

{
  "results": [
    {
      "email": "person@example.com",
      "status": "valid",
      "trust_score": 82,
      "checks": {},
      "provider": "example.com",
      "risk_factors": ["no_dmarc"]
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "last_page": 1}
}

可选查询参数：

包含已处理行的已取消任务可以下载，但请使用下载 endpoint 进行导出。

准确读取任务状态

API 客户端应逐步延长轮询间隔。不要仅仅因为现有任务仍处于待处理状态，或本地网络请求超时，就创建新的批量提交。

状态响应示例

{
  "job_id": 42,
  "name": "September contacts",
  "status": "processing",
  "total": 1500,
  "processed": 400,
  "progress": 27,
  "summary": {"safe": 220, "valid": 105, "risky": 55, "invalid": 20},
  "created_at": "2026-09-04T13:15:00+00:00",
  "completed_at": null
}

summary 会随着工作完成而增长。请使用 processed 和 total 显示进度，不要只对应用程序当前识别的类别求和。

下载任务

GET /api/v1/verify/bulk/{jobId}/download

包含已处理行的已完成、部分完成或已取消任务可以下载。系统会以流式方式传输 CSV，其中包含 Email、Status、Trust Score、Provider 和 Risk Factors 列。

示例：

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

请在 15 天的结果保留期内保存下载的输出。CSV 是供您自己的工作流使用的导出文件；它不会更改其他系统中的同意、订阅或联系人记录。

当没有可用的已处理导出文件时，下载 endpoint 会返回冲突。请先检查任务状态。成功的请求会以流的形式传输 CSV，而不是返回 JSON 包装，因此 HTTP 客户端应将其作为文件响应处理。

列出任务

GET /api/v1/verify/bulk

使用 page、per_page 和可选的 status。per_page 默认为 20，可接受 1 到 100。任务状态值包括 pending、processing、completed、partial、cancelled 和 failed。

响应包含 jobs 数组和 pagination 对象。每条任务记录都包含 ID、名称、状态、总数、已处理数量、进度和时间戳。

示例：

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk?status=processing&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

当 worker 重启或需要核对任务 ID 时，请使用列表 endpoint。不要将任务名称当作唯一标识符；请保存返回的数字 job_id。

任务列表响应结构

{
  "jobs": [
    {
      "job_id": 42,
      "name": "September contacts",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-09-04T13:15:00+00:00",
      "completed_at": "2026-09-04T13:28:00+00:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 20, "total": 1, "last_page": 1}
}

如果运维页面只需要进行中或已完成的任务，请使用 status 查询参数。对于验证大量列表的账户，分页非常重要；不要认为一次响应包含全部历史记录。

取消任务

POST /api/v1/verify/bulk/{jobId}/cancel

只取消待处理或运行中的工作。成功响应如下：

{"status":"cancelled","credits_refunded":40}

退款只针对未处理的工作。如果任务在取消请求到达前已进入最终状态，API 会返回冲突，而不改变结果。

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

取消不会删除任务。如有需要，请下载已处理的行，或随后删除已进入最终状态的记录。

删除任务

DELETE /api/v1/verify/bulk/{jobId}

请先取消运行中的任务。在 TrekMail 安全移除暂存的源列表后，删除操作会永久移除任务及其结果。成功响应如下：

{"deleted":true}

curl -X DELETE https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 843ef0c5-4dc0-4c09-bacd-5bd0fe87e847"

此操作对验证器记录不可逆。它不会撤回应用程序已下载的 CSV 文件，因此请对这些副本执行自己的保留流程。

删除顺序

1. 读取任务状态。
2. 如果任务待处理或正在运行，请将其取消。
3. 保存需要保留的任何已处理导出文件。
4. 使用幂等键删除未运行的验证器任务。
5. 根据您系统的隐私和保留规则，删除系统存储的所有副本。

错误和重试

单地址验证的路由限制为每分钟 60 个请求，批量提交为每分钟 10 个请求。实施逐步延长等待时间的重试逻辑，重试批量请求时保留相同的幂等键，并且不要在网络结果未知后盲目重试。

安全重试模式

1. 批量提交前生成并保存一个幂等键。
2. 使用该键发送请求。
3. 如果响应丢失，请使用同一个键重复完全相同的请求。
4. 保存返回的 job_id，并停止为该源列表创建新的提交。
5. 轮询该任务直到最终状态，然后下载或处理结果。

对于单地址验证，暂时性 503 响应表示服务无法完成检查。请稍后以正常的递增间隔重试。不要在自己的数据库中将此响应转换为 Invalid 结果。

联系人数据安全

在许多情况下，电子邮件列表属于个人数据。只发送验证所需的数据，将令牌访问权限限制在执行任务的系统，并避免在应用程序日志中记录完整地址数组。需要日志时，请存储任务 ID、数量、时间和概要结果，而不是完整列表。

TrekMail 将结果保留 15 天。在集成高容量列表前，请规划自己的安全导出存储或删除路径。

验证信号不能证明个人拥有该地址、已表示同意或邮件将来一定送达。即使地址获得 Safe 评分，也应继续在自己的应用程序中处理权限和抑制。