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`），用于避开已封禁的域名。缺失返回 `400`
provider	string	否	指定渠道名（如 `mailtm`、`outlook`），不填则自动调度
domain	string	否	指定域名
subdomain	string	否	泛子域名前缀（仅 YYDS 渠道），如 `team-a` → `user@team-a.example.com`
alias	boolean	否	要一个子地址别名（`账号+标签@域名`）。标签由服务端生成，不要自己传。仅 Outlook 支持，其他渠道忽略——请以响应里的 `address` 为准
duration	number	否	邮箱有效时长（秒），最小 60，最大 30 天；到期自动关闭并释放资源
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`
since	string/number	否	只提取此时间之后收到的新邮件，支持 ISO 时间或毫秒时间戳

响应 200

{
  "codes": [
    { "type": "numeric", "value": "483921",
      "confidence": 0.95, "context": 您的验证码是 483921 }
  ],
  "email": { "from": "...", "subject": "..." },
  "messageId": "message-123",
  "receivedAt": "2025-01-01T00:01:00Z"
}

典型集成方式：先 POST /api/inbox 创建邮箱 → 用邮箱注册目标服务 → GET /api/inbox/:id/code?wait=true&timeout=60 等待验证码。需要多次取件时，把上次响应的 receivedAt 作为 since 传入，避免重复返回同一封邮件。

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,
  "pendingOAuth": 2,
  "noToken": 0
}

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

请求体 (JSON)

参数	类型	必填	说明
accounts	string	是	每行一个账号，支持：`邮箱----密码` 或 `邮箱----密码----ClientID----refresh_token`。

响应 200

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

分隔符为 ----（4 个减号）。未完成授权的账号会进入待授权状态，可在账号列表中补全。已存在的邮箱会被跳过（INSERT OR IGNORE）。

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

查询参数

参数	类型	必填	说明
status	string	否	令牌状态：`valid`、`invalid`、`pending_oauth`、`no_token`
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": "..." }
  ]
}

GET /api/outlook/accounts/:email/mailbox 查看账号邮箱的全部邮件

查询参数

参数	类型	必填	说明
limit	number	否	取回的邮件条数，默认 50，最大 100

响应 200

{
  "email": "user@outlook.com", "limit": 50, "truncated": false,
  "messages": [
    { "id": "...", "from": "...", "subject": "...", "receivedAt": "...",
      "leaseId": "i-abc123", "leaseState": "lease" }
  ],
  "leases": [
    { "id": "i-abc123", "address": "user+tag@outlook.com", "targetService": "github",
      "createdAt": "...", "endedAt": null, "status": "active" }
  ]
}

管理员专用。/api/inbox/:id/messages 只返回该邮箱在这一次租期内收到的邮件，这条接口返回整个账号邮箱。每封邮件带 leaseState：lease（属于 leaseId 那次租期）、gap（两次租期之间，账号空闲）、before（第一次租期之前）、undated（没有可解析的时间）。limit 是硬上限而不是分页：更早的邮件取不回来，取满时 truncated 为 true。

GET /api/outlook/accounts/:email/mailbox/:messageId 读取账号邮箱中的一封邮件

响应 200

{
  "id": "...", "from": "...", "subject": "...",
  "receivedAt": "...", "text": "...", "html": "..."
}

管理员专用，不受租期限制。/api/inbox/:id/messages/:mid 对租期外的邮件返回 404，这条接口能打开它们。

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 }
  ]
}

检测原理：使用已保存的授权凭据向 Microsoft 验证，成功即有效。会同步更新数据库中的 token_status 字段。

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

请求体 (JSON)

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

响应 200

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

续期会刷新已保存的授权凭据。Microsoft 授权有有效期，建议定期续期。续期成功后 token_status 自动更新为 valid。

POST /api/outlook/oauth/start 创建授权补全会话

请求体 (JSON)

{
  "email": "user@outlook.com",
  "preset": "thunderbird"
}

响应 200

{
  "sessionId": "...",
  "authorizeUrl": "https://...",
  "email": "user@outlook.com",
  "preset": "thunderbird",
  "redirectUri": "https://localhost",
  "serverProxyConfigured": true,
  "status": "pending"
}

默认使用内置授权预设；自定义 OAuth App 仍可通过 API 传入 custom 配置。

POST /api/outlook/oauth/code 提交授权回跳结果

请求体 (JSON)

{
  "sessionId": "...",
  "finalUrl": "https://localhost/?code=...&state=..."
}

响应 200

{
  "ok": true,
  "sessionId": "...",
  "email": "user@outlook.com",
  "status": "completed"
}

