okooooooo/outlookEmailPlus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
outlookEmailPlus/注册与邮箱池接口文档.md
T

9.3 KiB
Raw Permalink Blame History

注册机接入与邮箱池 API 文档

📖 概览 Overview

本文档描述邮箱池管理系统的公开 API，供注册机业务方、脚本接入方使用。

服务定位：为注册机提供邮箱领取、状态回传、池管理等功能。

数据格式：所有请求和响应均使用 JSON 格式。

支持 CORS：支持跨域请求。

🔐 鉴权与通用规则

API Key 获取

联系系统管理员获取 API Key，在请求头中携带：

Authorization: Bearer YOUR_API_KEY

测试环境：联系管理员获取测试 Key（调用限制：100 次/分钟）

统一响应格式

所有接口遵循统一的响应格式：

{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}

失败时：

{
  "success": false,
  "error": "error_code",
  "message": "错误描述"
}

时间字段约定

所有时间字段使用 ISO 8601 格式：YYYY-MM-DDTHH:MM:SSZ

📋 API 端点列表

快速开始

注册机接入只需关注以下 3 个核心接口：

接口 用途 必要性
POST /api/pool/claim-random 领取邮箱 必需
POST /api/pool/claim-complete 完成任务回传 必需
POST /api/pool/claim-release 释放邮箱 必需
GET /api/pool/stats 查看池状态 可选

1️⃣ 领取邮箱

基本信息

POST /api/pool/claim-random
需要鉴权：是

请求示例

curl -X POST https://api.example.com/api/pool/claim-random \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caller_id": "register-worker-1",
    "task_id": "job-20260317-0001",
    "provider": "outlook"
  }'

参数说明

参数名 类型 必填 说明
caller_id string 是 调用方标识，建议使用固定的业务方标识或机器标识，如：register-worker-1、register-cluster-a
task_id string 是 当前注册任务的唯一 ID，如：job-20260317-0001、order-928371
provider string 否 邮箱提供商筛选，传 outlook 则只领取 Outlook 邮箱

成功响应示例

{
  "success": true,
  "data": {
    "account_id": 12,
    "email": "demo@outlook.com",
    "claim_token": "clm_xxxxx",
    "lease_expires_at": "2026-03-17T10:00:00Z"
  },
  "message": "邮箱领取成功"
}

响应字段说明

字段名 类型 说明
account_id integer 账号 ID，回传时必需
email string 邮箱地址
claim_token string 领取令牌，回传时必需
lease_expires_at string 租约过期时间，过期前需完成回传或释放

失败响应示例

{
  "success": false,
  "error": "no_available_account",
  "message": "池中没有符合条件的可用邮箱"
}

2️⃣ 完成任务并回传结果

基本信息

POST /api/pool/claim-complete
需要鉴权：是

请求示例

curl -X POST https://api.example.com/api/pool/claim-complete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 12,
    "claim_token": "clm_xxxxx",
    "caller_id": "register-worker-1",
    "task_id": "job-20260317-0001",
    "result": "success",
    "detail": "注册成功"
  }'

参数说明

参数名 类型 必填 说明
account_id integer 是 领取时返回的账号 ID
claim_token string 是 领取时返回的令牌
caller_id string 是 必须与领取时的 caller_id 一致
task_id string 是 必须与领取时的 task_id 一致
result string 是 任务结果，见下方【result 可选值】
detail string 否 详细说明，建议填写失败原因、目标站名称、风控现象等

result 可选值及对应状态

result 值 说明 邮箱最终状态 使用场景
success 注册成功，账号已消耗 used 成功完成注册任务
verification_timeout 未收到验证码 cooldown 长时间未收到验证码，建议冷却后再试
provider_blocked 被供应商风控 frozen 供应商风控、被封、被限制
credential_invalid 凭据失效 retired 邮箱密码或凭据已失效
network_error 网络故障 available 网络问题、临时故障，可立即重试

成功响应示例

{
  "success": true,
  "data": {
    "account_id": 12,
    "pool_status": "used"
  },
  "message": "结果回传成功"
}

失败响应示例

{
  "success": false,
  "error": "invalid_claim",
  "message": "claim_token 已失效或与 account_id 不匹配"
}

