仪表盘
加载中…活跃渠道
-
活跃邮箱
-
封禁规则
-
追踪服务
-
创建邮箱
最近邮箱
| 地址 | 渠道 | 目标 | 状态 | 时间 | 操作 |
|---|
最近动态
加载中…
收件箱
创建邮箱
邮箱列表
| 地址 | 渠道 | 目标 | 状态 | 过期时间 | 操作 |
|---|
封禁表
添加封禁
封禁列表
| 服务 | 域名 | 渠道 | 封禁时间 | 原因 | 操作 |
|---|
渠道管理
密钥管理
管理员 创建密钥
密钥列表
| 备注 | Key | 调用次数 | 最后使用 | 状态 | 操作 |
|---|
API 文档
REST API
Base URL:
/api
认证方式
所有 /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"}'
Outlook 账号池
加载中…总账号
-
可用
-
已分配
-
有效令牌
-
导入账号
闪客云购买
账号列表
| 邮箱 | 类型 | 令牌状态 | 分配状态 | 分组 | 续期时间 | 操作 |
|---|
YYDS Mail
加载中…总 Key
-
可用
-
无效
-
创建邮箱数
-
导入 API Key
API Key 列表
| API Key | 备注 | Wildcard | 创建数 | 最后使用 | 状态 | 操作 |
|---|