隐私邮箱外部取件 API v2

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

验证码 API

使用完整 API Key：

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

或直接访问签发的取码 URL：

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 都由本服务签发；轮换邮箱凭证后，旧凭证会同时失效。