HTTP JSON API,所有接口返回统一格式:
{
"success": true,
"data": {}
}失败响应:
{
"success": false,
"code": "VALIDATION_ERROR",
"message": "参数错误"
}稳定错误码: AUTH_REQUIRED、INVALID_CREDENTIALS、RATE_LIMITED、CSRF_INVALID、VALIDATION_ERROR、ACCOUNT_NOT_FOUND、OTP_REQUIRED、OTP_INVALID、UPSTREAM_UNAUTHORIZED、UPSTREAM_FAILURE、INTERNAL_ERROR
安全约定:
- 除
POST /api/auth/login与GET /api/auth/session外,所有/api接口都需要管理员会话 - 非 GET/HEAD/OPTIONS 请求必须携带
X-CSRF-Token请求头 - 会话 Cookie:
hme_session,Path=/、HttpOnly、SameSite=Strict;TLS 部署时设置ICLOUD_HME_SECURE_COOKIE=true启用Secure - 任何账号响应绝不包含
cookies、app_password、proxy字段(代理只暴露has_proxy布尔值) - 用户可见错误消息不拼接上游响应体或秘密
POST /api/auth/login
Content-Type: application/json
{"password": "管理员密码"}成功响应: 设置 hme_session Cookie
{
"success": true,
"data": {
"csrf_token": "随机值",
"expires_at": "2026-08-05T22:00:00+08:00"
}
}错误:
401 INVALID_CREDENTIALS— 密码错误(不设置 Cookie)429 RATE_LIMITED— 同一 IP 15 分钟内失败超过 5 次,响应带Retry-After头
GET /api/auth/session
Cookie: hme_session=...成功响应: 同上(csrf_token / expires_at)。会话无效返回 401 AUTH_REQUIRED。
POST /api/auth/logout
Cookie: hme_session=...
X-CSRF-Token: <token>
{"success": true, "data": {"logged_out": true}}GET /api/accounts响应: Summary[],排序为 active → pending → error,同状态按 name、id。
{
"success": true,
"data": [
{
"id": "acc_12345678",
"name": "主号",
"real_email": "owner@example.com",
"icloud_email": "owner@icloud.com",
"host": "icloud.com",
"status": "active",
"alias_total": 15,
"alias_active": 12,
"has_cookies": true,
"has_app_password": true,
"has_proxy": false,
"last_validated": "2026-08-04T09:00:00+08:00",
"status_message": "",
"created_at": "2026-08-01T09:00:00+08:00"
}
]
}cookies、app_password、proxy。status_message 只映射固定文案(pending → "等待配置或验证凭据",error → "凭据验证失败"),不返回内部错误原文。
POST /api/accounts
X-CSRF-Token: <token>
{
"name": "新账号",
"icloud_email": "owner@icloud.com",
"host": "icloud.com",
"proxy": "http://user:pass@host:port",
"cookies": "X-APPLE-WEBAUTH-TOKEN=abc; X-APPLE-WEBAUTH-USER=def"
}name必填,去空白后 1–64 字符icloud_email必填,net/mail校验且地址值必须等于输入host只能是icloud.com或icloud.com.cn(默认icloud.com)proxy可选,必须是http/https/socks5URLcookies可选,支持 Cookie Header 字符串或 JSON 文本- 无 Cookie 时状态为
pending,不访问网络
成功响应: 201,返回 Summary。
PATCH /api/accounts/:id
X-CSRF-Token: <token>
{"name": "新名称", "host": "icloud.com.cn"}只接受可选的 name、icloud_email、host,至少一个字段存在。响应返回更新后的 Summary。账号不存在返回 404 ACCOUNT_NOT_FOUND。
PUT /api/accounts/:id/proxy
X-CSRF-Token: <token>
{"proxy": "http://user:pass@host:port"}空字符串表示清除代理。响应只返回更新后的 Summary(代理值从不回显)。
PUT /api/accounts/:id/cookies
X-CSRF-Token: <token>
{"cookies": "a=1; b=2"}cookies 同时兼容字符串与对象:
{"cookies": {"a": "1", "b": "2"}}两种输入最终都交给 account.ParseCookieInput。响应只返回更新后的 Summary。
POST /api/accounts/:id/password
X-CSRF-Token: <token>
{"icloud_email": "your_email@icloud.com", "app_password": "xxxx-xxxx-xxxx-xxxx"}服务端会用 IMAP 连接验证凭据。成功返回 Summary;IMAP 验证失败返回 502 UPSTREAM_FAILURE。
POST /api/accounts/:id/login
X-CSRF-Token: <token>
{"password": "用户的常规iCloud密码", "otp_code": "123456"}otp_code可选,启用 2FA 时使用- 需要 OTP:
409 OTP_REQUIRED - 验证码错误:
401 OTP_INVALID - 成功:只返回
Summary,绝不返回 Cookies(Cookie 自动持久化到账号配置)
DELETE /api/accounts/:id
X-CSRF-Token: <token>响应: {"id": "acc_3"}。不存在返回 404 ACCOUNT_NOT_FOUND。
POST /api/create
X-CSRF-Token: <token>
{"account_id": "acc_1", "label": "注册某网站"}account_id必填label可选,最长 200 字符
响应:
{
"success": true,
"data": {
"email": "xyz123@icloud.com",
"label": "注册某网站",
"created_at": "2026-01-15T10:30:00+08:00",
"account_id": "acc_1"
}
}GET /api/inbox?account_id=acc_1&alias=xyz123@icloud.com&limit=20&days=7account_id必填alias可选,只返回发给该别名的邮件limit1–100(默认 20)days1–90(默认 7);非法整数直接400 VALIDATION_ERROR
响应(IMAP 优先,Web API 回退):
{
"success": true,
"data": {
"account_id": "acc_1",
"alias": "xyz123@icloud.com",
"count": 2,
"method": "imap",
"messages": [
{
"id": "1042",
"from": "GitHub <noreply@github.com>",
"to": "xyz123@icloud.com",
"subject": "[GitHub] Please verify your email address",
"date": "2026-07-09T14:32:10+08:00",
"preview": "Almost done! To finish setting up your account..."
}
]
}
}method 为 imap 或 web_api。IMAP 路径支持服务端按收件人搜索;Web API 路径拉取后本地过滤。
GET /api/aliases?account_id=acc_1响应: alias 对象字段风格为 camelCase(兼容 iCloud 原始格式):
{
"success": true,
"data": {
"account_id": "acc_1",
"count": 15,
"aliases": [
{
"email": "xyz123@icloud.com",
"anonymousId": "abc123",
"label": "注册某网站",
"active": true,
"createdAt": "2026-01-15T10:30:00Z"
}
]
}
}POST /api/aliases/:id/deactivate
POST /api/aliases/:id/reactivate
DELETE /api/aliases/:id
X-CSRF-Token: <token>
{"account_id": "acc_1"}:id为别名的anonymousId,非空且 URL 解码后不超过 256 字符account_id必填- 删除不可恢复;直接删除失败时会先停用再删
POST /api/reload
X-CSRF-Token: <token>重新读取 accounts.json。
BASE="http://localhost:8081"
# 1. 登录,保存 Cookie 到 jar
curl -c cookies.txt -X POST "$BASE/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"password":"你的管理员密码"}'
# 2. 从响应中提取 csrf_token(可用 jq)
CSRF=$(curl -b cookies.txt "$BASE/api/auth/session" | jq -r '.data.csrf_token')
# 3. 读取账号列表(GET 无需 CSRF)
curl -b cookies.txt "$BASE/api/accounts"
# 4. 添加账号(mutation 需要 CSRF
50BB
头)
curl -b cookies.txt -X POST "$BASE/api/accounts" \
-H "Content-Type: application/json" \
-H "X-CSRF-Token: $CSRF" \
-d '{"name":"新账号","icloud_email":"owner@icloud.com"}'
# 5. 创建别名
curl -b cookies.txt -X POST "$BASE/api/create" \
-H "Content-Type: application/json" \
-H "X-CSRF-Token: $CSRF" \
-d '{"account_id":"acc_1","label":"GitHub"}'
# 6. 读取邮件
curl -b cookies.txt "$BASE/api/inbox?account_id=acc_1&limit=10"用于创建/停用/激活/删除别名、读取邮件(Web API 回退)。
获取方式:
- 浏览器登录 icloud.com 或 icloud.com.cn (国区)
- F12 → Application → Cookies
- 导出 Cookie 为
{"key":"value"}JSON,粘贴到管理界面「更新 Cookie」
关键 Cookie: X-APPLE-WEBAUTH-TOKEN(认证 token)、X-APPLE-WEBAUTH-USER(含 dsid)、X-APPLE-WEBAUTH-HSA-TRUST(设备信任)、X-APPLE-DS-WEB-SESSION-TOKEN(会话)
有效期: 约 24 小时
用于 IMAP 读取邮件(优先路径,支持服务端按收件人搜索)。在 appleid.apple.com → 登录和安全 → App 专用密码 生成。
Web API 路径 (internal/mail/web_client.go):
- 调用
setup.icloud.com.cn/setup/ws/1/validate获取mccgatewayURL - 调用
mccgateway/mailws2/v1/thread/search读取邮件
validate返回的 mccgateway URL 可能带:443端口,tls-client 的 cookie jar 按不带端口的 host 存储 cookie,带端口请求时 cookie 无法附加导致 403;解决: 解析 URL 后剥离端口号
IMAP 路径 (internal/mail/client.go):标准 IMAP 协议,连接 imap.mail.me.com:993,需要 App Password。
升级差异(相对旧版):
- 全部 API 需要管理员登录(
401 AUTH_REQUIRED) - 账号响应不再返回 Cookie/密码/代理原文,改用
has_cookies/has_app_password/has_proxy POST /api/accounts/:id/login成功响应不再返回cookies字段accounts.json使用{"accounts": {id: {...}}}map wrapper 格式(参考accounts.json.template)
- 创建频率:iCloud 限制别名创建频率,过快会返回 429(服务端自动重试最多 5 次)
- Cookie 有效期:约 24 小时,需定期更新
- 邮件读取:依赖 IMAP 连接,超时默认 30 秒
- 请求体上限:1 MiB