iCloud Hide My Email 本地管理工具

English | 中文

通过逆向 iCloud Web 接口和 IMAP 邮件协议，实现 Apple iCloud 隐藏邮箱别名的创建、列出和邮件收取功能。

功能特性

✅ 创建 HME 别名 — 自动生成 iCloud 隐藏邮箱地址
✅ 列出所有别名 — 查看账号下的所有 HME 别名
✅ 收取邮件 — 通过 IMAP 或 Web API 读取发到 HME 别名的邮件
✅ 双路径读信 — 邮件读取优先走 IMAP (App Password),无 App Password 时回退 Web API (Cookie)
✅ 多账号管理 — 支持多个 iCloud 账号并行管理
✅ 双认证模式 — Cookie (创建别名 + 读邮件回退) 和 App Password (IMAP 优先)

快速开始

1. 安装

方式一：下载二进制发布版（推荐）

从 GitHub Releases 下载对应平台的二进制文件：

平台	文件
Linux x86_64	`icloud-hme_linux_amd64`
Linux ARM64	`icloud-hme_linux_arm64`
macOS Intel	`icloud-hme_darwin_amd64`
macOS Apple Silicon	`icloud-hme_darwin_arm64`
Windows x86_64	`icloud-hme_windows_amd64.exe`

# 示例：Linux 下直接运行
chmod +x icloud-hme_linux_amd64
./icloud-hme_linux_amd64

方式二：Docker

# 拉取镜像
docker pull ghcr.io/xiaozhou26/icloud-hme:latest

# 运行（将本机 data 目录挂载进去）
docker run -d \
  --name icloud-hme \
  -p 8081:8081 \
  -v /path/to/data:/app/data \
  ghcr.io/xiaozhou26/icloud-hme:latest

镜像支持 linux/amd64 和 linux/arm64 双架构，自动适配。

方式三：源码编译

# 前置要求: Go 1.26+
git clone https://github.com/xiaozhou26/icloud-hme.git
cd icloud-hme

# 编译
go build -o icloud-hme.exe .

# 调试模式（启用 Gin 请求日志）
./icloud-hme.exe -debug

2. 配置账号

在程序 data/ 目录下创建 accounts.json:

{
  "accounts": [
    {
      "id": "acc_1",
      "name": "主号",
      "host": "icloud.com",
      "cookies": {
        "X-APPLE-WEBAUTH-TOKEN": "token_value",
        "X-APPLE-WEBAUTH-USER": "v=1:s=1:d=22789132008",
        "X-APPLE-WEBAUTH-HSA-TRUST": "trust_value",
        "X-APPLE-DS-WEB-SESSION-TOKEN": "session_token"
      },
      "app_password": "xxxx-xxxx-xxxx-xxxx",
      "proxy": "http://user:pass@host:port"
    }
  ]
}

提示: 也可以通过 API 动态添加账号，无需手动编辑 JSON 文件。cookies 和 app_password 都是可选的，proxy 也是可选的。

3. 启动服务

# 二进制方式（默认 data 目录）
./icloud-hme_linux_amd64

# 指定端口和数据目录
./icloud-hme_linux_amd64 -addr :9090 -data ./my_data

# 调试模式（启用请求日志）
./icloud-hme_linux_amd64 -debug

# 查看完整参数
./icloud-hme_linux_amd64 -h

服务默认监听 :8081。

API 接口

核心接口

创建 HME 别名

POST /api/create

# 请求体
{
  "account_id": "acc_1",      # 必填: 账号 ID
  "label": "注册某网站"        # 可选: 别名标签
}

# 响应
{
  "success": true,
  "data": {
    "email": "xyz123@icloud.com",
    "label": "注册某网站",
    "created_at": "2024-01-15T10:30:00Z",
    "account_id": "acc_1"
  }
}

读取邮件

GET /api/inbox?account_id=acc_1&alias=xyz123@icloud.com&limit=20&days=7

# 参数说明:
#   account_id - 必填: 账号 ID
#   alias      - 可选: 只读取发到该别名的邮件
#   limit      - 可选: 返回邮件数量 (默认 20)
#   days       - 可选: 查找最近几天的邮件 (默认 7,仅 IMAP 模式)

# 响应
{
  "success": true,
  "data": {
    "account_id": "acc_1",
    "alias": "xyz123@icloud.com",
    "count": 2,
    "method": "imap",
    "messages": [
      {
        "id": "1042",
        "from": "noreply@example.com",
        "to": "xyz123@icloud.com",
        "subject": "欢迎注册",
        "preview": "感谢您的注册...",
        "date": "2026-07-09T14:32:10+08:00"
      }
    ]
  }
}

# 读取方式 (自动选择):
#   method: "imap"    — 通过 App Password 认证 (优先)
#   method: "web_api" — 通过 Cookie 认证,无需 App Password (回退)

账号管理接口

列出所有账号

GET /api/accounts

# 响应
{
  "success": true,
  "data": [
    {"id": "acc_1", "name": "主号"},
    {"id": "acc_2", "name": "副号"}
  ]
}

