HideMyEmail Generator

Hide My Email 주소를 생성하려면 활성 iCloud+ 구독이 필요합니다.

앱 미리보기

• 사용자 지정 레이블을 사용하여 주소 하나 또는 일괄 주소를 생성합니다.
• 로컬의 unused(미사용), used(사용됨), trash(휴지통) 주소와 활성 또는 비활성 iCloud 인벤토리를 함께 관리할 수 있습니다.
• 수신 메일함에 연결하여 전달된 메시지를 동기화하고, 앱을 벗어나지 않고 추출된 인증 코드를 복사합니다.
• 개별 주소를 복사하거나, 전체 내용을 복사하거나, 로컬 기록 및 CSV 데이터를 내보낼 수 있습니다.
• 대규모 일괄 처리를 예약할 수 있으며, 애플이 생성 속도를 제한(rate-limits)하면 앱이 일시 중지되었다가 재개됩니다.
• 네이티브로 로그인하고 세션을 Keychain에 유지하며, 연결 상태를 한눈에 확인할 수 있습니다.
• 모든 것을 비공개로 유지합니다: 주소 기록은 로컬에 보관되며 앱은 어떠한 텔레메트리(telemetry)도 수집하지 않습니다.

개요 (Overview)

HideMyEmail Generator는 Apple의 iCloud Hide My Email 서비스용 로컬 macOS 앱, 선택적 Android 컴패니언, 그리고 커맨드라인 유틸리티입니다. 이 도구는 새로운 주소를 생성하고 예약하며, 활성 또는 비활성 주소 목록을 제공하고, 현재 iCloud 세션 뒤에 있는 계정을 검사합니다.

기본 기능 외에도 다음 기능을 제공합니다:

• region 인식(region-aware) iCloud API 타겟팅을 통해 global 및 china 지원;
• 자동 iCloud 파티션 감지 기능;
• 인앱 iCloud 로그인 기능을 갖춘 네이티브 SwiftUI macOS 앱;
• 전화기 우선 별칭 관리용 선택적 Android 클라이언트;
• 원클릭 Windows 런처;
• 양방향 영어/간체 중국어 런처 및 CLI 출력 지원;
• 브라우저 지원 캡처를 통한 계정 인식(account-aware) 쿠키 관리 기능;
• 인증 코드 추출 기능을 갖춘 로컬 IMAP 받은 편지함;
• 로컬 주소 상태 관리 (unused, used, trash);
• 주소 및 수신 메시지에 대한 CSV 내보내기 기능;
• 느린 iCloud 응답에 대비한 긴 타임아웃 및 자동 재시도(automatic retries) 기능.

목차 (Contents)

• 앱 미리보기
• 주요 특징 (Highlights)
• 빠른 시작 (Quick Start)
• macOS 앱
• Android 앱
• Windows 런처
• CLI 참고 자료 (CLI Reference)
• 쿠키 관리 (Cookie Management)
• 로컬 받은 편지함 및 코드 (Local Inbox and Codes)
• 설정 (Configuration)
• 생성된 파일 (Generated Files)
• 문제 해결 (Troubleshooting)
• 보안 및 개인 정보 보호 (Security and Privacy)
• 속도 제한 (Rate Limits)
• 면책 조항 (Disclaimer)
• 감사의 글 (Acknowledgements)
• 라이선스 (License)

주요 특징 (Highlights)

빠른 시작 (Quick Start)

사전 빌드 바이너리 다운로드

최신 릴리스에서 독립형 바이너리를 가져오세요. Python이나 uv가 필요하지 않습니다.

• Windows: hidemyemail-windows.exe를 다운로드합니다. 이를 더블클릭하여 대화형 메뉴를 열거나, CLI 사용을 위해 터미널에서 인자(argument)와 함께 실행할 수 있습니다 (hidemyemail-windows.exe --help).
• macOS 앱: M 시리즈 Mac용 Apple Silicon DMG 또는 Intel Mac용 Intel DMG를 다운로드한 후, 앱을 마우스 오른쪽 버튼으로 클릭하고 처음 사용할 때 **열기(Open)**를 선택합니다.
• macOS CLI: Apple Silicon용 hidemyemail-macos 또는 Intel용 hidemyemail-macos-x86_64를 다운로드합니다. chmod +x로 실행 권한을 부여한 다음, 터미널에서 실행합니다.
• Android 앱: android/ 아래에서 소스 코드를 빌드합니다.

