Skip to content
BranchesTags
 
 

Repository files navigation

iCloud Hide My Email 本地管理工具

English | 中文

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

Docker、GitHub Actions 和安全部署说明见 DEPLOY.md。

功能特性

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

快速开始

1. 安装

# 前置要求: Go 1.26+
go version  # 确认 Go 版本

# 克隆项目
git clone <your-repo-url>
cd icloud-hme

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

2. 配置账号

在项目根目录创建 accounts.json:

{
  "accounts": [
    {
      "id": "acc_1",
      "name": "主号",
      "cookies": [
        {
          "domain": ".icloud.com",
          "name": "x-apple-session-token",
          "value": "YOUR_SESSION_TOKEN_HERE"
        }
      ],
      "app_passwords": [
        {
          "icloud_email": "your_email@icloud.com",
          "password": "YOUR_APP_PASSWORD_HERE"
        }
      ]
    }
  ]
}

3. 启动服务

./icloud-hme.exe

# 服务默认监听 :8080
# 可通过环境变量 PORT 修改端口
PORT=9090 ./icloud-hme.exe

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:

  1. 使用浏览器登录 icloud.com 或 icloud.com.cn (国区)
  2. 打开浏览器开发者工具 (F12)
  3. 进入 Application → Cookies
  4. 导出全部 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:

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

邮件读取双路径

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

  1. 优先: IMAP (App Password) — 设置了 App Password 时使用,支持服务端按收件人 (TO) 搜索
  2. 回退: 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

# 运行 (开发模式，带日志)
go run main.go

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

# 交叉编译 (Linux)
GOOS=linux GOARCH=amd64 go build -o icloud-hme .

代码规范

  • 代码注释使用中文
  • 错误信息返回给用户时使用中文
  • 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

# Build
go build -o icloud-hme.exe .

# Create accounts.json with your credentials
# Run
./icloud-hme.exe

# API endpoints
# POST /api/create     - Create HME alias
# GET  /api/inbox      - Read emails
# GET  /api/aliases    - List aliases

See API Documentation for detailed usage.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages