Mail Hub

活跃渠道

-

活跃邮箱

-

封禁规则

-

追踪服务

-

创建邮箱

目标服务

渠道

域名

认证方式

所有 /api/* 接口需在请求头中携带 Bearer Token。支持两种身份：

Authorization: Bearer your-token

管理员密钥（环境变量 API_SECRET）：拥有全部权限，包括密钥管理接口。

普通 API Key（通过管理员创建，mk_ 前缀）：可调用除密钥管理外的全部接口。每次调用自动记录用量。

若未设置 API_SECRET 则无需认证（开发模式）。

错误处理

所有错误响应格式统一：

{
  "error": "错误描述信息"
}

常见状态码：400 参数错误、401 未认证、404 资源不存在、409 资源冲突、410 资源已关闭、502 上游服务异常、503 全部渠道不可用。

邮箱管理

核心工作流：创建临时邮箱 → 轮询收信 → 提取验证码 → 上报结果 → 关闭邮箱。

POST /api/inbox 创建邮箱（自动调度或指定渠道）

请求体 (JSON)

参数	类型	必填	说明
for	string	否	目标服务名（如 `twitter.com`），用于避开被封禁域名
provider	string	否	指定渠道名（如 `mailtm`、`outlook`），不填则自动调度
domain	string	否	指定域名
duration	number	否	邮箱有效时长（分钟），部分渠道支持
needPolling	boolean	否	是否要求渠道支持轮询收信，默认 `true`

响应 201

{
  "id": "aBcDeFgHiJkL",
  "address": "random@domain.com",
  "provider": "mailtm",
  "expiresAt": "2025-01-01T12:00:00Z",
  "features": { "pollInbox": true, "attachments": false, ... }
}

自动调度会按信任等级、限流状态、封禁域名等综合评分选择最优渠道。Outlook 渠道从账号池中分配。

GET /api/inboxes 查询邮箱列表

查询参数

参数	类型	必填	说明
status	string	否	`active` 或 `closed`
provider	string	否	按渠道名筛选
for	string	否	按目标服务筛选

响应 200

{
  "inboxes": [
    { "id": "...", "provider": "mailtm", "address": "...",
      "target_service": "twitter.com", "created_at": "...",
      "expires_at": null, "status": "active" }
  ]
}

GET /api/inbox/:id/messages 获取邮箱内所有邮件

路径参数

参数	说明
id	邮箱 ID（由创建接口返回）

响应 200

{
  "messages": [
    { "id": "msg-id", "from": "noreply@x.com",
      "subject": "验证码", "excerpt": "您的验证码是...",
      "receivedAt": "2025-01-01T12:00:00Z" }
  ]
}

GET /api/inbox/:id/messages/:mid 获取单封邮件详情（含 HTML/Text 正文）

路径参数

参数	说明
id	邮箱 ID
mid	邮件 ID（由邮件列表返回）

响应 200

{
  "id": "msg-id", "from": "...", "subject": "...",
  "text": "纯文本正文",
  "html": "<html>...</html>",
  "receivedAt": "2025-01-01T12:00:00Z"
}

GET /api/inbox/:id/code 自动提取验证码/链接

查询参数

参数	类型	必填	说明
wait	boolean	否	设为 `true` 会轮询等待邮件到达
timeout	number	否	等待超时（秒），默认 60，最大 120
type	string	否	按类型过滤：`numeric`、`alphanumeric`、`link`

响应 200

{
  "codes": [
    { "type": "numeric", "value": "483921",
      "confidence": 0.95, "context": "您的验证码是 483921" }
  ],
  "email": { "from": "...", "subject": "..." }
}

典型集成方式：先 POST /api/inbox 创建邮箱 → 用邮箱注册目标服务 → GET /api/inbox/:id/code?wait=true&timeout=60 等待验证码。

POST /api/inbox/:id/report 上报邮箱使用结果（成功/失败）

请求体 (JSON)

参数	类型	必填	说明
success	boolean	是	`true` 记录成功，`false` 记录失败并封禁域名
service	string	否	目标服务名，失败时用于记录封禁关系

响应 200

{
  "ok": true,
  "action": "block_recorded",
  "blocked": { "service": "twitter.com", "domain": "example.com" }
}

上报失败后，该域名在下次调度时会自动被跳过（仅针对对应服务）。这是调度智能化的核心反馈机制。

DELETE /api/inbox/:id 关闭邮箱

关闭后邮箱状态变为 closed，不再可用。Outlook 渠道会释放账号回池。

响应 200

{ "ok": true }

封禁管理

管理「服务 + 域名」的封禁规则。调度器创建邮箱时会自动跳过已封禁的域名。

GET /api/blocks 查询封禁列表

查询参数

参数	类型	必填	说明
service	string	否	按服务名精确筛选
domain	string	否	按域名精确筛选

响应 200

{
  "blocks": [
    { "id": 1, "service": "twitter.com", "domain": "sharklasers.com",
      "provider": "guerrillamail", "blocked_at": "...", "reason": "..." }
  ]
}

POST /api/blocks 手动添加封禁

请求体 (JSON)

参数	类型	必填	说明
service	string	是	服务名
domain	string	是	域名
provider	string	否	关联渠道名
reason	string	否	封禁原因

响应 201

{ "ok": true }

DELETE /api/blocks/:id 删除封禁记录

路径参数

参数	说明
id	封禁记录 ID（由列表接口返回）

响应 200

{ "ok": true }

渠道管理

查询和配置邮箱渠道（Provider）。每个渠道可独立启用/禁用和调整优先级。

GET /api/providers 列出所有已注册渠道

响应 200

{
  "providers": [
    { "name": "mailtm", "displayName": "Mail.tm",
      "type": "api", "tier": "free",
      "trustLevel": 3, "enabled": true, "priority": 0,
      "rateLimit": { "createPerMinute": 10, "pollPerMinute": 30 },
      "features": { "pollInbox": true, ... },
      "rateStatus": { "currentCount": 2, "maxPerWindow": 10 } }
  ]
}

GET /api/providers/:name 获取渠道详情（含域名、统计）

响应 200

{
  "name": "mailtm", "displayName": "Mail.tm",
  "domains": ["dpptd.com", "exelica.com"],
  "stats": {
    "success_count": 42, "fail_count": 3,
    "last_success_at": "...", "last_error": "..."
  },
  "rateStatus": { ... }
}

PATCH /api/providers/:name 更新渠道配置

请求体 (JSON)

参数	类型	必填	说明
enabled	boolean	否	启用/禁用渠道
priority	number	否	调度优先级（越高越优先）

响应 200

{ "ok": true, "enabled": true, "priority": 10 }

GET /api/providers/:name/domains 获取渠道当前可用域名

响应 200

{
  "provider": "mailtm",
  "domains": ["dpptd.com", "exelica.com"]
}

Outlook 账号池

Outlook 是池化渠道：从预导入的账号中分配邮箱，而非创建新邮箱。需先通过导入或购买接口补充账号池。

GET /api/outlook/stats 账号池统计

响应 200

{
  "total": 50,
  "available": 35,
  "assigned": 15,
  "validToken": 42,
  "invalidToken": 3
}

POST /api/outlook/import 批量导入账号

请求体 (JSON)

参数	类型	必填	说明
accounts	string	是	每行一个账号，格式：`邮箱----密码----ClientID----令牌`

响应 200

{
  "imported": 10,
  "skipped": 2,
  "errors": ["格式错误: ..."]
}

分隔符为 ----（4 个减号）。ClientID 和令牌可选，不填则无法通过 Graph API 读信。已存在的邮箱会被跳过（INSERT OR IGNORE）。

GET /api/outlook/accounts 查询账号列表

查询参数

参数	类型	必填	说明
status	string	否	令牌状态：`valid`、`invalid`
available	string	否	`true` 只看空闲，`false` 只看已分配
group	string	否	按分组名筛选

响应 200

{
  "accounts": [
    { "email": "user@outlook.com", "token_status": "valid",
      "assigned_inbox_id": null, "group_name": "未分组",
      "created_at": "...", "token_renewed_at": "..." }
  ]
}

DELETE /api/outlook/accounts 批量删除账号（仅未分配的）

请求体 (JSON)

参数	类型	必填	说明
emails	string[]	是	要删除的邮箱地址列表

响应 200

{
  "deleted": 3,
  "requested": 5
}

已分配给活跃邮箱的账号无法删除，需先关闭对应邮箱释放账号。

POST /api/outlook/check 批量检测令牌有效性

请求体 (JSON)

参数	类型	必填	说明
emails	string[]	否	要检测的邮箱列表，不传则检测全部

响应 200

{
  "checked": 10,
  "valid": 8,
  "invalid": 2,
  "results": [
    { "email": "user@outlook.com", "valid": true }
  ]
}

检测原理：使用 refresh_token 向 Microsoft OAuth2 换取 access_token，成功即有效。会同步更新数据库中的 token_status 字段。

POST /api/outlook/renew 批量续期令牌

请求体 (JSON)

参数	类型	必填	说明
emails	string[]	否	要续期的邮箱列表，不传则全部续期

响应 200

{
  "total": 10,
  "renewed": 9,
  "failed": 1,
  "results": [
    { "email": "user@outlook.com", "renewed": true }
  ]
}

续期会获取新的 refresh_token 并替换旧的。Microsoft 的 refresh_token 有 90 天有效期，建议定期续期。续期成功后 token_status 自动更新为 valid。

POST /api/outlook/buy 从闪客云购买账号

请求体 (JSON)

参数	类型	必填	说明
num	number	否	购买数量，默认 1

响应 200

{
  "imported": 10,
  "errors": []
}

需在 Outlook 管理页填写闪客云卡密。购买的账号自动导入池中，分组标记为「闪客云购买」。

密钥管理

创建和管理 API Key。所有密钥管理接口仅限管理员（API_SECRET）调用，普通 Key 返回 403。

POST /api/keys 创建新密钥

请求体 (JSON)

参数	类型	必填	说明
name	string	是	备注名称（如"给小明"、"自动化脚本"）

响应 201

{
  "key": "mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "name": "给小明",
  "callCount": 0,
  "lastUsedAt": null,
  "active": true
}

GET /api/keys 列出所有密钥（含完整 Key 和用量）

响应 200

{
  "keys": [
    { "key": "mk_aBcDeFgH...", "name": "给小明",
      "callCount": 42, "lastUsedAt": "2025-01-01T12:00:00",
      "createdAt": "...", "active": true }
  ]
}

PATCH /api/keys/:key 更新密钥（改名、启用/禁用）

请求体 (JSON)

参数	类型	必填	说明
name	string	否	新备注名
active	boolean	否	启用/禁用

响应 200

{ "ok": true }

DELETE /api/keys/:key 删除密钥

路径参数

参数	说明
key	要删除的完整 Key 值

响应 200

{ "ok": true }

集成示例

典型验证码获取流程

// 1. 创建邮箱（自动选择最优渠道，避开 twitter.com 封禁的域名）
const inbox = await fetch('/api/inbox', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ for: 'twitter.com' })
}).then(r => r.json());
// → { id: "aBcDeFgHiJkL", address: "random@domain.com", ... }

// 2. 用 inbox.address 去目标服务注册/验证

// 3. 等待并提取验证码
const code = await fetch(`/api/inbox/${inbox.id}/code?wait=true&timeout=60`)
  .then(r => r.json());
// → { codes: [{ type: "numeric", value: "483921", confidence: 0.95 }] }

// 4. 上报结果（帮助调度器学习）
await fetch(`/api/inbox/${inbox.id}/report`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ success: true })
});

// 5. 关闭邮箱
await fetch(`/api/inbox/${inbox.id}`, { method: 'DELETE' });

cURL 快速测试

# 创建邮箱
curl -X POST http://localhost:3100/api/inbox \
  -H "Content-Type: application/json" \
  -d '{"for":"twitter.com"}'

# 等待验证码
curl "http://localhost:3100/api/inbox/YOUR_ID/code?wait=true&timeout=30"

# 指定 Outlook 渠道
curl -X POST http://localhost:3100/api/inbox \
  -H "Content-Type: application/json" \
  -d '{"provider":"outlook"}'

# 导入 Outlook 账号
curl -X POST http://localhost:3100/api/outlook/import \
  -H "Content-Type: application/json" \
  -d '{"accounts":"user@outlook.com----pass123----clientid----token"}'

总账号

-

可用

-

已分配

-

有效令牌

-

导入账号

闪客云购买

卡密

API 地址

类型

数量

账号列表

	邮箱	类型	令牌状态	分配状态	分组	续期时间	操作

总 Key

-

可用

-

无效

-

创建邮箱数

-

导入 API Key

API Key 列表

	API Key	备注	Wildcard	创建数	最后使用	状态	操作

仪表盘

收件箱

封禁表

渠道管理

密钥管理

API 文档

认证方式

错误处理

邮箱管理

封禁管理

渠道管理

Outlook 账号池

密钥管理

集成示例

典型验证码获取流程

cURL 快速测试

Outlook 账号池

YYDS Mail