Generate, reserve, and manage iCloud Hide My Email addresses from a native macOS app, optional Android companion, or local CLI.
Includes native macOS sign-in, an Android client, a Windows launcher, iCloud China support, and a local inbox.

English · 简体中文 · Русский

You need an active iCloud+ subscription to generate Hide My Email addresses.

Download for Apple Silicon (.dmg) · Download for Intel (.dmg)

• Generate one address or a batch with a custom label.
• Manage local unused, used, and trash addresses alongside the live active or inactive iCloud inventory.
• Connect a receiving mailbox, sync forwarded messages, and copy extracted verification codes without leaving the app.
• Copy individual addresses, copy everything, or export local history and CSV data.
• Schedule larger batches; the app pauses and resumes when Apple rate-limits creation.
• Sign in natively, keep the session in Keychain, and see connection status at a glance.
• Keep everything private: address history stays local and the app collects no telemetry.

HideMyEmail Generator is a local macOS app, optional Android companion, and command-line utility for Apple's iCloud Hide My Email service. It generates and reserves new addresses, lists active or inactive ones, and inspects the account behind the current iCloud session.

Alongside the basics it provides:

• region-aware iCloud API targeting for global and china;
• automatic iCloud partition detection;
• a native SwiftUI macOS app with in-app iCloud sign-in;
• an optional Android client for phone-first alias management;
• a one-click Windows launcher;
• bilingual English / Simplified Chinese launcher and CLI output;
• account-aware cookie management with browser-assisted capture;
• a local IMAP inbox with verification-code extraction;
• local address state management (unused, used, trash);
• CSV export for addresses and received messages;
• longer timeouts and automatic retries for slower iCloud responses.

• App Preview
• Highlights
• Quick Start
• macOS App
• Android App
• Windows Launcher
• CLI Reference
• Cookie Management
• Local Inbox and Codes
• Configuration
• Generated Files
• Troubleshooting
• Security and Privacy
• Rate Limits
• Disclaimer
• Acknowledgements
• License

Grab a standalone binary from the latest release — no Python or uv required.

• Windows: download hidemyemail-windows.exe. Double-click it to open the interactive menu, or run it from a terminal with arguments for CLI usage (hidemyemail-windows.exe --help).
• macOS app: download the Apple Silicon DMG for M-series Macs or the Intel DMG for Intel Macs, then right-click the app and choose Open the first time.
• macOS CLI: download hidemyemail-macos for Apple Silicon or hidemyemail-macos-x86_64 for Intel. Make it executable with chmod +x, then run it from Terminal.
• Android app: build the source under android/.

The native app captures its own iCloud session after you sign in. Prebuilt CLI binaries still use manual cookie capture; Playwright capture is available only when running the CLI from source.

git clone https://github.com/rtunazzz/hidemyemail-generator.git
cd hidemyemail-generator
uv sync --python 3.12

On Windows, double-click start-hidemyemail.bat. For direct CLI usage:

uv run hidemyemail --help

The app requires macOS 13 or newer. It bundles the CLI helper, so Python and uv are not required.

1. Open the app and choose Connect iCloud.
2. Complete Apple's system account prompt or fallback sign-in form. The iCloud session is captured from the authenticated Hide My Email request before its page loads. The window closes automatically when the session validates.
3. Use Generate for one address or a batch, manage local and live iCloud inventory from Addresses, connect a receiving mailbox under Inbox, or use Scheduler to create addresses at a configurable interval until a target is reached.

The session cookie is validated locally and stored in macOS Keychain. Every helper invocation receives it through an owner-only temporary file that is deleted immediately afterward. Generated addresses are also appended to ~/Library/Application Support/HideMyEmail Generator/emails.txt. The History scope stores each address, label, and generation time in a local owner-only history file. Address workflow state, inbox metadata, and extracted codes stay in hidemyemail.db in the same Application Support directory.

The app stores an optional IMAP password or app password in macOS Keychain and keeps only non-secret inbox settings in app preferences. It creates an owner-only temporary CLI config for each inbox sync and deletes it immediately. This is intentionally separate from the CLI's inbox_config.json workflow.

