API 文档 - iCloud 收件箱

GET`/api/code` — 获取邮件验证码

返回指定用户别名邮箱中最新一封邮件的验证码、发件人、主题和时间，无需登录网页，适用于自动化场景。

鉴权

复用 users.json 的用户名密码体系，支持两种方式：

# 方式一：查询参数
GET /api/code?username=xxx&password=xxx

# 方式二：Authorization Header（推荐）
GET /api/code
Authorization: Basic base64(username:password)

请求参数

参数	类型	默认	说明
`username`	string	-	用户名（未使用 Basic Auth 时必填）
`password`	string	-	密码（未使用 Basic Auth 时必填）
`minutes`	number	60	只搜索最近 N 分钟内的邮件（1-1440）
`digits`	number	6	验证码位数（4-10）
`from`	string	-	只匹配指定发件人地址，如 `noreply@example.com`
`wait`	boolean	false	为 `true` 时，若当前没有验证码则轮询等待最多 60 秒

响应（成功）

{
  "code": "932600",
  "from": "noreply@example.com",
  "subject": "Your verification code",
  "time": "2026-07-04T13:00:00Z"
}

若最新邮件中未匹配到验证码，code 为 null。

响应（时间范围内没有邮件）

{
  "code": null,
  "message": "No emails found in recent minutes"
}

示例请求

# 查询参数方式
curl "https://yourdomain.com/api/code?username=xxx&password=xxx"

# Basic Auth 方式
curl -u xxx:xxx "https://yourdomain.com/api/code"

# 等待新验证码（最多 60 秒），只看最近 10 分钟、指定发件人的 4 位验证码
curl -u xxx:xxx "https://yourdomain.com/api/code?wait=true&minutes=10&digits=4&from=noreply@example.com"

错误码说明

HTTP 状态码	说明
`200`	成功（`code` 为 `null` 时表示未找到验证码）
`401`	缺少用户名/密码，或用户名密码错误
`403`	该账户已被禁用
`500`	服务器错误（如 IMAP 连接失败、缺少 .env 配置）

GET`/api/page` — 可视化查看邮件

打开后直接显示最新一封邮件，无需登录网页；点击“查看所有邮件”即可切换到该用户可见的邮件列表。页面与 /api/code 使用同一套用户名、密码和收件人范围。

打开地址

https://yourdomain.com/api/page?username=xxx&password=xxx

页面只会显示当前用户可见的邮件，不会显示同一收件箱中其他收件人的邮件。

页面功能

功能	说明
最新邮件	打开页面后自动同步并展示最新一封邮件的主题、发件人、收件人、时间和正文。
所有邮件	点击页面内的切换按钮查看该用户范围内的邮件列表，按时间倒序分页。
邮件正文	点击列表中的邮件后查看 HTML 或纯文本正文。

页面数据接口

若需要在其他前端中集成，可以直接调用页面使用的数据接口：

GET /api/page/messages?username=xxx&password=xxx&page=1
GET /api/page/message/123?username=xxx&password=xxx

GET/api/code — 获取邮件验证码

鉴权