也可以提交 code + state。敏感令牌只写入服务端，不会在响应中返回。

GET /api/outlook/oauth/status/:sessionId 查询授权补全状态

响应 200

{
  "sessionId": "...",
  "email": "user@outlook.com",
  "preset": "thunderbird",
  "status": "completed",
  "error": ""
}

POST /api/outlook/oauth/password 读取待补全账号密码

请求体 (JSON)

{ "sessionId": "..." }

响应 200

{ "email": "user@outlook.com", "password": "..." }

管理员接口，仅用于 pending/no_token 账号的授权补全辅助，不返回任何令牌。

GET /api/outlook/oauth/callback 自定义 OAuth 回调

仅用于自定义 OAuth App 兼容流程。默认补全路径使用外部回跳 URL 提交接口。

POST /api/outlook/oauth/automation/claim 领取待补全任务

请求体 (JSON)

{ "preset": "thunderbird", "includeProxy": true, "includeFailed": false }

默认跳过带有 oauth_last_error 的失败账号；只有明确重试失败任务时才传 includeFailed: true。

响应 200

{
  "sessionId": "...",
  "authorizeUrl": "https://...",
  "email": "user@outlook.com",
  "redirectUri": "https://localhost",
  "serverProxyConfigured": true,
  "proxyUrl": "http://user:pass@host:port",
  "status": "pending"
}

POST /api/outlook/oauth/automation/password 读取已领取任务密码

请求体 (JSON)

{ "sessionId": "..." }

响应 200

{ "email": "user@outlook.com", "password": "..." }

管理员接口，仅用于外部自动化对已领取任务的安全取用。

POST /api/outlook/oauth/automation/report 上报自动化状态

请求体 (JSON)

{
  "sessionId": "...",
  "status": "waiting_user",
  "error": ""
}

状态可为 started、waiting_user、failed、completed。令牌写入仍由授权 code 提交流程完成。

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 机制为每个收件箱生成一个地址，再按收件人从共用邮箱里分拣，因此一个邮箱可同时支撑多个收件箱。生成的地址是人名形态（nathanlambert@、lisa.chen@、d_watson91@）而非随机字符串，已被占用的地址不会重复发放；传 username 可自己指定。添加账号后，在创建邮箱时指定 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 }

iCloud 别名

隐藏邮件是转发别名，不是信箱：Apple 没有按别名读信的 API。所以这个渠道分两半——签发地址走 Apple 私有接口，收信走「转发目标信箱」的 IMAP。转发目标常常不是 Apple 信箱（Apple ID 用 gmail 注册时就得连 imap.gmail.com）。需要 iCloud+ 订阅；一个 Apple ID 一辈子 750 个地址，所以地址回收复用而不是用完即弃。

GET /api/icloud/accounts 列出所有 Apple ID

响应 200

{
  "accounts": [
    { "id": "uuid", "apple_id": "me@gmail.com",
      "region": "global", "auth_mode": "srp",
      "imap_host": "imap.gmail.com", "imap_user": "me@gmail.com",
      "status": "active", "last_error": null }
  ]
}

status 三态：active 两半都通；degraded 会话过期，池里现有地址照常收信但不能签发新的；error 收信不可用，调度会跳过。Cookie、Apple ID 密码、信任令牌、IMAP 密码一律不返回。

POST /api/icloud/accounts 添加 Apple ID

请求体

{
  "appleId": "me@gmail.com",
  "region": "global",
  "cookies": "<整坨粘贴>",
  "imapUser": "me@gmail.com",
  "imapPassword": "<应用专用密码>",
  "imapHost": "imap.gmail.com",
  "imapPort": 993
}

cookies 接受浏览器给的任何形式：复制为 cURL（任意 shell）、复制为 PowerShell、Cookie 扩展导出的 JSON、或纯 Cookie 请求头。缺 X-APPLE-WEBAUTH-TOKEN 或 X-APPLE-WEBAUTH-USER 会直接 400 并指名缺哪个，而不是存下来等以后失败。

POST /api/icloud/accounts/:id/test 同时检测签发与收信两半

响应 200

{
  "ok": false,
  "forwardTo": "me@gmail.com",
  "forwardMismatch": null,
  "hmeError": null,
  "imapError": "authentication rejected: ..."
}

两半的错误分开返回，因为它们在不同地方修：Cookie 归 Apple 网页，IMAP 密码归收信邮箱的服务商。forwardTo 是隐藏邮件实际投递到的信箱，跟 IMAP 登录名不一致时 forwardMismatch 会直说。

POST /api/icloud/accounts/:id/cookies 就地更换过期 Cookie

保留地址池。删号重建会把它持有的每一个别名一起烧掉——每个都占 750 名额中的一个。