3️⃣ 释放邮箱

基本信息

POST /api/pool/claim-release
需要鉴权：是

请求示例

curl -X POST https://api.example.com/api/pool/claim-release \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 12,
    "claim_token": "clm_xxxxx",
    "caller_id": "register-worker-1",
    "task_id": "job-20260317-0001",
    "reason": "任务取消"
  }'

参数说明

参数名 类型 必填 说明
account_id integer 是 领取时返回的账号 ID
claim_token string 是 领取时返回的令牌
caller_id string 是 必须与领取时一致
task_id string 是 必须与领取时一致
reason string 否 释放原因

成功响应示例

{
  "success": true,
  "data": {
    "account_id": 12,
    "pool_status": "available"
  },
  "message": "邮箱已释放回池"
}

4️⃣ 查看池状态

基本信息

GET /api/pool/stats
需要鉴权：是

请求示例

curl -X GET https://api.example.com/api/pool/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

成功响应示例

{
  "success": true,
  "data": {
    "total": 1000,
    "available": 850,
    "claimed": 120,
    "used": 20,
    "cooldown": 5,
    "frozen": 3,
    "retired": 2
  },
  "message": "查询成功"
}

⚠️ 错误处理

HTTP 状态码一览

状态码 说明
200 请求成功
400 请求参数错误
401 未授权（缺少或无效的 API Key）
403 禁止访问
404 资源不存在
429 请求频率超限
500 服务器内部错误

常见错误响应

缺少 API Key

{
  "success": false,
  "error": "missing_api_key",
  "message": "请在请求头中携带 Authorization: Bearer YOUR_API_KEY"
}

请求频率超限

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "请求频率超限，请稍后重试"
}

无可用邮箱

{
  "success": false,
  "error": "no_available_account",
  "message": "池中没有符合条件的可用邮箱"
}

claim_token 不匹配

{
  "success": false,
  "error": "invalid_claim",
  "message": "claim_token 已失效或与 account_id 不匹配"
}

📝 使用限制

频率限制

  • 领取邮箱：60 次/分钟
  • 回传结果：120 次/分钟
  • 查询状态：300 次/分钟

租约超时

领取邮箱后，必须在 lease_expires_at 前完成回传或释放。超时未处理的邮箱将自动释放回池。

建议重试策略

  • 遇到 429 错误时，等待 1 秒后重试
  • 遇到 no_available_account 时，等待 5-10 秒后重试
  • 建议使用指数退避算法

🔄 业务流程图

导入邮箱（add_to_pool=true）
         ↓
邮箱进入池子（status=available）
         ↓
注册机调用 claim-random 领取邮箱
         ↓
注册机执行注册任务
         ↓
    ┌────┴────┐
    ↓         ↓
 成功/失败   中途放弃
    ↓         ↓
claim-complete  claim-release
    ↓         ↓
邮箱状态更新   邮箱返回池子

🎯 常见问题

Q1: 账号导入了，但注册机领不到？

原因：

  1. 导入时没有设置 add_to_pool=true
  2. 账号状态不是 active 或不在 available

解决：检查导入参数，确保账号正确入池。

Q2: 回传时提示参数不匹配？

原因：account_id、claim_token、caller_id、task_id 四个字段必须与领取时完全一致。

解决：注册机必须保存领取时的原始参数，不能自行修改。

Q3: 领取后忘记回传会怎样？

后果：邮箱会停留在 claimed 状态，影响后续分配。

建议：

  • 成功或失败都调用 claim-complete
  • 中途放弃调用 claim-release

Q4: 所有失败都回传 network_error 会怎样？

后果：已失效的邮箱会继续回池，被重复分配，浪费资源。

建议：根据实际失败原因选择正确的 result 值。

📞 联系方式

  • 问题反馈：[提交 Issue]

📅 更新日志

v1.0.0 (2026-03-17)

  • 初始版本发布
  • 支持邮箱领取、回传、释放、查询功能

外部接口路径

如果通过外部受控接口调用，路径对应为：

  • /api/external/pool/claim-random
  • /api/external/pool/claim-complete
  • /api/external/pool/claim-release
  • /api/external/pool/stats

业务含义与内部接口完全一致。

Reference in new issue View Git Blame Copy Permalink