List iCloud Mail from the Terminal

Apple's missing mail API

Google has the Gmail API. Microsoft has Graph API. Yahoo has IMAP with OAuth2. Apple has... nothing. There's no iCloud Mail REST API, no Apple-provided CLI, and no SDK for mail access. Apple's developer documentation explicitly states that iCloud Mail is accessible only through IMAP and SMTP.

This means every tool that reads iCloud Mail — Thunderbird, mutt, offlineimap, Python's imaplib — goes through the same IMAP path. And that path has friction.

The iCloud Mail authentication maze

Since March 2023, Apple requires two-factor authentication on all Apple IDs. There's no opt-out. To connect any third-party app to iCloud Mail, you must:

1. Sign in to appleid.apple.com
2. Navigate to Sign-In and Security, then App-Specific Passwords
3. Generate a password (Apple allows up to 25 app-specific passwords per account)
4. Copy it immediately — Apple won't show it again
5. Configure your IMAP client with server imap.mail.me.com, port 993, SSL required

The catch: app-specific passwords can't be refreshed programmatically. If one gets revoked (which happens when you change your Apple ID password), you have to manually log in to appleid.apple.com and generate a new one. For automation, this is a dead end.

1. Install the Nylas CLI

brew install nylas/nylas-cli/nylas

For shell script, PowerShell, or Go installs, see the getting started guide.

2. Connect your iCloud Mail account

Head to dashboard-v3.nylas.com, create an application, and connect your iCloud Mail account. Nylas handles Apple's authentication requirements so you don't have to generate app-specific passwords yourself.

nylas auth config
# Paste your API key when prompted

# Verify the connection
nylas auth whoami
# => Authenticated as you@icloud.com (iCloud)

3. List your iCloud inbox

# List recent messages
nylas email list

# Show only unread messages
nylas email list --unread

# Limit to 15 results
nylas email list --limit 15

Hide My Email: finding your alias messages

iCloud+ includes Hide My Email, which generates random @privaterelay.appleid.com addresses. Apple says you can create unlimited aliases with iCloud+ (the free tier allows one). These addresses forward to your real inbox, but when you need to find which service maps to which alias, the CLI helps:

# Find all emails sent to Hide My Email aliases
nylas email search "to:@privaterelay.appleid.com" --limit 20

# See which alias a specific service uses
nylas email search "from:noreply@service.com to:@privaterelay.appleid.com" --json | \
  jq -r '.[] | "\(.to[0].email) <- \(.from[0].email): \(.subject)"'

# Count how many services are using your relay aliases
nylas email list --json --limit 200 | \
  jq '[.[] | select(.to[]?.email | test("privaterelay.appleid.com"))] | \
  [.[].from[0].email] | unique | length'

This is something Apple Mail.app doesn't make easy. You'd have to manually scroll through messages and check the To: field on each one.

iCloud+ custom domain email

iCloud+ subscribers (starting at $0.99/month for 50 GB) can use up to 5 custom domains with 3 email addresses per domain. According to Apple's iCloud+ documentation, custom domain email uses the same iCloud Mail infrastructure as @icloud.com addresses.

When you connect your iCloud account to Nylas, all your addresses are available — @icloud.com, @me.com (legacy), custom domains, and Hide My Email aliases. No separate configuration per address:

# Messages to your custom domain
nylas email search "to:you@yourdomain.com" --limit 10

# Messages to your legacy @me.com address
nylas email search "to:you@me.com" --limit 10

# All iCloud-related addresses at once — just list your inbox
nylas email list --limit 20

iCloud Mail's folder quirks

iCloud Mail uses standard IMAP folder names, but with a few Apple-specific conventions that trip up developers. Apple uses "Junk" where Gmail uses "Spam" and Outlook uses "Junk Email". Sent messages go to "Sent Messages" (not "Sent" or "Sent Items"). And there's no "All Mail" equivalent.

# List all folders to see iCloud's naming
nylas folder list

# iCloud-specific folder names
nylas email list --folder "Inbox"
nylas email list --folder "Sent Messages"    # Not "Sent" or "Sent Items"
nylas email list --folder "Junk"             # Not "Spam" or "Junk Email"
nylas email list --folder "Drafts"
nylas email list --folder "Trash"            # Not "Deleted Items"
nylas email list --folder "Archive"

# Notes folder (synced with Apple Notes via IMAP)
nylas email list --folder "Notes" --limit 5

The Notes folder is interesting — Apple syncs Apple Notes to iCloud Mail's IMAP Notes folder. You can read your Apple Notes as IMAP messages through the CLI, though they're plain-text only (no rich formatting or attachments).

Apple Mail.app vs Nylas CLI

Apple Mail.app is the default macOS/iOS mail client. It works well for reading email, but it's not scriptable. You can't pipe Apple Mail output into jq, trigger it from a cron job, or run it in a CI pipeline. Here's where the CLI fills gaps:

Traditional IMAP vs Nylas CLI for iCloud

Automation for privacy-focused iCloud users

Many people chose iCloud specifically for Apple's privacy stance. Apple processes email on-device for features like Mail Privacy Protection (which preloads remote content to block tracking pixels). According to Apple's privacy documentation, iCloud Mail doesn't scan message content for advertising.

The CLI respects this by going through Nylas's API, not by scraping or storing email content locally. Common automation patterns for iCloud users:

# Morning inbox summary (no email content leaves your terminal)
echo "=== iCloud Inbox Summary ==="
echo "Unread: $(nylas email list --unread --json | jq length)"
echo ""
echo "Latest 5 messages:"
nylas email list --limit 5 --json | \
  jq -r '.[] | "  \(.date | split("T")[0]) \(.from[0].name // .from[0].email): \(.subject)"'

# Weekly alias audit — which Hide My Email addresses are active?
nylas email list --json --limit 500 | \
  jq '[.[] | select(.to[]?.email | test("privaterelay"))] |
  group_by(.from[0].email) |
  map({service: .[0].from[0].email, count: length}) |
  sort_by(-.count) | .[:10]'

A note on macOS Keychain

If you're on macOS, you might wonder why you can't just pull iCloud credentials from Keychain. Apple stores iCloud Mail tokens in the system Keychain, but they're protected by the Secure Enclave and can't be extracted by third-party apps — even with security find-internet-password. This is intentional. The Nylas CLI uses its own OAuth2 tokens stored in ~/.nylas/, separate from Keychain.

Next steps

• Send iCloud Mail from the CLI — send from @icloud.com, custom domains, or Hide My Email
• Manage iCloud calendar from the CLI — create events and check availability
• Send email from the terminal — compose and send from iCloud Mail
• List Gmail emails — same CLI for Google accounts
• List Outlook emails — same workflow for Microsoft 365
• List Yahoo Mail emails — same workflow for Yahoo
• List Exchange emails — for Exchange Online and on-prem
• List IMAP emails — for Fastmail, Zoho, self-hosted, and more
• Give AI agents email access via MCP
• Full command reference