messenger/docs/setup/icloud-mail.md

iCloud Mail Setup

Connect iCloud Mail to the messenger platform via IMAP/SMTP.

Prerequisites

• An iCloud account with an @icloud.com / @me.com email address
• Two-factor authentication enabled on the Apple ID
• An app-specific password (regular password won't work with 2FA)

1. Generate an App-Specific Password

1. Go to appleid.apple.com
2. Sign in, navigate to Sign-In and Security > App-Specific Passwords
3. Click Generate an app-specific password
4. Label it messenger-sync (or similar)
5. Copy the generated password (format: xxxx-xxxx-xxxx-xxxx)

2. Configure Environment Variables

Add to the backend .env file:

# iCloud Mail IMAP (incoming)
ICLOUD_IMAP_HOST=imap.mail.me.com
ICLOUD_IMAP_PORT=993
ICLOUD_IMAP_USER=yourname@icloud.com
ICLOUD_IMAP_PASS=xxxx-xxxx-xxxx-xxxx
ICLOUD_IMAP_TLS=true

# iCloud Mail SMTP (outgoing)
ICLOUD_SMTP_HOST=smtp.mail.me.com
ICLOUD_SMTP_PORT=587

# Your iCloud email (used to determine message direction)
ICLOUD_FROM_EMAIL=yourname@icloud.com

# Sync interval in milliseconds (default: 60000 = 1 minute)
ICLOUD_SYNC_INTERVAL=60000

ICLOUD_IMAP_USER and ICLOUD_IMAP_PASS use the same app-specific password for both IMAP and SMTP.

3. IMAP/SMTP Server Details

Protocol	Host	Port	Security
IMAP	imap.mail.me.com	993	TLS
SMTP	smtp.mail.me.com	587	STARTTLS

4. What Gets Synced

On startup, the ICloudSyncService:

1. Connects to IMAP
2. Syncs folder list (Inbox, Sent, Drafts, etc.) to email_folders table
3. Fetches messages from each folder (last 30 days on first sync)
4. Parses email headers for threading (References, In-Reply-To)
5. Creates contacts from sender/recipient addresses
6. Stores messages with provider = 'icloud' in the unified messages table
7. Polls for new messages on the configured interval

5. Verify Sync

Once the backend is running with iCloud configured:

-- Check synced folders
SELECT name, message_count, unread_count FROM email_folders WHERE provider = 'icloud';

-- Check synced messages
SELECT COUNT(*) FROM messages WHERE provider = 'icloud';

-- Check conversations
SELECT display_name, message_count FROM conversations WHERE provider = 'icloud' ORDER BY last_message_at DESC LIMIT 10;

Or via MCP tools:

list_conversations provider=icloud
list_folders provider=icloud
search_messages query="..." provider=icloud

Troubleshooting

• "ICLOUD_IMAP_USER not configured" — The env var is empty or missing. Check .env.
• Authentication failed — Verify the app-specific password. Regular Apple ID passwords don't work.
• Connection timeout — Ensure outbound connections to imap.mail.me.com:993 are allowed.
• No messages syncing — First sync fetches the last 30 days. Check email_folders has entries first.