If Apple rate-limits creation, the app preserves completed addresses, shows a countdown, and retries after at least 30 minutes while the app remains open. Use Import Cookie File… only if embedded sign-in does not provide the required cookie.

To build the unsigned app from source:

scripts/build-macos-app.sh "$(uname -m)"

Run this after every change to the Swift app. It removes and regenerates the matching app under build/ and its ZIP and DMG under dist/, so those folders never continue to serve an older UI.

The script builds one exact architecture and refuses cross-architecture packaging. Run it on Apple Silicon for the Apple Silicon app and on an Intel Mac (or the matching GitHub runner) for the Intel app.

macOS updates use Sparkle and are published only from version tags. The verification public key is embedded in macos/Info.plist.

1. Bump the version in pyproject.toml, uv.lock, and macos/Info.plist.
2. Merge the tested change to main.
3. Tag that commit with the matching v-prefixed version, such as v2.1.1.

The release workflow rejects mismatched tags or a missing signing key, builds both Mac architectures, signs their appcasts, and publishes only after every artifact passes.

The optional Android client targets Android 6.0 (API 23) or newer and gives Android users a phone-first interface for their own iCloud+ Hide My Email aliases. It supports global and China iCloud endpoints, raw Cookie header or browser Copy as cURL import, account validation, alias generation, active/inactive address lists, editable labels and notes, deactivate/reactivate controls, and local unused / used / trash tracking. The UI follows the device language with English and Simplified Chinese resources.

Build it from this repository with:

cd android
bash ./gradlew testDebugUnitTest
bash ./gradlew assembleDebug

On Windows, use ./gradlew.bat instead. The debug APK is written to android/app/build/outputs/apk/debug/app-debug.apk.

The Windows launcher is the recommended entry point for Windows users.

1. Generate emails
2. List active emails
3. List inactive emails
4. Manage iCloud cookie
5. Local inbox and codes
6. Exit

Cookie management:

1. Show current cookie account
2. Replace iCloud cookie
3. Auto capture iCloud cookie
4. Back

Inbox management:

1. Configure inbox IMAP account
2. Sync inbox and show verification codes
3. Show recent verification codes
4. Show recent inbox messages
5. List unused local emails
6. Mark email as used
7. Move email to trash
8. Sync iCloud HME addresses to local DB
9. Export CSV files
10. Back

The launcher defaults to the global region. To target iCloud China, set the environment variable before launching:

HIDEMYEMAIL_REGION=china

Commands default to the global region. Add --region china (or set HIDEMYEMAIL_REGION=china) to target iCloud China.

uv run hidemyemail generate --label test --count 1 --cookie-file cookies.txt

Options:

uv run hidemyemail list --active --cookie-file cookies.txt
uv run hidemyemail list --inactive --cookie-file cookies.txt

uv run hidemyemail deactivate abc123@icloud.com
uv run hidemyemail reactivate abc123@icloud.com
uv run hidemyemail update-metadata abc123@icloud.com --label "Newsletter" --note "Signed up 2026-07"

Deactivating stops an address from forwarding mail without giving up the address; it stays on your account and can be reactivated later. update-metadata keeps whichever of --label / --note you leave out.

Each command looks the address up by its email, so no identifier is needed. That costs one extra list call per invocation.

uv run hidemyemail whoami --cookie-file cookies.txt

Example output:

Current iCloud Cookie
Apple ID       user@example.com
Name           Example User
DSID           ***********
Hide My Email  Available
User Partition 68
Maildomain     p68-maildomainws.icloud.com

uv sync --extra capture
uv run hidemyemail capture-cookie --cookie-file cookies.txt

Configure the receiving mailbox used by iCloud Hide My Email forwarding:

uv run hidemyemail inbox setup

Sync the latest inbox messages and show extracted verification codes:

uv run hidemyemail inbox sync --limit 100 --show-codes

Show recent codes:

uv run hidemyemail inbox codes --limit 30

Sync existing iCloud Hide My Email addresses into the local database:

uv run hidemyemail inbox sync-hme --cookie-file cookies.txt

Track address state:

uv run hidemyemail inbox addresses --state unused
uv run hidemyemail inbox mark example@icloud.com used
uv run hidemyemail inbox mark example@icloud.com trash

Export local CSV files:

uv run hidemyemail inbox export

The tool needs an authenticated iCloud browser cookie. Cookies stay local in cookies.txt, which is ignored by Git.

1. Run start-hidemyemail.bat.
2. Choose 4. Manage iCloud cookie.
3. Choose 3. Auto capture iCloud cookie.
4. Log in in the opened browser window if needed.
5. The tool opens iCloud Plus, clicks Hide My Email, captures the app request, validates the cookie, and writes cookies.txt.

The capture flow listens for the Hide My Email app request:

https://www.icloud.com/applications/hidemyemail/current/en-us/index.html?rootDomain=www

For iCloud China the host is www.icloud.com.cn and the locale segment is zh-cn.

It uses a separate browser profile:

.cookie-browser-profile

It does not read your everyday browser profile. If a new cookie is captured, the previous file is backed up as:

cookies.txt.bak

1. Open https://www.icloud.com/icloudplus/ (use www.icloud.com.cn for China).

2. Press F12.

3. Open Network.

4. Click the Hide My Email tile (隐藏邮件地址 on China).

5. Find the request ending with:

   /applications/hidemyemail/current/en-us/index.html?rootDomain=www
   

6. Right-click the request and choose Copy -> Copy as cURL.

7. Paste the entire copied text into cookies.txt.

Raw Cookie: header strings also work.

The local inbox feature uses IMAP to read the mailbox that receives forwarded mail from iCloud Hide My Email. It stores message metadata, matched Hide My Email addresses, and extracted verification codes in a local SQLite database.

What it does:

• connects to your receiving mailbox through IMAP;
• fetches new messages from the configured folder;
• extracts likely verification codes from subjects and message bodies;
• links messages to known Hide My Email addresses when possible;
• tracks local address state as unused, used, or trash;
• exports addresses.csv and messages.csv.

What it does not do:

• it does not upload mail or codes to any server;
• it does not require public deployment;
• it does not read your everyday browser profile;
• it does not bypass Apple or mailbox provider rate limits.

For many mail providers, you should use an app password instead of your normal mailbox password.

These files are local-only and ignored by Git:

• cookies.txt
• cookies.txt.bak
• emails.txt
• hidemyemail.db
• hidemyemail.db-*
• inbox_config.json
• exports/
• .cookie-browser-profile/
• .venv/

• Cookies are stored locally and ignored by Git.
• The macOS app stores its validated session in Keychain and never stores or logs the Apple Account password.
• IMAP secrets entered in the macOS app are stored in Keychain, never in app preferences or process arguments.
• The macOS app uses owner-only temporary cookie files and deletes them after each helper invocation.
• The macOS app contains no analytics, telemetry, advertising, or crash-reporting SDK. It connects only to Apple's iCloud endpoints and, when Inbox is configured, the user's chosen IMAP server.
• IMAP configuration and local mailbox data are stored locally and ignored by Git.
• Automatic capture uses a separate browser profile.
• The project does not intentionally collect, upload, or share your cookies, email data, or verification codes.
• Do not commit cookies.txt, cookies.txt.bak, emails.txt, inbox_config.json, hidemyemail.db, exports, or browser profile data.
• If a token or cookie is accidentally exposed, revoke it from the provider dashboard.

Apple may rate-limit Hide My Email creation. Observed limits are roughly 5 * number of people in your iCloud family new addresses every 30 minutes, with a total cap around 700 addresses.

The macOS app does not bypass this limit. It generates sequentially and resumes after a cooldown when Apple returns error -41015.

This project is an independent community tool and is not affiliated with, endorsed by, or sponsored by Apple Inc. Apple, iCloud, and Hide My Email are trademarks of Apple Inc.

• iCloud China support, the Windows launcher, local inbox, and Android companion were contributed by @never-seek.
• Thanks to all other community contributors.

MIT. See LICENSE.