【开源推广】iCloud Mail：自托管 iCloud 隐藏邮箱管理，支持自动创建 23个/h，邮箱池、API 取码和 Docker 部署

本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：

- 我的帖子已经打上 开源推广 标签： 是

- 我的开源项目完整开源，无未开源部分： 是

- 我的开源项目已链接认可 LINUX DO 社区： 是

- 我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是

- 以上选择我承诺是永久有效的，接受社区和佬友监督： 是

以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出

项目：iCloud Mail

- 新人首次开源，但有不好的，不合规的请多多指点

- 求Star

- 简单来说：自动创建隐藏邮箱，通过本项目提供的 API 管理、分发和获取验证码，支持国际区与中国大陆 Apple 账户。

如果你平时会用 iCloud 隐藏邮箱，应该遇到过这些麻烦：地址多了不好整理，几个主号要分别管理，收到验证码后还得去主邮箱里翻。如果想接进自己的程序，又需要另外处理收件和接口。

这个二开项目就是把这些事情集中到一个可以自己部署的 Web 面板里：管理隐藏邮箱、自动补充地址、接收邮件，再通过链接或 API 取验证码。

项目地址： GitHub - t508708/icloud-mail: 自托管 iCloud 隐藏邮箱管理、邮箱池与 API 取码服务；基于 mangobubu/icloud-api 的派生二开版本，来源与许可见 NOTICE.md。 · GitHub

目前能做什么？

- 集中管理多个 iCloud 主号。 同步隐藏邮箱目录，支持搜索筛选、跨页选择、框选多选，以及批量创建、停用和删除。

- 给每个邮箱一个取件入口。 可以直接刷新取件链接，也可以用 API 获取最新验证码，方便接入自己的脚本或工具。

- 提供项目邮箱池。 不同项目使用各自的 Pool Key，通过接口领取邮箱、确认使用、续租、释放和退役，减少手动维护地址列表。

- 支持根邮箱接收 +tag 邮件。 已登记 [email protected] 后，投递到 [email protected] 的邮件可以归入根邮箱取件；完整地址精确匹配优先。

- 按需增量收件。 访问取件链接或 API 时触发读取，同一主号复用连接，尽量减少重复请求和旧邮件正文下载。

- 可选自动登录恢复。 按主号配置后，在通道需要重新登录时提交登录并获取双重验证码，减少反复人工操作。

界面采用苹果风格，支持浅色、深色主题和 Liquid Glass 效果，JS、CSS 随服务本地提供。

另外，每个邮箱可以使用独立的 API Key、IMAP 密码和 OAuth 凭据，并支持轮换。

这些独立凭据由本网关提供，用于连接本服务；上游 iCloud 收件仍使用主号的 App 专用密码。

自动创建每小时能有多少？

当前自动计划按每个主号的滚动一小时安排：

连接状态 |
自动创建计划 |

新旧通道正常 |
新通道 19 次＋旧通道 4 次，合计最多 23 次尝试/h |

新通道失效，旧通道及目录正常 |
降级为旧通道最多 5 次尝试/h，恢复新通道后回到双通道计划 |

这里说的是尝试次数，实际成功数量取决于 Apple 响应、账户状态和剩余容量。

已有使用观察中，新旧通道常在约 20 次和 5 次附近触限，所以双通道计划各留一次余量，并分散执行时间。这些数字是项目当前采用的策略，Apple 的实际限制仍以上游响应为准。

怎么部署？

提供 AMD64、ARM64 的预构建 Docker 镜像，默认使用 latest：```
git clone --depth 1 https://github.com/t508708/icloud-mail.git
cd icloud-mail
cp -n .env.example .env

docker compose pull
docker compose up -d --wait
```建议准备 2 核、4 GB 内存的环境，以及具备“隐藏邮件地址”功能的 Apple 账户。

关于 iCloud+ 和家庭共享

可以通过 iCloud+ 家庭共享，让家庭成员使用相应功能。家庭组织者加上最多 5 位成员，可以组成 6 人家庭组；每个账户仍需要分别连接和管理。

个人使用中观察到，部分主号的隐藏邮箱容量可到 750 个左右，具体以上游对该账户显示的容量为准。

停用、删除和新建轮转仍在观察中：曾遇到累计创建约 1,000 个左右后，出现持续数天的 429 限流。这个数字只是使用记录，涉及的具体窗口和后续恢复规律还没有测清楚，大家别按固定配额理解。

登录后台

示例配置的后台地址：```
http://127.0.0.1:8788/admin/
``用户名为 admin，首次生成的密码通过下面的命令查看：``
docker compose exec -T icloud-api cat /app/keys/admin-password
```远程访问、域名、HTTPS、备份和升级步骤都放在仓库文档里了。

目前还有哪些限制？

1. 新通道可能在约 8 小时后失效

目前比较明显的问题是：新通道仍可能在登录约 8 小时后失效。

自动登录恢复可以减少人工处理。在密码、双重验证接码服务和账户状态正常时，可以自动尝试恢复连接（理论能一直保持在线，仅新通道可一小时创建20个，保活也是为了他的保持），但还没有永久在线的保证。

2. 取码仍受投递时间和网络影响

取码速度取决于邮件实际投递时间，以及服务器到 Apple 的网络。

项目通过按需增量读取、连接复用等方式减少重复工作，邮件尚未投递时仍需要等待。

3. 隐藏邮箱管理需要跟随 Apple 官网变化

服务默认直连 Apple：

- 邮件接收使用 Apple 公开支持的标准 IMAP。

- 隐藏邮箱管理适配 Apple 官网使用的接口。

- 邮箱池、取件 API 和独立凭据由本网关提供。

官网接口的行为可能受到页面调整、账户区域和账户状态影响，需要持续维护。

4. 转发到自有域名邮箱后的二次托管仍在评估

目前尚未把“转发到自有域名邮箱后，稳定按原隐藏邮箱归属并通过 API 取件”做成成熟方案。

主要难点是：不同转发链路保留的收件信息有所差异。如果只剩主号地址，原始隐藏邮箱的归属就容易丢失；单看 To 等字段，也未必能覆盖所有投递情况。

这部分还在找更可靠的方案。如果有佬友做过完整的投递头保留和地址归属，欢迎交流。

欢迎试用和反馈

如果你也有集中管理隐藏邮箱、给自己的工具接入取码 API 的需求，欢迎试用。

部署问题、使用体验或功能建议，可以直接在楼里交流，也欢迎到 GitHub 提 Issue：

GitHub - t508708/icloud-mail: 自托管 iCloud 隐藏邮箱管理、邮箱池与 API 取码服务；基于 mangobubu/icloud-api 的派生二开版本，来源与许可见 NOTICE.md。 · GitHub

新人首次开源，但有不好的，不合规的请多多指点，求Star，求Star，求Star