POST /api/icloud/accounts/:id/srp/begin SRP 登录，用信任令牌取代 Cookie

请求体

{ "password": "<Apple ID 密码>" }
→ { "sessionId": "...", "needsMfa": true }

随后

GET  /api/icloud/srp/:sessionId/phones      // 可选：手机号列表
POST /api/icloud/srp/:sessionId/sms         { "phoneId": 1 }
POST /api/icloud/accounts/:id/srp/complete  { "sessionId": "...", "code": "123456" }

Cookie 几小时过期，信任令牌能撑很久，所以 6 位码是每个 Apple ID 输一次而不是每次会话输一次。Apple 认可已存的信任令牌时 needsMfa 为 false，根本不推码。会话 5 分钟过期；握手中间态在内存里，这期间重启会丢失，重新登录即可。手边没有苹果设备时用 phones + sms 走短信。

POST /api/icloud/accounts/:id/generate 立刻生成地址（手动补货）

请求体

{ "count": 1 }   // 最多 5
→ { "created": 1, "addresses": ["quiet.fox42@icloud.com"] }

常规路径是后台自动补货，这个是应急用的。Apple 拒绝时原样返回它自己的措辞——它的错误分类没有公开文档，不做臆测的归类。自动补货的开关和目标值在 iCloud 页面上，或走 PATCH /api/admin/settings 的 icloud_pool_enabled / icloud_pool_target（目标值钳到 750）。

GET /api/icloud/addresses 地址池

state 三态：free 在池中可领用；assigned 被某个活着的 inbox 持有；retired 已在 Apple 侧停用、永不再发，它占的名额也永久花掉了。

GET /api/icloud/addresses/:hme/messages 按地址读信（含 /:uid 详情）

这个地址收到过的所有邮件，不像 /api/inbox/:id/messages 会隐藏比 inbox 更早的信。用来回答「这个地址到底收到过东西没有」。

POST /api/icloud/addresses/:hme/retire 停用被烧掉的地址

在 Apple 侧关闭转发并永不再分配。有 inbox 正持有时返回 409。它占的那个名额不会还回来——750 是一个 Apple ID 一辈子的总数。

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\\nuser2@outlook.com----pass123----clientid----refresh_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 账号的已用服务

导入账号

Thunderbird 授权补全

高级：自定义 OAuth（可选）

OAuth Client ID

Redirect URI

Scopes

Tenant

仅在需要非 Thunderbird 预设时使用。

账号列表

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

总 Key

-

可用

-

无效

-

Created inbox数

-

导入 API Key

API Key 列表

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

总账号

-

活跃

-

添加 IMAP 账号

主机

端口

用户名

密码

域名

TLS

账号列表

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

Apple ID

-

可用地址

-

已占用

-

添加 Apple ID

Apple ID

区域

收信邮箱

邮箱的应用专用密码

收信服务商

Cookie（整坨粘贴即可）

Apple ID 列表

Apple ID	状态	地址池	最后检测	操作

地址池

自动补货

地址	状态	使用	占用者	操作

数据库备份

自动备份

间隔 (小时)

保留数量

数据保留

活动日志保留天数

失败日志保留天数

已Close inbox保留天数

备份列表

文件名	大小	时间	操作

出站代理

Proxy URL

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

批量操作

批量并发数

Outlook/YYDS 批量检测、续期时的最大并发请求数。默认 5。

系��信息

Loading...

快捷键

Loading...

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

输入

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

生成数量

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

生成规则

点击卡片切换

生成结果

收件监控

捕获规则

仪表盘

收件箱

封禁表

目标服务

渠道管理

密钥管理

API 文档

认证方式

错误处理

邮箱管理

封禁管理

渠道管理

Outlook 账号池

YYDS Mail 池

IMAP 域名邮箱

密钥管理

集成示例

典型验证码获取流程

cURL 快速测试

AI / LLM 集成

Outlook 账号池

YYDS Mail

IMAP 域名邮箱

iCloud 别名

系统设置

自定义渠道

Gmail 别名生成器

邮箱收码系统

Mail Hub

收件监控

捕获规则

仪表盘

收件箱

封禁表

目标服务

渠道管理

密钥管理

API 文档

认证方式

错误处理

邮箱管理

封禁管理

渠道管理

Outlook 账号池

YYDS Mail 池

IMAP 域名邮箱

密钥管理

集成示例

典型验证码获取流程

cURL 快速测试

AI / LLM 集成

Outlook 账号池

YYDS Mail

IMAP 域名邮箱

iCloud 别名

系统设置

自定义渠道

Gmail 别名生成器