隐私邮箱外部取件 API v2

本服务提供两种取件方式：只读 IMAPS，以及支持等待新验证码和读取历史的 HTTP API。所有响应均可重复读取，不消费验证码，也不改变邮件已读状态。

验证码 API

使用完整 API Key：

curl -H "Authorization: Bearer API_KEY" https://HOST/api/v1/otp

管理端签发的取码 URL 会等待验证码，最近 5 分钟内已有验证码时立即返回，否则最长等待 20 秒：

https://HOST/api/v2/otp/wait?timeout=20&token=DERIVED_TOKEN

{"status":"received","otp":"123456","mail_time":"2026-08-26T20:00:00+08:00","synced_at":"2026-08-26T20:00:03+08:00"}

等待到期时返回 {"status":"waiting"}。等待期间同一主号最多每 2 秒触发一次合并同步；空闲账号仍使用普通轮询周期。

兼容历史接口仍可直接使用派生 token：

https://HOST/api/v1/otp?token=DERIVED_TOKEN

响应是最新优先的裸 JSON 数组，每个邮箱最多保留 100 条验证码：

[{"otp":"123456","time":"2026-08-11T12:00:00+08:00"}]

没有验证码时返回 200 []。

访问令牌

用服务签发的 client ID 与 refresh token 换取一小时有效的 IMAPS XOAUTH2 访问令牌：

curl -X POST https://HOST/oauth2/v2.0/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=CLIENT_ID" \
  --data-urlencode "refresh_token=REFRESH_TOKEN"

{"access_token":"ACCESS_TOKEN","token_type":"Bearer","expires_in":3600}

只读 IMAPS

连接部署方提供的 IMAPS 主机与端口，用户名为隐私邮箱地址。可直接使用服务签发的 IMAP 密码登录，也可使用上一步访问令牌进行 XOAUTH2 登录。

邮箱仅包含一个只读 INBOX，支持 LIST、STATUS、SELECT/EXAMINE、SEARCH、FETCH、UID FETCH 与 IDLE。写入、改旗标、移动和删除命令会返回只读错误。

API Key、IMAP 密码、client ID、refresh token 与 access token 都由本服务签发；轮换邮箱凭证后，旧凭证会同时失效。