네이티브 앱은 사용자가 로그인하면 자체 iCloud 세션을 캡처합니다. 미리 빌드된 CLI 바이너리는 여전히 수동 쿠키 캡처를 사용하며, Playwright 캡처는 소스로부터 CLI를 실행할 때만 사용할 수 있습니다.

소스에서 실행하기 (Run from source)

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

Windows에서는 start-hidemyemail.bat을 더블클릭합니다. 직접 CLI를 사용하려면:

uv run hidemyemail --help

macOS 앱 (macOS App)

이 앱은 macOS 13 이상을 요구합니다. CLI 헬퍼가 번들되어 있어 Python과 uv는 필요하지 않습니다.

1. 앱을 열고 **iCloud에 연결(Connect iCloud)**을 선택합니다.
2. Apple 시스템 계정 프롬프트 또는 대체 로그인 양식을 완료합니다. iCloud 세션은 페이지 로드 전에 인증된 Hide My Email 요청으로부터 캡처됩니다. 세션이 유효성을 검사하면 창이 자동으로 닫힙니다.
3. **생성(Generate)**을 사용하여 하나의 주소 또는 일괄적으로 처리하고, **주소(Addresses)**에서 로컬 및 실시간 iCloud 인벤토리를 관리하거나, 받은 편지함(Inbox) 아래에서 수신 메일함을 연결하거나, **스케줄러(Scheduler)**를 사용하여 대상에 도달할 때까지 설정 가능한 간격으로 주소를 생성합니다.

세션 쿠키는 로컬에서 검증되어 macOS Keychain에 저장됩니다. 모든 헬퍼 호출은 소유자 전용 임시 파일을 통해 이를 수신하며, 사용 직후 즉시 삭제됩니다. 생성된 주소는 ~/Library/Application Support/HideMyEmail Generator/emails.txt에도 추가됩니다. History 범위는 각 주소, 레이블 및 생성 시간을 로컬 소유자 전용 기록 파일에 저장합니다. 주소 워크플로우 상태, 받은 편지함 메타데이터 및 추출된 코드는 동일한 Application Support 디렉터리의 hidemyemail.db에 유지됩니다.

이 앱은 선택적 IMAP 비밀번호 또는 앱 비밀번호를 macOS Keychain에 저장하며, 앱 환경설정에는 비(非)비밀 받은 편지함 설정만 보관합니다. 각 받은 편지함 동기화마다 소유자 전용 임시 CLI 설정을 생성하고 즉시 삭제합니다. 이는 CLI의 inbox_config.json 워크플로우와 의도적으로 분리됩니다.

Apple이 생성을 속도 제한(rate-limits)하는 경우, 앱은 완료된 주소를 보존하고 카운트다운을 표시하며, 앱이 열려 있는 동안 최소 30분 후에 재시도합니다. 임베디드 로그인으로 필요한 쿠키를 제공하지 않는 경우에만 **Import Cookie File…**을 사용하십시오.

소스에서 서명되지 않은(unsigned) 앱을 빌드하려면:

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

이 스크립트는 Swift 앱의 모든 변경 후 실행해야 합니다. 이는 build/ 아래의 일치하는 앱과 그 ZIP 및 DMG 파일을 제거하고 재생성하여, 해당 폴더들이 이전 UI를 계속 제공하지 않도록 합니다.

스크립트는 정확히 하나의 아키텍처만 빌드하며 교차 아키텍처 패키징을 거부합니다. Apple Silicon 앱의 경우 Apple Silicon에서, Intel 앱의 경우 Intel Mac(또는 일치하는 GitHub runner)에서 실행하십시오.

릴리스하기 (Releasing)

macOS 업데이트에는 Sparkle이 사용되며 버전 태그를 통해서만 게시됩니다. 검증 공개 키는 macos/Info.plist에 임베드되어 있습니다.

1. pyproject.toml, uv.lock, 및 macos/Info.plist에서 버전을 올립니다(Bump).
2. 테스트된 변경 사항을 main으로 병합합니다(Merge).
3. 해당 커밋에 일치하는 v-접두사가 붙은 버전, 예: v2.1.1로 태그를 지정합니다.

