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	否	指定域名
subdomain	string	否	泛子域名前缀（仅 YYDS 渠道），如 `team-a` → `user@team-a.example.com`
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, ... }
}

自动调度会按 Trust、限流状态、已封禁域名等综合评分选择最优渠道。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": "code", "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" }
}

上报失败会记录日志。若管理员配置了自动封禁规则（如「某服务失败 3 次/24h 自动封禁」），达到阈值时域名会被自动封禁。

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）。每个渠道可独立启用/禁用和调整优先级。

池化渠道说明
Outlook：1:1 账号分配模式，每个邮箱独占一个 Outlook 账号，关闭后账号回池。容量 = 空闲账号数。
YYDS Mail：多 API Key 池化模式（X-API-Key 认证），支持固定域名和泛子域名（wildcard）。每个 key 每日 20,000 次 API 调用配额，按 key 轮转分摊负载。邮件 24 小时自动删除。上游 API 文档：maliapi.215.im/v1/llms.txt

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	否	调度优先级（越高越优先）
autoDispatch	boolean	否	是否参与自动调度（付费渠道默认关闭，需显式指定 `provider` 才使用）

响应 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。

YYDS Mail 池

YYDS Mail 是池化渠道：通过多个 API Key 调用上游 YYDS Mail API 创建临时邮箱。支持固定域名和泛子域名（wildcard），每个 Key 每日 20,000 次调用配额。所有 YYDS 管理接口仅限管理员调用。

GET /api/yyds/stats Key 池统计

响应 200

{
  "total": 10,
  "active": 8,
  "invalid": 2,
  "totalInboxes": 156
}

POST /api/yyds/import 批量导入 API Key

请求体 (JSON)

参数	类型	必填	说明
accounts	string	是	每行一个 Key，格式：`API-KEY----备注名`（`----` 分隔）

响应 200

{
  "imported": 5,
  "duplicated": 2,
  "skipped": 0,
  "errors": []
}

已存在的 Key 会被跳过（INSERT OR IGNORE）。备注名可选。

GET /api/yyds/accounts 列出所有 Key

响应 200

{
  "accounts": [
    { "api_key": "AC-xxxx...", "name": 主力Key,
      "status": "active", "supports_wildcard": 1,
      "inbox_count": 42, "daily_calls": 1500,
      "last_used_at": "...", "created_at": "..." }
  ]
}

DELETE /api/yyds/accounts 批量删除 Key

请求体 (JSON)

参数	类型	必填	说明
keys	string[]	是	要删除的 API Key 数组

响应 200

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

POST /api/yyds/check 验证 Key 有效性

请求体 (JSON)

参数	类型	必填	说明
keys	string[]	否	指定检测的 Key，不填则检测全部

响应 200

{
  "checked": 10,
  "valid": 8,
  "invalid": 2,
  "results": [{ "key": "AC-xxxx", "valid": true }, ...]
}

通过向上游 API 发送探测请求来判断 Key 是否仍然有效，结果同步更新到数据库 status 字段。

PATCH /api/yyds/accounts/wildcard 设置 Wildcard 支持

请求体 (JSON)

参数	类型	必填	说明
keys	string[]	是	要设置的 API Key 数组
wildcard	boolean	否	是否支持泛子域名，默认 `false`

响应 200

{
  "updated": 3,
  "wildcard": true
}

通常不需要手动设置。系统会在创建邮箱时自动探测 Key 是否支持 wildcard，并记录结果（supports_wildcard 字段：null=未知, 0=不支持, 1=支持）。

IMAP 域名邮箱

通过 IMAP 连接你自己的域名邮箱，利用 catch-all 机制生成随机收件地址。添加账号后，在创建邮箱时指定 provider: "imap" 即可通过自己的域名收验证码。所有 IMAP 管理接口仅限管理员调用。

GET /api/imap/stats 池统计

响应 200

{
  "total": 3,
  "active": 2
}

GET /api/imap/accounts 列出所有 IMAP 账号

响应 200

{
  "accounts": [
    { "id": "uuid", "host": "imap.gmail.com",
      "port": 993, "user": "me@gmail.com",
      "domain": "mydomain.com", "tls": 1,
      "status": "active", "last_checked_at": "...",
      "created_at": "..." }
  ]
}

密码不会在列表或详情响应中返回。

GET /api/imap/accounts/:id 查看单个 IMAP 账号详情

响应 200

{
  "account": {
    "id": "uuid", "host": "imap.gmail.com",
    "port": 993, "user": "me@gmail.com",
    "domain": "mydomain.com", "tls": 1,
    "status": "active"
  }
}

POST /api/imap/accounts 添加 IMAP 账号

请求体 (JSON)

参数	类型	必填	说明
host	string	是	IMAP 服务器地址
port	number	否	端口，默认 993
user	string	是	邮箱用户名
password	string	是	邮箱密码或应用专用密码
domain	string	是	收件域名（需开启 catch-all）
tls	boolean	否	是否启用 TLS，默认 true

响应 201