添加账号

简化版（cookies 可选）:

POST /api/accounts

# 请求体
{
  "name": "新账号",
  "host": "icloud.com",           # 可选
  "proxy": "http://..."           # 可选
}

# 响应 - 状态为 pending,需登录
{
  "success": true,
  "data": {
    "id": "acc_xxx",
    "name": "新账号",
    "status": "pending"
  }
}

完整版（带 Cookie）:

POST /api/accounts

# 请求体
{
  "name": "新账号",
  "cookies": "{\"x-apple-session-token\":\"token_value\"}",  # JSON 或 Header 格式
  "host": "icloud.com",           # 可选
  "proxy": "http://..."           # 可选
}

# 响应
{
  "success": true,
  "data": {
    "id": "acc_3",
    "name": "新账号",
    "status": "active"
  }
}

账号登录（获取 Cookie）

POST /api/accounts/:id/login

# 请求体
{
  "password": "用户的常规iCloud密码",  # 不是 App Password
  "otp_code": "123456"                  # 可选,2FA 验证码
}

# 响应
{
  "success": true,
  "data": {
    "id": "acc_1",
    "cookies": {
      "x-apple-session-token": "...",
      "X-APPLE-WEBAUTH-TOKEN": "..."
    }
  }
}

删除账号

DELETE /api/accounts/:id

# 响应
{
  "success": true,
  "data": {"id": "acc_3"}
}

设置 App Password

POST /api/accounts/:id/password

# 请求体
{
  "icloud_email": "your_email@icloud.com",
  "app_password": "xxxx-xxxx-xxxx-xxxx"
}

# 响应
{
  "success": true,
  "data": {
    "id": "acc_1",
    "icloud_email": "your_email@icloud.com"
  }
}

别名管理接口

列出所有别名

GET /api/aliases?account_id=acc_1

