447 lines
9.3 KiB
Markdown
447 lines
9.3 KiB
Markdown
# 注册机接入与邮箱池 API 文档
|
||
|
||
## 📖 概览 Overview
|
||
|
||
本文档描述邮箱池管理系统的公开 API，供注册机业务方、脚本接入方使用。
|
||
|
||
**服务定位**：为注册机提供邮箱领取、状态回传、池管理等功能。
|
||
|
||
**数据格式**：所有请求和响应均使用 JSON 格式。
|
||
|
||
**支持 CORS**：支持跨域请求。
|
||
|
||
---
|
||
|
||
## 🔐 鉴权与通用规则
|
||
|
||
### API Key 获取
|
||
|
||
联系系统管理员获取 API Key，在请求头中携带：
|
||
|
||
```
|
||
Authorization: Bearer YOUR_API_KEY
|
||
```
|
||
|
||
**测试环境**：联系管理员获取测试 Key（调用限制：100 次/分钟）
|
||
|
||
### 统一响应格式
|
||
|
||
所有接口遵循统一的响应格式：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": { ... },
|
||
"message": "操作成功"
|
||
}
|
||
```
|
||
|
||
失败时：
|
||
|
||
```json
|
||
{
|
||
"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
|
||
需要鉴权：是
|
||
```
|
||
|
||
### 请求示例
|
||
|
||
```bash
|
||
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 邮箱 |
|
||
|
||
### 成功响应示例
|
||
|
||
```json
|
||
{
|
||
"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 | 租约过期时间，过期前需完成回传或释放 |
|
||
|
||
### 失败响应示例
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "no_available_account",
|
||
"message": "池中没有符合条件的可用邮箱"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2️⃣ 完成任务并回传结果
|
||
|
||
### 基本信息
|
||
|
||
```
|
||
POST /api/pool/claim-complete
|
||
需要鉴权：是
|
||
```
|
||
|
||
### 请求示例
|
||
|
||
```bash
|
||
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` | 网络问题、临时故障，可立即重试 |
|
||
|
||
### 成功响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"account_id": 12,
|
||
"pool_status": "used"
|
||
},
|
||
"message": "结果回传成功"
|
||
}
|
||
```
|
||
|
||
### 失败响应示例
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "invalid_claim",
|
||
"message": "claim_token 已失效或与 account_id 不匹配"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3️⃣ 释放邮箱
|
||
|
||
### 基本信息
|
||
|
||
```
|
||
POST /api/pool/claim-release
|
||
需要鉴权：是
|
||
```
|
||
|
||
### 请求示例
|
||
|
||
```bash
|
||
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 | 否 | 释放原因 |
|
||
|
||
### 成功响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"account_id": 12,
|
||
"pool_status": "available"
|
||
},
|
||
"message": "邮箱已释放回池"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4️⃣ 查看池状态
|
||
|
||
### 基本信息
|
||
|
||
```
|
||
GET /api/pool/stats
|
||
需要鉴权：是
|
||
```
|
||
|
||
### 请求示例
|
||
|
||
```bash
|
||
curl -X GET https://api.example.com/api/pool/stats \
|
||
-H "Authorization: Bearer YOUR_API_KEY"
|
||
```
|
||
|
||
### 成功响应示例
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "missing_api_key",
|
||
"message": "请在请求头中携带 Authorization: Bearer YOUR_API_KEY"
|
||
}
|
||
```
|
||
|
||
#### 请求频率超限
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "rate_limit_exceeded",
|
||
"message": "请求频率超限，请稍后重试"
|
||
}
|
||
```
|
||
|
||
#### 无可用邮箱
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "no_available_account",
|
||
"message": "池中没有符合条件的可用邮箱"
|
||
}
|
||
```
|
||
|
||
#### claim_token 不匹配
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
业务含义与内部接口完全一致。
|