{
  "account": {
    "id": "uuid", "host": "imap.gmail.com",
    "port": 993, "user": "me@gmail.com",
    "domain": "mydomain.com", "tls": 1,
    "status": "active"
  }
}

PUT /api/imap/accounts/:id 更新 IMAP 账号

请求体 (JSON)

所有字段均可选，只更新传入的字段。

参数	类型	必填	说明
host	string	否	IMAP 服务器地址
port	number	否	端口
user	string	否	邮箱用户名
password	string	否	邮箱密码
domain	string	否	收件域名
tls	boolean	否	是否启用 TLS
status	string	否	状态：active / inactive

响应 200

{ "ok": true }

DELETE /api/imap/accounts/:id 删除 IMAP 账号

响应 200

{ "ok": true }

删除账号不会影响已有的收件箱记录，但那些收件箱将无法继续拉取邮件。

POST /api/imap/accounts/:id/test 测试 IMAP 连接

响应 200

{
  "ok": true
}

{
  "ok": false,
  "error": "connect ECONNREFUSED"
}

测试连接会尝试打开 INBOX，成功后更新 last_checked_at 时间戳。

密钥管理

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

POST /api/keys 创建新密钥

请求体 (JSON)

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

响应 201

{
  "key": "mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "keyHash": "a1b2c3d4...",
  "name": API Key,
  "callCount": 0,
  "lastUsedAt": null,
  "active": true
}

创建时返回明文 Key（mk_ 前缀），之后仅可通过列表接口查看。keyHash 用于后续更新/删除操作。

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

响应 200

{
  "keys": [
    { "key": "mk_aBcDeFgH...", "keyHash": "a1b2c3d4...",
      "name": API Key, "callCount": 42,
      "lastUsedAt": "2025-01-01T12:00:00",
      "createdAt": "...", "active": true }
  ]
}

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

请求体 (JSON)

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

响应 200

{ "ok": true }

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

路径参数

参数	说明
keyHash	密钥哈希值（从列表接口获取）

响应 200

{ "ok": true }

集成示例

典型验证码获取流程

// 1. 创建邮箱（自动选择最优渠道，避开封禁域名）
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. 用邮箱地址去目标服务注册/验证

// 3. 等待并${t('inbox.extract')}code
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. Close inbox
await fetch(`/api/inbox/${inbox.id}`, { method: 'DELETE' });

cURL 快速测试

# Create inbox
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"}'

AI / LLM 集成

提供 llms.txt 端点，让 AI 助手（如 ChatGPT、Claude）快速理解公开集成面与认证方式，帮助您编写接入代码。

GET /v1/llms.txt 获取 AI 可读的 API 摘要（无需认证）

返回一份纯文本格式的公开 API 摘要，供 AI/LLM 快速理解外部可集成端点和认证方式。该端点无需认证，可直接访问。

响应 200 (text/plain)

# Mail Hub — Temporary Email Aggregation API
> Version: 0.9

## Authentication
Authorization: Bearer <your-api-key>

## Typical Workflow
1. POST   /api/inbox          → Create inbox
2. GET    /api/inbox/:id/code → Extract verification code
3. POST   /api/inbox/:id/report → ⚠️ REPORT (MANDATORY!)
4. DELETE /api/inbox/:id      → Close inbox
... (完整端点文档，含参数与响应格式)

使用方式：在与 AI 助手对话时，告诉它读取此端点即可快速理解 Mail Hub 的全部公开 API。例如：

在新标签页打开

总账号

-

可用

-

已分配

-

有效令牌

-

Report failure时记录已用服务关闭后，仅在Reported success时记录 Outlook 账号的已用服务

导入账号

账号列表

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

总 Key

-

可用

-

无效

-

Created inbox数

-

导入 API Key

API Key 列表

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

总账号

-

活跃

-

添加 IMAP 账号

主机

端口

用户名

密码

域名

TLS

账号列表

	主机	端口	用户名	域名	状态	TLS	最后检测	操作

数据库备份

自动备份

间隔 (小时)

保留数量

数据保留

活动日志保留天数

失败日志保留天数

已Close inbox保留天数

备份列表

文件名	大小	时间	操作

出站代理

Proxy URL

留空则直连。支持 HTTP/SOCKS5 代理。设置后所有上游请求经代理出站。

系统信息

Loading...

快捷键

Loading...

名称	标识	API Base	等级	状态	操作

输入

Gmail 用户名（@gmail.com 之前的部分）

生成数量

基于 Gmail 点不敏感 + 后缀 + googlemail.com 等价域特性，生成的别名都会进入同一个原始信箱。

生成规则

点击卡片切换

生成结果

仪表盘

收件箱

封禁表

目标服务

渠道管理

密钥管理

API 文档

认证方式

错误处理

邮箱管理

封禁管理

渠道管理

Outlook 账号池

YYDS Mail 池

IMAP 域名邮箱

密钥管理

集成示例

典型验证码获取流程

cURL 快速测试

AI / LLM 集成

Outlook 账号池

YYDS Mail

IMAP 域名邮箱

系统设置

自定义渠道

Gmail 别名生成器