DEVELOPER GUIDE

为你的系统接入追踪能力。

统一 Bearer 认证。任何支持 HTTP 的系统均可接入。

1. 创建密钥

登录后进入「API 与集成」。创建任务需要 tracking:write，读取需要 tracking:read。IP 另需 tracking:ip。账户服务和密钥都必须有效。

2. 创建任务并获取代码

curl -X POST "https://mail.senkebang.cn/api/v1/tracking/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-order-20261029-001" \
  -d '{"name":"产品资料跟进","type":"single","recipients":[{"email":"customer@example.com"}]}'

响应包含任务 id 及 recipients[].tracking_url、recipients[].html。请把每条记录的代码插入对应邮件副本，平台不会替你发信。示例邮箱仅用于说明，实际调用请替换为目标地址。

3. 查询结果

GET /api/v1/tracking/tasks/{id}
GET /api/v1/tracking/tasks/{id}/recipients?cursor=0&limit=50
GET /api/v1/tracking/tasks/{id}/events?cursor=0&limit=50
GET /api/v1/account/usage

以上请求同样需要 Authorization。以返回的 next_cursor 继续请求，null 表示本次已到末尾；持续增量拉取请自行保存最后一条事件 id，并从该 id 继续。时间为 UTC，带 _at 的字段格式为 YYYY-MM-DD HH:mm:ss。

写入约定

所有 POST 接口需要 8–128 位 Idempotency-Key，按账户隔离，保留 7 天（需清理计划）。相同键与相同路径/原始 JSON 返回原结果；不同内容返回 409。批量提交为全成功或全失败，重试不重复计量。最大批量 1000，每账户每分钟 120 次 API 请求。

更多接口

GET  /api/v1/tracking/tasks
POST /api/v1/tracking/tasks/{id}/recipients:batch
POST /api/v1/tracking/tasks/{id}/close
POST /api/v1/tracking/tasks/{id}/start
POST /api/v1/tracking/tasks/{id}/reopen
POST /api/v1/tracking/tasks/{id}/prepare

start/close/reopen/prepare 使用 {} 请求体。新集成使用 start 开启追踪，reopen 保持兼容；start 与 reopen 共用幂等记录。同一操作重试保持原请求编号和原始 JSON，关闭后再次开启须换新编号。追加接口使用 recipients 数组；默认去重仅限本次请求，跨请求新增记录会再次计量。单封任务不允许追加第二条。收件人可用 email 或 external_id 至少一种。

错误响应

401：密钥无效；403：账户到期、权限或额度不足；404：无权访问或不存在；409：幂等冲突；422：参数错误；429：限速（按 Retry-After 重试）；503：服务暂不可用。error.code、error.message 和 request_id 可用于定位问题。

此版本提供邮件追踪 API。API 创建任务为兼容现有调用默认立即追踪；如需准备状态，创建时传 initial_status: preparing，发送后调用 start（reopen 仍兼容）。prepare 接口可切回准备状态。事件响应直接包含收件人的 email、external_id，无需另查邮箱映射；只提供业务编号时 email 为空。ignored 与 ignore_reason 标识排除情况；有 IP 权限时同时返回 ip 与 region。PHP API 响应包含 X-API-Version 版本号和 X-Request-ID 请求编号。邮箱验证接口见下方说明；Webhook 暂未提供。

VERIFICATION API

让任何业务系统接入邮箱验证

沿用现有 Bearer 密钥。创建和操作需要 verification:write，查询需要 verification:read。可创建只含验证权限的密钥，无需开通追踪写入权限。

1. 提交名单

curl -X POST "https://mail.senkebang.cn/api/v1/verification/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: verification-order-0001" \
  -d '{"name":"合作伙伴名单","emails":[{"email":"person@example.com","external_id":"contact-001"}],"auto_start":true}'

示例域名仅用于说明字段，请使用你有权检查的真实名单。单个和批量只需改变 emails 数组长度。auto_start 默认为 true，返回 202；false 只保存名单，返回 201 且不预占额度。当前 check_level 固定为 deep，可省略。

2. 查看进度与结果

GET  /api/v1/verification/jobs/{id}
GET  /api/v1/verification/jobs/{id}/results?limit=100
GET  /api/v1/verification/jobs/{id}/results?status=valid
GET  /api/v1/verification/jobs?limit=50
POST /api/v1/verification/jobs/{id}/start
POST /api/v1/verification/jobs/{id}/cancel
GET  /api/v1/account/usage

POST 操作提交 {} 并携带新的 Idempotency-Key。超时重试时，使用同一路径、同一原始 JSON 和同一键；需要最新进度请 GET。结果使用 next_cursor 分页，null 表示当前没有下一页。

建议每 5–10 秒查询一次进度。completed / partial_failed / failed / cancelled 为结束状态。执行失败不等于邮箱无效。results 按原始行返回 email、external_id、result_id、status、reason_code、checked_at 和 charged_units。重复行共用 result_id；计算消耗时按 result_id 去重，或直接使用任务 summary.consumed。

如何理解结论

valid 表示获得支持接收的协议证据；invalid 表示明确格式、域名或收件人问题；risky 表示全收、转发等风险；unknown 表示暂时无法确认。验证通过不保证未来投递，unknown 不等于无效。

验证额度通过 account/usage 的 verification 对象读取，包含 total、used、reserved、available 和 ready。原追踪字段对具有 tracking:read 的密钥保持兼容。

服务未就绪怎么办

VERIFICATION_UNAVAILABLE（503）：暂没有健康节点，自动开始的创建请求不会保存半成品或预占额度；可改为 auto_start=false 保存名单，并使用新的幂等键。VERIFICATION_DISABLED（403）：账户未开通验证。QUOTA_EXCEEDED（403）：可用额度不足。所有业务接口继续遵守每账户每分钟 120 次的请求限额。