# 响应
{
  "success": true,
  "data": {
    "account_id": "acc_1",
    "count": 15,
    "aliases": [
      {
        "email": "xyz123@icloud.com",
        "label": "注册某网站",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

停用别名

POST /api/aliases/:id/deactivate

# 请求体
{
  "account_id": "acc_1"
}

# 响应
{
  "success": true,
  "data": {
    "anonymous_id": "abc123",
    "success": true
  }
}

激活别名

POST /api/aliases/:id/reactivate

# 请求体
{
  "account_id": "acc_1"
}

# 响应
{
  "success": true,
  "data": {
    "anonymous_id": "abc123",
    "success": true
  }
}

删除别名

DELETE /api/aliases/:id

# 请求体
{
  "account_id": "acc_1"
}

# 响应
{
  "success": true,
  "data": {
    "anonymous_id": "abc123"
  }
}

认证方式

方式一: Cookie 认证 (推荐,功能最完整)

Cookie 认证可实现所有功能:创建别名、读取邮件、管理别名。

适用范围:

创建/停用/激活/删除 HME 别名 ✅
读取邮件 (通过 iCloud Web API,无需 App Password) ✅

获取 Cookie:

使用浏览器登录 icloud.com 或 icloud.com.cn (国区)
打开浏览器开发者工具 (F12)
进入 Application → Cookies
导出全部 Cookie 为 {"key":"value"} 格式的 JSON

关键 Cookie (必需):

X-APPLE-WEBAUTH-TOKEN — 认证 token
X-APPLE-WEBAUTH-USER — 含 dsid (v=1:s=1:d=22789132008)
X-APPLE-WEBAUTH-HSA-TRUST — 设备信任 token
X-APPLE-DS-WEB-SESSION-TOKEN — 会话 token

注意: 导出的 Cookie 值不要包含多余的引号或转义字符。

方式二: App Password 认证 (IMAP,优先读邮件)

App Password 用于 IMAP 读取邮件,是邮件读取的优先路径 (支持服务端按收件人搜索)。

生成 App Password:

登录 appleid.apple.com
进入 "登录和安全" → "App 专用密码"
生成新密码,用于此工具

邮件读取双路径

GET /api/inbox 自动选择读取方式:

优先: IMAP (App Password) — 设置了 App Password 时使用,支持服务端按收件人 (TO) 搜索
回退: Web API (Cookie) — 无 App Password 或 IMAP 失败时,通过 mccgateway 端点读取,本地按别名过滤

响应中包含 "method": "web_api" 或 "method": "imap" 字段,标识实际使用的读取方式。

项目架构

icloud-hme/
├── main.go                 # 入口: 加载配置、初始化管理器、启动服务
├── accounts.json           # 账号配置文件 (自动生成)
├── go.mod
└── internal/
    ├── account/
    │   └── manager.go      # 多账号管理器 (持久化、客户端工厂)
    ├── hme/
    │   ├── client.go       # iCloud HME Web 客户端 (Cookie 认证)
    │   └── auth.go         # SRP 登录 (账号密码 + 2FA 获取 Cookie)
    ├── mail/
    │   ├── client.go       # IMAP 邮件客户端 (App Password 认证)
    │   └── web_client.go   # Web 邮件客户端 (Cookie 认证,无需 App Password)
    └── server/
        └── server.go       # HTTP API (Gin 路由 + 请求处理)

核心模块

account.Manager: 管理多个 iCloud 账号,负责配置持久化和客户端创建
hme.Client: 封装 iCloud HME Web API,支持 Cookie 认证
hme.auth: SRP 协议登录,支持账号密码 + 可选 2FA
mail.Client: IMAP 邮件客户端 (App Password,优先读邮件)
mail.WebClient: 通过 iCloud Web API (mccgateway) 读取邮件,无需 App Password
server.Server: HTTP API 服务,提供 RESTful 接口

技术栈

Go 1.26+
Gin — HTTP 框架
go-imap — IMAP 协议实现
tls-client — TLS 指纹模拟 (绕过 iCloud 反爬)

常见问题

Q: 创建别名返回 401/403 错误?

A: Cookie 已过期，需要重新获取。iCloud Cookie 有效期通常为 24 小时。

Q: 读取邮件返回超时?

A: 检查网络连接，确保可以访问 imap.mail.me.com:993。

Q: 如何查看某个别名收到了哪些邮件?

A: 调用 GET /api/inbox?account_id=acc_1&alias=your_alias@icloud.com

Q: 支持同时管理多个 iCloud 账号吗?

A: 支持，在 accounts.json 中配置多个账号即可，每个账号有独立的 id。

开发指南

本地开发

# 安装依赖
go mod download

# 运行 (开发模式，默认 :8081，带 Gin 请求日志)
go run main.go -debug

# 编译
go build -o icloud-hme.exe .

# 交叉编译
GOOS=linux GOARCH=amd64 go build -o icloud-hme .
GOOS=windows GOARCH=amd64 go build -o icloud-hme.exe .

发布

推送 v* tag 到 GitHub 自动触发 CI：

git tag v0.2.0 && git push origin --tags

Actions 会自动构建多平台二进制、Docker 镜像（ghcr.io/xiaozhou26/icloud-hme）并创建 Release。

代码规范

代码注释使用中文
错误信息返回给用户时使用中文
API 响应格式统一: {success: bool, data: any, message: string}

许可证

MIT License

社区

友情链接：LINUX DO

English

A local management tool for Apple iCloud Hide My Email (HME) aliases, supporting creation, listing, and email reading through reverse-engineered iCloud Web API and IMAP protocol.

Features

Create HME aliases automatically
List all aliases for an account
Read emails sent to HME aliases via IMAP
Manage multiple iCloud accounts
Dual authentication: Cookie and App Password

Quick Start

Option 1: Binary (GitHub Releases)

Download the latest binary from GitHub Releases:

Platform	File
Linux x86_64	`icloud-hme_linux_amd64`
Linux ARM64	`icloud-hme_linux_arm64`
macOS Intel	`icloud-hme_darwin_amd64`
macOS Apple Silicon	`icloud-hme_darwin_arm64`
Windows x86_64	`icloud-hme_windows_amd64.exe`

# Linux example
chmod +x icloud-hme_linux_amd64
./icloud-hme_linux_amd64

Option 2: Docker

docker pull ghcr.io/xiaozhou26/icloud-hme:latest

docker run -d \
  --name icloud-hme \
  -p 8081:8081 \
  -v /path/to/data:/app/data \
  ghcr.io/xiaozhou26/icloud-hme:latest

Option 3: Build from source

git clone https://github.com/xiaozhou26/icloud-hme.git
cd icloud-hme
go build -o icloud-hme .
./icloud-hme -debug     # enable request logging

Create data/accounts.json and start the server (default port :8081).

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github/workflows		.github/workflows
internal		internal
.gitignore		.gitignore
API.md		API.md
Dockerfile		Dockerfile
README.md		README.md
accounts.json.template		accounts.json.template
build.sh		build.sh
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

iCloud Hide My Email 本地管理工具

功能特性

快速开始

1. 安装

方式一：下载二进制发布版（推荐）

方式二：Docker

方式三：源码编译

2. 配置账号

3. 启动服务

API 接口

核心接口

创建 HME 别名

读取邮件

账号管理接口

列出所有账号

添加账号

账号登录（获取 Cookie）

删除账号

设置 App Password

别名管理接口

列出所有别名

停用别名

激活别名

删除别名

认证方式

方式一: Cookie 认证 (推荐,功能最完整)

方式二: App Password 认证 (IMAP,优先读邮件)

邮件读取双路径

项目架构

核心模块

技术栈

常见问题

Q: 创建别名返回 401/403 错误?

Q: 读取邮件返回超时?

Q: 如何查看某个别名收到了哪些邮件?

Q: 支持同时管理多个 iCloud 账号吗?

开发指南

本地开发

发布

代码规范

许可证

社区

English

Features

Quick Start

Option 1: Binary (GitHub Releases)

Option 2: Docker

Option 3: Build from source

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages