iCloud Mail CLI: Read Emails from Terminal

How do you use an iCloud Mail CLI from terminal?

Connect iCloud Mail once, then run nylas email list, nylas email search, and nylas email read. The CLI gives you terminal access to iCloud Mail without building around raw IMAP, app-specific passwords, or Hide My Email alias parsing.

Apple is the only major consumer email provider without a public REST API for mail.

Apple is the only major consumer email provider without a public REST API for mail. Gmail exposes the Gmail API. Microsoft exposes Microsoft Graph. Yahoo exposes OAuth-secured IMAP. iCloud Mail supports only IMAP and SMTP — the access details, including the requirement to use an app-specific password, are spelled out on Apple's own iCloud Mail server settings page. Every iCloud Mail tool from Thunderbird and mutt to offlineimap and Python's imaplib goes through that same IMAP path. It has not changed in over a decade.

IMAP itself is fine. The problem is Apple's authentication overlay on top of it: mandatory two-factor auth, manually generated app-specific passwords, and a hard cap of 25 active passwords per Apple ID. That is what makes iCloud Mail awkward for terminal access, not the IMAP protocol (defined in RFC 9051).

This page is intentionally narrower than a generic "list email from the CLI" guide. The search intent here is Apple-specific: inspecting iCloud Mail, dealing with Hide My Email aliases, working with custom domains, and avoiding brittle IMAP credential handling. If you are comparing providers in general, the broader list-email guides cover that separately.

The iCloud Mail authentication maze

Connecting a third-party client to iCloud Mail requires a 5-step manual process: enabling two-factor authentication, generating an app-specific password at appleid.apple.com, copying it immediately (Apple never shows it again), and configuring IMAP server details. Apple caps each Apple ID at 25 active app-specific passwords, and changing your Apple ID password revokes all of them at once.

Apple has required two-factor authentication on Apple IDs created in macOS 10.12 Sierra or later (and effectively all modern accounts) for years; the policy is documented in the Apple two-factor authentication overview. There is no opt-out. To connect any third-party IMAP client to iCloud Mail, you have to:

1. Sign in to appleid.apple.com
2. Open Sign-In and Security, then App-Specific Passwords
3. Generate a password. Apple caps the active total at 25 (see Apple's app-specific passwords article)
4. Copy it immediately. Apple does not show it again
5. Configure your IMAP client with server imap.mail.me.com, port 993, SSL required

The catch: app-specific passwords cannot be refreshed programmatically. If one gets revoked (which happens automatically the moment you change your Apple ID password), you have to log into appleid.apple.com and generate a new one by hand. For unattended automation, that is a dead end.

1. Install the Nylas CLI

The Nylas CLI installs as a single binary under 30 MB on macOS, Linux, and Windows. Homebrew is the fastest method — a single command downloads the binary, verifies its SHA-256 checksum, and adds it to your PATH. The install typically completes in under 10 seconds on a broadband connection.

brew install nylas/nylas-cli/nylas

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

2. Connect your iCloud Mail account

Connecting an iCloud Mail account to the Nylas CLI takes about 2 minutes. The CLI authenticates through Nylas's API layer, which handles Apple's mandatory two-factor authentication and app-specific password requirements on your behalf. You don't need to generate or manage app-specific passwords yourself — the CLI stores an OAuth2 token locally instead.

Start by creating an application at dashboard-v3.nylas.com and connecting your iCloud Mail account there. Then run nylas auth config to paste your API key. The nylas auth whoami command confirms the connection is active and shows the linked email address.

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

The nylas email list command fetches messages from the connected iCloud Mail inbox and prints them to stdout. By default it returns the 10 most recent messages, sorted newest-first. Adding --unread filters to unread messages only, and --limit controls how many results come back — useful when an inbox has thousands of messages.

iCloud Mail accounts average around 40 new messages per day for active users. These three variations cover the most common listing tasks: a quick inbox check, an unread-only scan, and a larger batch pull.

# 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

Hide My Email is an iCloud+ feature that generates random @privaterelay.appleid.com addresses for use when signing up for services. iCloud+ subscribers can create unlimited aliases (the free tier allows 1). Each alias forwards to the real iCloud inbox, but Apple provides no built-in way to search across aliases or audit which services map to which relay address.

The Nylas CLI's nylas email search command can filter by the privaterelay.appleid.com domain to find all relay-addressed messages. Piping JSON output through jq extracts the mapping between sender and alias, and a second query counts the total number of unique services using relay addresses.

# 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'

Apple Mail.app has no equivalent workflow. Auditing Hide My Email aliases in Mail.app requires manually scrolling through messages and checking the To: field on each one — impractical for accounts with dozens of active aliases.

iCloud+ custom domain email

iCloud+ subscribers (starting at $0.99/month for 50 GB) can attach up to 5 custom domains with 3 email addresses per domain, for a maximum of 15 custom addresses per Apple ID. According to Apple's iCloud+ documentation, custom domain email routes through the same iCloud Mail infrastructure as @icloud.com addresses — same IMAP servers, same authentication, same storage quota.

When you connect an iCloud account to the Nylas CLI, all addresses on that Apple ID become accessible from a single grant: @icloud.com, @me.com (legacy), custom domains, and Hide My Email aliases. No separate configuration is needed per address. The nylas email search command filters by recipient 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 exposes 7 default IMAP folders, but 3 of them use names that differ from Gmail and Outlook conventions. Apple calls the spam folder "Junk" (not "Spam" or "Junk Email"), the sent folder "Sent Messages" (not "Sent" or "Sent Items"), and the trash folder "Trash" (not "Deleted Items"). There is no "All Mail" equivalent. Scripts that hard-code Gmail or Outlook folder names will silently return zero results on iCloud.

The nylas folder list command prints every folder name on the account, including custom folders. The commands here show the exact iCloud folder names you need for the --folder flag.

# 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 ships on every Mac and iPhone — over 1.5 billion active Apple devices worldwide as of Apple's January 2025 earnings call. Mail.app works well for reading email in a GUI, but it produces no structured output. You can't pipe Mail.app results into jq, trigger inbox checks from a cron job, or run mail operations in a CI pipeline. The Nylas CLI fills those gaps with JSON output, scriptable commands, and headless execution.

Traditional IMAP vs Nylas CLI for iCloud

Traditional IMAP access to iCloud Mail requires configuring imap.mail.me.com on port 993 with SSL, generating an app-specific password, and handling credential revocation whenever the Apple ID password changes. The Nylas CLI replaces that 5-step manual setup with a single nylas auth config command and automatic token refresh. The table compares each step of the two approaches side by side.

Automation for privacy-focused iCloud users

iCloud Mail users often choose Apple specifically for its privacy protections. Mail Privacy Protection, introduced in iOS 15 and macOS Monterey in 2021, routes remote content through Apple's proxy servers and pre-fetches tracking pixels so senders cannot correlate an open event with a recipient's IP address or read time. Apple's broader privacy policy documents what data the company collects across its services.

The Nylas CLI preserves that privacy model. It reads mail through Nylas's API rather than scraping IMAP directly, and email content is not stored on disk unless you explicitly redirect output to a file. The two scripts here cover the most common privacy-conscious automation tasks: a morning inbox summary that prints counts and subjects without caching message bodies, and a weekly Hide My Email alias audit that identifies which services are sending to which relay addresses.

# 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]'

Why macOS Keychain can't replace the Nylas CLI for iCloud Mail

Apple stores iCloud Mail tokens in the macOS system Keychain, but those tokens are protected by the Secure Enclave — a hardware-isolated coprocessor present in every Mac with a T2 chip or Apple Silicon (shipped since 2017). Third-party apps cannot extract iCloud credentials from Keychain, even using the security find-internet-password command. The Nylas CLI sidesteps this limitation entirely by storing its own OAuth2 tokens in ~/.config/nylas/, separate from Keychain. This means iCloud Mail access works on macOS, Linux, and Windows without depending on Apple-specific hardware security.

Next steps

After listing iCloud Mail from the terminal, the natural follow-ups are sending email, managing iCloud calendars, or extending the same CLI workflow to other providers. The Nylas CLI supports 6 email providers — iCloud, Gmail, Outlook, Exchange, Yahoo, and generic IMAP — with the same command syntax across all of them.

• iCloud Mail CLI: Send Email from Terminal — send from @icloud.com, custom domains, or Hide My Email
• iCloud Mail API alternative — compare IMAP settings, app-specific passwords, aliases, and CLI access
• iCloud Calendar CLI: Manage Events — create events and check availability
• Send email from the terminal — compose and send from iCloud Mail
• How Apple's new CEO can automate iCloud email — AI triage, smart compose, focus time, and MCP agents for iCloud
• List Gmail emails — same CLI for Google accounts
• List Outlook emails — same workflow for Microsoft 365
• Yahoo Mail CLI: Read Emails from Terminal — 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