| # Temp Mail 域名池与外部注册 API 说明 |
|
|
| 本文档说明本项目最近新增/补强的两部分能力： |
|
|
| 1. `temp_mail` 邮箱服务支持域名池与 Worker 域名 API |
| 2. 外部调用方可通过 HTTP API 创建注册批次、查询状态、取消任务 |
|
|
| 配套文档： |
|
|
| - [External API 调用示例](external-api-examples.md) |
| - [External API 第三方对接速览](external-api-quickstart.md) |
| - [External API 网站内管理与 API Key 生成方案](external-api-webui-management-plan.md) |
|
|
| --- |
|
|
| ## 1. Temp Mail 域名池 |
|
|
| ### 1.1 适用场景 |
|
|
| 项目内新增了 `temp_mail` 邮箱类型，用于接入你自建的临时邮箱服务，例如： |
|
|
| - `https://apmail.889110.xyz/` |
|
|
| 服务端支持通过管理接口返回当前可用域名池，例如： |
|
|
| - `GET /admin/domains` |
|
|
| 请求头： |
|
|
| - `x-admin-auth: <admin_password>` |
|
|
| ### 1.2 支持的配置项 |
|
|
| `temp_mail` 服务配置支持以下字段： |
|
|
| | 字段 | 必填 | 说明 | |
| | --- | --- | --- | |
| | `base_url` | 是 | 临时邮箱服务地址，如 `https://apmail.889110.xyz` | |
| | `admin_password` | 是 | 管理接口密码，对应请求头 `x-admin-auth` | |
| | `domains` | 否 | 域名池，数组或逗号分隔字符串，优先级最高 | |
| | `domain` | 否 | 单个回退域名 | |
| | `enable_prefix` | 否 | 是否保留旧版 `tmp` 前缀，默认 `false` | |
| | `timeout` | 否 | 请求超时，默认 `30` | |
| | `max_retries` | 否 | 请求重试次数，默认 `3` | |
|
|
| ### 1.3 域名解析优先级 |
|
|
| 创建邮箱时，域名来源按以下优先级解析： |
|
|
| 1. `config.domains` |
| 2. Worker `GET /admin/domains` |
| 3. `config.domain` |
|
|
| 如果三者都拿不到可用域名，则创建邮箱失败。 |
|
|
| ### 1.4 随机邮箱生成规则 |
|
|
| - 默认生成**纯随机**本地名，不再强制 `tmp` 前缀 |
| - 如果配置 `enable_prefix=true`，则继续使用旧版 `tmpxxxxx` 风格 |
| - 最终会从当前可用域名池中随机选择一个域名拼接地址 |
|
|
| ### 1.5 可用服务展示 |
|
|
| 以下两个接口会展示 `temp_mail` 的域名摘要： |
|
|
| - Web UI: `GET /api/registration/available-services` |
| - 外部 API: `GET /api/external/capabilities` |
|
|
| 返回中会包含： |
|
|
| - `domain_count` |
| - `domains_preview` |
| - `domain_source` |
|
|
| 其中 `domain_source` 可能为： |
|
|
| - `config_domains` |
| - `worker_api` |
| - `config_fallback` |
| - `none` |
|
|
| > 注意：接口只暴露安全摘要，不会把 `admin_password` 等敏感信息返回给前端或外部调用方。 |
| |
| --- |
| |
| ## 2. 外部注册 API |
| |
| ### 2.1 功能概览 |
| |
| 外部 API 允许调用方不直接操作 Web UI，而是通过 HTTP 请求： |
| |
| - 查询当前可用邮箱类型与上传目标 |
| - 创建异步注册批次 |
| - 查询批次状态 |
| - 取消批次 |
| |
| ### 2.2 鉴权方式 |
| |
| 需要在系统设置中启用： |
| |
| - `external_api_enabled` |
| - `external_api_key` |
| |
| 请求头使用： |
| |
| ```http |
| X-API-Key: <your_api_key> |
| ``` |
| |
| 未启用时返回 `403`；密钥错误时返回 `401`。 |
| |
| ### 2.2.1 API Key 从哪里来 |
| |
| 当前项目里，外部 API Key 不是“调用方自己申请”的，也不是接口动态下发的。 |
| |
| 它来自系统管理员在项目配置中设置的： |
| |
| - `external_api_enabled` |
| - `external_api_key` |
| |
| 也就是说： |
| |
| 1. 管理员先在系统里启用外部 API |
| 2. 管理员在系统里填写一个 `external_api_key` |
| 3. 再把这个值发给第三方调用方 |
| |
| 第三方真正拿到的就是这个管理员配置的值，然后放到： |
| |
| ```http |
| X-API-Key: 你拿到的那个值 |
| ``` |
| |
| > 当前版本没有单独的“获取 API Key / 轮换 API Key”开放接口。 |
| > 如果要换 Key，需要由系统管理员修改配置后，再重新发给对接方。 |
| |
| ### 2.3 能力查询 |
| |
| 接口： |
| |
| ```http |
| GET /api/external/capabilities |
| ``` |
| |
| 用于返回： |
| |
| - 支持的邮箱类型 |
| - 当前可用邮箱服务 |
| - 当前可用上传目标 |
| - 外部 API 是否启用 |
| |
| 其中邮箱类型包含数据库内启用的： |
| |
| - `outlook` / `moe_mail` / `temp_mail` / `duck_mail` / `freemail` / `imap_mail` |
| |
| 其中临时邮箱能力在外部 API 中统一使用 `temp_mail` 枚举，不再暴露旧的 `tempmail` 占位。 |
|
|
| 能力接口返回的每个可选服务，都会带： |
|
|
| - `id` |
| - `name` |
| - `priority` |
|
|
| 对于 `temp_mail`，还会带： |
|
|
| - `domain_count` |
| - `domains_preview` |
| - `domain_source` |
|
|
| ### 2.3.1 service_id 不是 0/1 猜出来的 |
| |
| 第三方在创建批次时看到的： |
| |
| - `email.service_id` |
| - `upload.service_id` |
|
|
| 都不是让你自己猜 “0 代表哪个、1 代表哪个”。 |
|
|
| 正确方式是： |
|
|
| 1. 先调 `GET /api/external/capabilities` |
| 2. 读取返回里的服务列表 |
| 3. 按 `name` 找到你想用的服务 |
| 4. 把该服务对应的 `id` 填回创建请求里的 `service_id` |
|
|
| 也就是说，真正的映射关系来自 `capabilities` 返回值，而不是文档里写死。 |
|
|
| 例如能力返回里可能是： |
|
|
| ```json |
| { |
| "email_types": [ |
| { |
| "type": "temp_mail", |
| "services": [ |
| {"id": 3, "name": "Worker temp mail A"}, |
| {"id": 7, "name": "Worker temp mail B"} |
| ] |
| } |
| ], |
| "upload_providers": [ |
| { |
| "provider": "sub2api", |
| "services": [ |
| {"id": 1, "name": "sub2-main"}, |
| {"id": 4, "name": "sub2-backup"} |
| ] |
| } |
| ] |
| } |
| ``` |
|
|
| 那你在创建批次时： |
|
|
| - 传 `email.service_id=3`，表示使用 `Worker temp mail A` |
| - 传 `upload.service_id=4`，表示上传到 `sub2-backup` |
|
|
| > 结论：`service_id` 只认 `capabilities` 当前返回的 `id`，不要手写猜测，也不要假设某个数字永远对应某个服务。 |
| |
| ### 2.4 创建注册批次 |
| |
| 接口： |
| |
| ```http |
| POST /api/external/registration/batches |
| ``` |
| |
| 请求体示例： |
| |
| ```json |
| { |
| "count": 5, |
| "idempotency_key": "demo-batch-001", |
| "email": { |
| "type": "temp_mail", |
| "service_id": 1 |
| }, |
| "upload": { |
| "enabled": true, |
| "provider": "sub2api", |
| "service_id": 1 |
| }, |
| "execution": { |
| "mode": "pipeline", |
| "concurrency": 1, |
| "interval_min": 5, |
| "interval_max": 15 |
| } |
| } |
| ``` |
| |
| 字段约束： |
|
|
| - `count`: `1 ~ 100` |
| - `email.type`: 必填 |
| - `email.service_id`: 可选 |
| - `upload.provider`: 仅在 `upload.enabled=true` 时必填 |
| - `upload.provider`: 仅支持 `sub2api` / `cpa` / `tm` |
| - `execution.mode`: `pipeline` 或 `parallel` |
| - `execution.concurrency`: `1 ~ 50` |
| - `execution.interval_max >= execution.interval_min` |
|
|
| 关于 `service_id` 的默认行为： |
|
|
| - `email.service_id` 不传：系统按该邮箱类型的当前可用规则自动选 |
| - `upload.service_id` 不传：系统按该上传 provider 当前启用且优先级最高的服务自动选 |
|
|
| 返回规则： |
|
|
| - 首次创建成功：HTTP `202` |
| - 如果 `idempotency_key` 命中历史批次：HTTP `200` |
|
|
| ### 2.5 查询批次状态 |
|
|
| 接口： |
|
|
| ```http |
| GET /api/external/registration/batches/{batch_uuid} |
| ``` |
|
|
| 返回字段包含： |
|
|
| - `batch_uuid` |
| - `status` |
| - `requested_count` |
| - `completed_count` |
| - `success_count` |
| - `failed_count` |
| - `upload_success_count` |
| - `upload_failed_count` |
| - `failure_reason` |
| - `recent_errors` |
|
|
| 状态可能包括： |
|
|
| - `pending` |
| - `running` |
| - `completed` |
| - `completed_partial` |
| - `failed` |
| - `cancelled` |
|
|
| ### 2.6 取消批次 |
|
|
| 接口： |
|
|
| ```http |
| POST /api/external/registration/batches/{batch_uuid}/cancel |
| ``` |
|
|
| 规则： |
|
|
| - `pending` / `running` 可取消 |
| - 已结束批次不可重复取消，返回 `400` |
| - 批次不存在返回 `404` |
|
|
| ### 2.7 错误码约定 |
|
|
| | 场景 | 状态码 | |
| | --- | --- | |
| | API 未启用 | `403` | |
| | API Key 错误 | `401` | |
| | 请求体验证失败 | `422` | |
| | 批次不存在 | `404` | |
| | 业务参数不合法 | `400` | |
| | 外部批次服务不可用 | `503` | |
|
|
| --- |
|
|
| ## 3. 外部批次执行行为 |
|
|
| ### 3.1 持久化 |
|
|
| 外部批次及其子项会持久化到数据库： |
|
|
| - `external_registration_batches` |
| - `external_registration_batch_items` |
|
|
| 同时为每个子项生成独立 `registration_task_uuid`，便于复用现有注册执行链路。 |
|
|
| ### 3.2 幂等 |
|
|
| 如果创建批次时传入 `idempotency_key`，系统会优先复用已有批次，避免重复创建。 |
|
|
| ### 3.3 重启恢复 |
|
|
| 服务启动时会尝试恢复中断批次： |
|
|
| - `pending` / `running` 的外部批次会被标记为失败 |
| - 失败原因记为 `service_restarted` |
|
|
| 这样可以避免系统重启后外部调用方看到“永远卡在运行中”的脏状态。 |
|
|
| ### 3.4 上传行为 |
|
|
| 如果启用了上传： |
|
|
| - 注册成功后才会执行上传 |
| - 会优先按注册结果里的 `email` 查账号 |
| - 如找不到，再按 `account_id` 回退查找 |
| - 上传结果会分别统计成功数和失败数 |
|
|
| --- |
|
|
| ## 4. 当前测试覆盖 |
|
|
| 本轮功能已补充并验证以下覆盖： |
|
|
| - `temp_mail` 本地名生成与域名随机选择 |
| - `temp_mail` 域名解析优先级与回退逻辑 |
| - Worker 域名 API 集成路径 |
| - `available-services` / `capabilities` 的域名摘要展示 |
| - 外部 API 鉴权、参数校验、错误码映射 |
| - 外部批次创建、幂等、状态汇总、取消、重启恢复 |
| - 外部批次执行中的预失败项、上传成功/失败、`account_id` 回退查找 |
| - 服务选择的拒绝分支与边界约束 |
|
|
| 全量测试验证结果： |
|
|
| - `134 passed` |
|
|
| --- |
|
|
| ## 5. 使用建议 |
|
|
| ### 5.1 如果你想让 `temp_mail` 自动从多个域名中随机取 |
| |
| 建议只配置： |
| |
| - `base_url` |
| - `admin_password` |
| - `domain`（仅作回退） |
|
|
| 然后由 Worker `GET /admin/domains` 统一返回真实域名池。 |
|
|
| ### 5.2 如果你想固定只用部分域名 |
|
|
| 直接在该邮箱服务配置中填写： |
|
|
| ```json |
| { |
| "domains": ["a.example.com", "b.example.com"] |
| } |
| ``` |
|
|
| 此时系统会优先使用配置内域名池，而不会再请求 Worker 域名接口。 |
|
|
| ### 5.3 如果你要给第三方系统对接 |
|
|
| 优先使用： |
|
|
| - `GET /api/external/capabilities` |
| - `POST /api/external/registration/batches` |
| - `GET /api/external/registration/batches/{batch_uuid}` |
| - `POST /api/external/registration/batches/{batch_uuid}/cancel` |
|
|
| 这样调用方只负责“下发任务”和“查结果”，实际邮箱、上传、执行模式等策略仍由系统内配置统一兜底。 |
|
|
