Outlook Manager 对外邮件 API v3.3.2

本文档供程序 / AI 对接使用。请严格按下方 硬性规则 实现，不要猜测其它邮件服务商的接口格式。

检测中... API Key — 读邮权限 —

0. 硬性规则（必读）

Base URL：https://weiruan.zmdsbk.com 。不要调用 emailmux 或其它第三方邮箱 API。
只使用 v1 路径：/api/v1/mail/...。不要混用未带 Key 的旧示例。
认证：每个邮件请求必须带 Header：X-API-Key: <key>（或 Authorization: Bearer <key>）。密钥在管理后台「API 对接」查看，不是文档里的占位符。
加号别名必须编码：路径中的 + 必须写成 %2B。例：user+tag@outlook.com → user%2Btag@outlook.com。
列表接口没有正文：GET /api/v1/mail/{email} 只返回 subject/sender/date/id。要验证码正文请再调 detail，或直接从 subject 解析（如 confirmation code: XXX-XXX）。
全局读邮权限：若后台设为 alias，只能查带 + 的别名，查根邮箱会 403；设为 root 则相反。
账户只需录入根邮箱：库里是 user@outlook.com；查询可用 user+tag@outlook.com，系统会映射并按收件人过滤。
不要用点号当地址变体注册：Outlook 不会像 Gmail 忽略点号；验证码场景请只用 + 别名。

1. 认证

X-API-Key: <API_KEY>

# 等价
Authorization: Bearer <API_KEY>

注意：运行时密钥保存在数据库，以管理后台「API 对接」显示的为准。环境变量 API_KEY 仅作首次种子；重置后请用新密钥。

2. 健康检查（无需密钥）

GET /api

响应含 version、auth.api_key_required、auth.api_read_scope。

3. 获取邮件列表（主接口）

GET /api/v1/mail/{email}?limit=20&folder=all&refresh=true

参数	位置	类型	默认	说明
email	path	string	—	根邮箱或 `+` 别名；`+`→`%2B`，`@` 一般可保留
limit	query	int	20	1–100
folder	query	string	all	`all` \| `inbox` \| `junk`
refresh	query	bool	false	`true` 跳过缓存，轮询验证码时建议 true

成功响应 200

{
  "email": "user+tag@outlook.com",
  "total": 1,
  "emails": [
    {
      "id": "INBOX-AAkALgAAAA...",
      "subject": "SpaceXAI confirmation code: 4ML-PWU",
      "sender": "SpaceXAI <noreply@x.ai>",
      "date": "2026-07-25T02:32:00Z",
      "folder": "INBOX"
    }
  ]
}

字段约定： emails 始终是数组（无邮件时为 []，不会是 null）。列表不含 content_text / HTML。

正确 curl（验证码轮询推荐）

curl -sS -H "X-API-Key: YOUR_API_KEY" \
  "https://weiruan.zmdsbk.com/api/v1/mail/cielobernhardtpq%2Bdjfmruy@outlook.com?limit=10&refresh=true"

4. 其它 v1 接口

方法	路径	说明
GET	`/api/v1/mail/{email}/latest/{count}`	最新 N 封（count=1–100），响应同列表
GET	`/api/v1/mail/{email}/inbox`	仅收件箱
GET	`/api/v1/mail/{email}/junk`	仅垃圾箱
GET	`/api/v1/mail/{email}/detail/{message_id}`	详情（含正文）；message_id 用列表里的 `id`，需 URL 编码

详情响应 200

{
  "id": "INBOX-AAkALgAAAA...",
  "subject": "SpaceXAI confirmation code: 4ML-PWU",
  "sender": "SpaceXAI <noreply@x.ai>",
  "recipient": "user+tag@outlook.com",
  "date": "2026-07-25T02:32:00Z",
  "content_text": ".... 4ML-PWU ....",
  "content_html": "<html>...</html>"
}

5. 验证码监听推荐流程（给 AI）

注册/发信目标地址使用加号别名：root+随机标签@outlook.com。
每 3–5 秒请求一次列表接口，refresh=true，limit=10。
在返回的 emails[].subject（及必要时 detail 的 content_text）中用正则提取验证码。
匹配到目标主题/发件人后停止轮询。

# 伪代码
email = "cielobernhardtpq+djfmruy@outlook.com"
path  = "/api/v1/mail/" + urlencode(email)   # 务必把 + 编成 %2B
GET base + path + "?limit=10&refresh=true"
Header: X-API-Key: <key>
解析 JSON.emails[].subject

6. 全局读邮权限 api_read_scope

在管理后台「API 对接」设置，对所有公开邮件 API 生效。

值	允许查询	禁止
`both`	根邮箱 + 别名	—
`root`	仅根邮箱	带 `+` 的别名 → 403
`alias`	仅别名（必须含 `+` 或点号别名）	直接查根邮箱 → 403

当前运行值见页面顶部徽章，或 GET /api → auth.api_read_scope。

7. 错误响应

{
  "detail": "人类可读说明",
  "code": "unauthorized | forbidden | not_found | bad_request | unavailable | error"
}

HTTP	code	常见原因
401	unauthorized	缺少/错误 API Key
403	forbidden	违反全局读邮权限（例如 alias 模式下查了根邮箱）
404	not_found	根邮箱未录入系统
503	unavailable	OAuth/微软令牌失败

8. 常见错误（AI 最容易踩）

把 + 原样放进 URL，未编成 %2B → 别名解析失败或查空。
全局 alias 时去查根邮箱 → 403，误以为“读不到信”。
在列表响应里找 body/content → 字段不存在，应看 subject 或调 detail。
调用 /emails/...（管理端）却只带 API Key → 应用管理员 Bearer 密码，不是对外接口。
文档占位符 your-api-key 未替换成真实密钥 → 401。
使用点号地址当 Outlook 别名发信 → 微软往往根本收不到信。

9. 兼容路径（不推荐）

仍可用但请优先 v1：/api/mail/...、/public/emails/{email}/unified。鉴权规则与 v1 相同。

10. 管理端（勿与对外 API 混淆）

范围	路径前缀	认证
对外读邮	`/api/v1/mail`	API Key
管理后台	`/accounts`、`/emails`	`Authorization: Bearer <ADMIN_PASSWORD>`