✉

iCloud Hide My Email

验证码 API 服务

接码页面

API 接口文档

通过 API 获取 iCloud Hide My Email 邮箱的验证码。支持长轮询、批量查询、邮件原件查看等功能。

服务运行中 RESTful API JSON 响应

认证方式 公开

每个邮箱别名都有独立的 api_key（格式 alias_xxx）。在管理后台生成邮箱后获取。支持以下任一方式传递：
· query 参数 ?key=alias_xxx，或凭据格式 ?email=邮箱----alias_xxx
· 请求头 X-API-Key: alias_xxx 或 Authorization: Bearer alias_xxx
统一入口：任意节点的 Key 均可直接走根路径（如 /api/v1/code），无需节点前缀。管理员使用 adm_xxx 可访问所有邮箱。

公开接口 用户可用

GET /api/v1/health 健康检查 ▶
说明
检查服务是否正常运行，无需认证。
示例
# 检查服务状态 curl https://icloud.xbovo.online/api/v1/health
响应
// 200 OK {"ok": true, "service": "icloud-code-api", "status": "running"}
GET /api/v1/code?key=xxx 获取最新验证码 ▶
说明
只需 API Key 即可获取该邮箱最新验证码；后台实时同步器持续收件，必要时可加 sync=1 触发一次请求级同步。
参数
keystring必填邮箱的 API Key
emailstring邮箱地址（有 key 时可省略）
afterepoch仅返回此时间之后的验证码
max_age_secondsint有效窗口，默认 3600；传 0 可返回任意历史验证码
allow_stalebool没有新码时是否返回过期旧码，并标记 stale=true
syncbool请求时先触发一次同步；默认关闭，适合排查取码延迟
示例
# 用 API Key 获取验证码（推荐） curl https://icloud.xbovo.online/api/v1/code?key=alias_xxx # 指定邮箱 + Key curl https://icloud.xbovo.online/api/v1/code?email=test@icloud.com&key=alias_xxx
响应
// 200 OK — 有验证码 {"ok": true, "code": "123456", "email": "test@icloud.com", "mail": {"from": "noreply@example.com", "subject": "Your code", ...}, "fetched_at": "2026-07-05T14:13:15+00:00"} // 200 OK — 暂无新验证码，但会返回诊断信息 {"ok": true, "code": "", "mail": null, "email": "test@icloud.com", "lookup_status": "no_recent_code", "lookup": {"source": "qq-icloud4", "last_code": "123456", ...}}
GET /api/v1/code/wait?key=xxx&timeout=60 长轮询等待验证码 ▶
说明
持续轮询直到收到新验证码或超时。适合需要实时获取验证码的场景。
参数
keystring必填邮箱的 API Key
timeoutint等待秒数，默认 60，范围 5-120
intervalint轮询间隔秒数，默认 5，范围 2-15
excludestring排除已用验证码，逗号分隔如 123456,654321
afterepoch只等这个时间之后的新验证码
max_age_secondsint有效窗口，默认 3600
allow_stalebool超时时可返回旧码诊断/旧码
示例
# 长轮询 60 秒，排除已用的 123456 curl https://icloud.xbovo.online/api/v1/code/wait?key=alias_xxx&timeout=60&exclude=123456
响应
// 收到验证码 {"ok": true, "code": "654321", "email": "test@icloud.com", "timeout": false, "attempts": 3, "waited_seconds": 12} // 超时未收到 {"ok": true, "code": "", "mail": null, "timeout": true, "attempts": 12}
POST /api/v1/code POST 方式获取验证码（支持长轮询） ▶
说明
POST JSON 方式，参数更灵活。设置 timeout > 0 时自动长轮询。
请求体
{ "key": "alias_xxx", // 必填 "email": "test@icloud.com", // 可选，有 key 时可省略 "exclude": ["123456"], // 排除已用验证码 "after": 0, // epoch 时间戳 "max_age_seconds": 3600, "allow_stale": false, "sync": false, "timeout": 30, // >0 时长轮询 N 秒 "interval": 5 // 轮询间隔 }
示例
curl -X POST https://icloud.xbovo.online/api/v1/code \ -H "Content-Type: application/json" \ -d '{"key":"alias_xxx","exclude":["123456"],"timeout":30}'
POST /api/v1/key/rotate 自助更换邮箱 API Key ▶
说明
使用当前完整凭据自助更换该邮箱的 API Key。默认随机生成新 Key，也可传 new_key 指定新 Key。换成功后旧 Key 立即失效。
请求体
{ "credential": "test@icloud.com----alias_old_xxx", // 必填，完整凭据 "new_key": "alias_custom_xxx" // 可选，不传则随机生成 }
new_key 规则
前缀string必须以 alias_ 开头
长度int总长度 16-128
字符set只允许字母、数字、下划线、短横线，且不能和已有 Key 重复
示例
# 随机更换 Key curl -X POST https://icloud.xbovo.online/api/v1/key/rotate \ -H "Content-Type: application/json" \ -d '{"credential":"test@icloud.com----alias_old_xxx"}' # 指定新 Key curl -X POST https://icloud.xbovo.online/api/v1/key/rotate \ -H "Content-Type: application/json" \ -d '{"credential":"test@icloud.com----alias_old_xxx","new_key":"alias_custom_xxx_123"}'
响应
// 200 OK { "ok": true, "email": "test@icloud.com", "api_key": "alias_new_xxx", "credential": "test@icloud.com----alias_new_xxx", "rotated_at": "2026-08-03T12:00:00+08:00", "mode": "random" }
GET /api/v1/messages?key=xxx 列出邮件 ▶
参数
keystring必填API Key
emailstring邮箱地址
limitint返回条数，默认 20，范围 1-100
示例
curl https://icloud.xbovo.online/api/v1/messages?key=alias_xxx&limit=10
GET /api/v1/message/raw?key=xxx&id=123 查看邮件原件 ▶
说明
返回邮件完整 HTML 内容、纯文本、原始 headers。
参数
keystring必填API Key
emailstring邮箱地址
idint必填邮件 ID
示例
curl https://icloud.xbovo.online/api/v1/message/raw?key=alias_xxx&id=123
POST /api/v1/messages/delete 删除邮件（仅本地缓存） ▶
说明
删除本地缓存的邮件记录，不影响 iCloud 邮箱中的原始邮件。仅能删除属于该 API Key 对应邮箱的邮件。
请求体
{ "key": "alias_xxx", // 必填 "email": "test@icloud.com", // 可选 "ids": [1, 2, 3] // 必填，邮件 ID 列表 }
示例
curl -X POST https://icloud.xbovo.online/api/v1/messages/delete \ -H "Content-Type: application/json" \ -d '{"key":"alias_xxx","ids":[1,2,3]}'
响应
// 200 OK {"ok": true, "deleted": 3}

代码示例

JS JavaScript / 浏览器 ▶
// 获取验证码 const res = await fetch("/api/v1/code?key=alias_xxx"); const data = await res.json(); if (data.code) console.log("验证码:", data.code); // 长轮询等待验证码 const wait = await fetch("/api/v1/code/wait?key=alias_xxx&timeout=60"); const result = await wait.json(); if (result.code) console.log("收到:", result.code); else console.log("超时");
PY Python ▶
import requests API = "https://icloud.xbovo.online" KEY = "alias_xxx" # 获取验证码 r = requests.get(f"{API}/api/v1/code", params={"key": KEY}) data = r.json() print(data["code"] or "暂无验证码") # 长轮询等待验证码（排除已用） r = requests.get(f"{API}/api/v1/code/wait", params={"key": KEY, "timeout": 60, "exclude": "123456"}) data = r.json() if data.get("code"): print(f"收到验证码: {data['code']}") else: print("超时未收到")
PY Python（POST + 长轮询） ▶
import requests r = requests.post("https://icloud.xbovo.online/api/v1/code", json={"key": "alias_xxx", "timeout": 30, "exclude": ["123456"]}) data = r.json() print(data.get("code", ""))

接码页面 · iCloud Hide My Email API