릴리스 워크플로우는 태그 불일치 또는 서명 키 누락 시 거부하며, Mac 아키텍처를 모두 빌드하고 앱캐스트에 서명한 후 모든 아티팩트가 통과해야만 게시합니다.

Android App

선택적 Android 클라이언트는 Android 6.0 (API 23) 이상을 대상으로 하며, Android 사용자에게 자체 iCloud+ Hide My Email 별칭을 위한 휴대폰 우선 인터페이스를 제공합니다. 글로벌 및 중국 iCloud 엔드포인트를 지원하고, 원시 Cookie 헤더 또는 브라우저 cURL로 복사 가져오기, 계정 검증, 별칭 생성, 활성/비활성 주소 목록, 편집 가능한 레이블 및 메모, 비활성화/재활성화 제어, 그리고 로컬 unused / used / trash 추적 기능을 지원합니다. UI는 기기 언어를 따르며 영어와 간체 중국어 리소스를 제공합니다.

이 저장소에서 다음 명령어로 빌드할 수 있습니다:

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

Windows에서는 대신 ./gradlew.bat을 사용하세요. 디버그 APK는 android/app/build/outputs/apk/debug/app-debug.apk에 작성됩니다.

Windows Launcher

Windows 런처는 Windows 사용자에게 권장되는 진입점입니다.

1. 이메일 생성
2. 활성 이메일 목록 보기
3. 비활성 이메일 목록 보기
...

쿠키 관리:

1. 현재 쿠키 계정 표시
2. iCloud 쿠키 교체
3. iCloud 쿠키 자동 캡처
...

받은 편지함 관리:

1. 받은 편지함 IMAP 계정 설정
2. 받은 편지함 동기화 및 인증 코드 표시
3. 최근 인증 코드 표시
...

런처는 기본적으로 global 리전을 사용합니다. iCloud China를 대상으로 하려면 실행 전에 환경 변수를 설정하세요:

HIDEMYEMAIL_REGION=china

CLI Reference

명령어는 기본적으로 global 리전을 사용합니다. iCloud China를 대상으로 하려면 --region china를 추가하거나 (HIDEMYEMAIL_REGION=china 설정) 하세요.

Generate

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

옵션:

List

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

주소 관리 (Manage an Address)

uv run hidemyemail deactivate [email protected]
uv run hidemyemail reactivate [email protected]

주소를 비활성화(Deactivating)하면 해당 주소로의 메일 전달이 중단되지만, 주소 자체가 사라지는 것은 아닙니다. 계정에 남아 있다가 나중에 다시 활성화할 수 있습니다. update-metadata는 --label 또는 --note 중 지정하지 않은 값을 유지합니다.

각 명령어는 이메일을 통해 해당 주소를 조회하므로 별도의 식별자가 필요 없습니다. 이로 인해 호출(invocation)당 추가적인 list 호출이 한 번 발생합니다.

계정 확인 (Account Check)

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

예시 출력:

Current iCloud Cookie
Apple ID       [email protected]
Name           Example User
...

쿠키 자동 캡처 (Auto Capture Cookie)

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

로컬 받은 편지함 (Local Inbox)

iCloud Hide My Email 포워딩에 사용되는 수신 사서함을 설정합니다:

uv run hidemyemail inbox setup

최신 받은 편지함 메시지를 동기화하고 추출된 인증 코드를 표시합니다:

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

최근 코드들을 보여줍니다:

uv run hidemyemail inbox codes --limit 30

기존 iCloud Hide My Email 주소들을 로컬 데이터베이스에 동기화합니다:

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

주소 상태 추적:

uv run hidemyemail inbox addresses --state unused
uv run hidemyemail inbox mark [email protected] used
uv run hidemyemail inbox mark [email protected] trash

로컬 CSV 파일 내보내기:

uv run hidemyemail inbox export

쿠키 관리 (Cookie Management)

이 도구는 인증된 iCloud 브라우저 쿠키가 필요합니다. 쿠키는 Git에 의해 무시되는 cookies.txt 파일에 로컬로 저장됩니다.

자동 캡처 (Automatic Capture)