隐私邮箱外部取件 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":"876543","time":"2026-08-11T12:00:00+08:00"},{"otp":"123456","time":"2026-08-11T11:00:00+08:00"}]

设置 ICLOUD_API_OTP_RETURN_LATEST_ONLY=true 后，有记录时只返回该数组第一项的裸 JSON 对象，也就是真正最新的有效 OTP。旧变量 ICLOUD_API_OTP_RETURN_LAST_ONLY 保留为兼容别名；同时设置时以正式变量为准。两种模式没有验证码时都返回 200 []。

邮件主题、纯文本和 HTML 可读文本中，只有未与字母或数字相邻的 6 位 ASCII 数字会被识别为验证码；升级前保存的其他格式历史值也不会出现在 OTP API 响应中。

访问令牌

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