List Your iCloud Mail Emails from the Command Line

The problem with iCloud Mail access

To access iCloud Mail programmatically, you need to enable two-factor authentication on your Apple ID, generate an app-specific password, and manually configure IMAP settings with Apple's mail server hostnames and ports. Apple does not provide a REST API or CLI for iCloud Mail.

Tools like mutt or offlineimap can connect via IMAP, but they require manual credential management and break when Apple changes their security policies. There is no clean way to search or filter iCloud email from the command line.

1. Install the Nylas CLI

# macOS / Linux (Homebrew)
brew install nylas/nylas-cli/nylas

# Or build from source (requires Go 1.23+)
go install github.com/nylas/cli/cmd/nylas@latest

2. Connect your iCloud Mail account

Head to dashboard-v3.nylas.com, create an application, and connect your iCloud Mail account. Then grab your API key:

nylas auth config
# Paste your API key when prompted

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

3. List your emails

# List recent emails
nylas email list

# Limit results
nylas email list --limit 10

# Only unread emails
nylas email list --unread

4. Search and filter

# Search by keyword
nylas email search "photos" --limit 5

# Search by sender
nylas email search "from:noreply@apple.com"

# Search within a date range
nylas email search "after:2026-01-01 before:2026-02-01"

5. Read a specific email

# Read an email by ID (IDs are shown in list output)
nylas email read msg_abc123

# Read the raw MIME source
nylas email read msg_abc123 --mime

6. JSON output for scripting

Every command supports --json output, so you can pipe it into jq, a script, or an AI agent:

# Count unread emails
nylas email list --unread --json | jq length

# Extract subjects
nylas email list --limit 5 --json | jq '.[].subject'

Filter Apple notifications with a quick script:

# Filter Apple notifications
nylas email list --json \
  | jq '[.[] | select(.from[0].email | test("apple.com|icloud.com"; "i"))]' \
  | jq length \
  | xargs -I{} echo "Apple notifications: {}"

7. Work with iCloud Mail folders

iCloud Mail uses standard IMAP folders with a few Apple-specific conventions:

# List emails in a specific folder
nylas email list --folder "INBOX"
nylas email list --folder "Sent Messages"
nylas email list --folder "Junk"

# List all available folders
nylas folder list

# iCloud uses "Junk" instead of "Spam"
nylas email list --folder "Junk" --limit 5

# Archive folder
nylas email list --folder "Archive" --limit 10

8. Traditional iCloud IMAP vs Nylas CLI

Here is what it takes to access iCloud Mail with each approach:

9. Hide My Email and iCloud+ aliases

Apple's iCloud+ includes Hide My Email, which creates random @privaterelay.appleid.com addresses. When listing emails with the Nylas CLI, messages sent to these aliases appear in your inbox like any other email:

# Find emails sent to your private relay addresses
nylas email search "to:@privaterelay.appleid.com" --limit 10

# iCloud custom domain emails (iCloud+) also work
nylas email search "to:you@yourdomain.com" --limit 10

The CLI also works with iCloud custom domain email (available with iCloud+), where you use your own domain with iCloud Mail. No separate configuration is needed — connect the account once and all aliases and custom domains are accessible.

Next steps

• Send email from the terminal
• List Gmail emails — same workflow for Google
• List Outlook emails — same workflow for Microsoft 365
• List Yahoo Mail emails — same workflow for Yahoo
• List IMAP emails — works with Fastmail, Zoho, and more
• List Exchange emails — same workflow for Exchange
• Give AI agents email access via MCP
• Full command reference