Source: https://cli.nylas.com/guides/list-icloud-emails

# List iCloud Mail from the Terminal

This guide is specifically about iCloud Mail's awkward access model: no public mail API, mandatory two-factor authentication, app-specific passwords, and Apple-only mailbox quirks like Hide My Email aliases, custom domains, and the Notes folder. It shows how to list and search iCloud Mail from the terminal without building around raw IMAP.

Written by [Prem Keshari](https://cli.nylas.com/authors/prem-keshari) Senior SRE

Reviewed by [Nick Barraclough](https://cli.nylas.com/authors/nick-barraclough)

Updated May 3, 2026

## Apple is the only major provider without a public mail API

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](https://support.apple.com/en-us/HT202304). 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](https://datatracker.ietf.org/doc/html/rfc9051)).

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

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](https://support.apple.com/en-us/HT204915). 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](https://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](https://support.apple.com/en-us/HT204397))
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

```bash
brew install nylas/nylas-cli/nylas
```

For shell script, PowerShell, or Go installs, see the [getting started guide](https://cli.nylas.com/guides/getting-started).

## 2. Connect your iCloud Mail account

Head to [dashboard-v3.nylas.com](https://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.

```bash
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

```bash
# 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:

```bash
# 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:

```bash
# 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.

```bash
# 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:

| Task | Apple Mail.app | Nylas CLI |
| --- | --- | --- |
| Read inbox | GUI only | `nylas email list` |
| Search messages | Spotlight integration (GUI) | `nylas email search` |
| Export to JSON | Not supported | `--json` flag |
| Automation | AppleScript (deprecated APIs) | Pipe into bash/jq/Python |
| CI/CD integration | Not possible | Works in any shell |
| Server-side rules | iCloud Mail rules (web only) | Script your own filters |
| Multiple accounts | GUI account switcher | `--grant` flag |
| Hide My Email audit | Manual (check each message) | Search + jq filtering |

## Traditional IMAP vs Nylas CLI for iCloud

| Step | iCloud IMAP (mutt, imaplib, etc.) | Nylas CLI |
| --- | --- | --- |
| 2FA requirement | Must enable on Apple ID | Handled by Nylas |
| Credentials | Generate app-specific password at appleid.apple.com | `nylas auth config` |
| Server configuration | `imap.mail.me.com:993`, SSL required | Not required |
| Password rotation | Manual — log in to Apple ID portal, regenerate | Token refresh handled automatically |
| When Apple ID password changes | All app-specific passwords are revoked | Re-auth once in Nylas dashboard |
| Custom domain support | Same IMAP server, but different auth flow | All aliases accessible automatically |
| Search | IMAP SEARCH (limited server-side support) | `nylas email search` |

## Automation for privacy-focused iCloud users

Many people pick iCloud specifically for Apple's privacy posture. [Mail Privacy Protection](https://support.apple.com/en-us/HT212614) (introduced in iOS 15 and macOS Monterey) routes remote content through proxy servers and pre-fetches images so trackers cannot tie an open back to your IP or read time. Apple's broader [privacy policy](https://www.apple.com/legal/privacy/en-ww/) covers what data the company collects across its services and how it is used.

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

```bash
# 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 `~/.config/nylas/`, separate from Keychain.

## Next steps

- [Send iCloud Mail from the CLI](https://cli.nylas.com/guides/send-icloud-email-cli) — send from @icloud.com, custom domains, or Hide My Email
- [Manage iCloud calendar from the CLI](https://cli.nylas.com/guides/manage-icloud-calendar-cli) — create events and check availability
- [Send email from the terminal](https://cli.nylas.com/guides/send-email-from-terminal) — compose and send from iCloud Mail
- [List Gmail emails](https://cli.nylas.com/guides/list-gmail-emails) — same CLI for Google accounts
- [List Outlook emails](https://cli.nylas.com/guides/list-outlook-emails) — same workflow for Microsoft 365
- [List Yahoo Mail emails](https://cli.nylas.com/guides/list-yahoo-emails) — same workflow for Yahoo
- [List Exchange emails](https://cli.nylas.com/guides/list-exchange-emails) — for Exchange Online and on-prem
- [List IMAP emails](https://cli.nylas.com/guides/list-imap-emails) — for Fastmail, Zoho, self-hosted, and more
- [Give AI agents email access via MCP](https://cli.nylas.com/guides/ai-agent-email-mcp)
- [Full command reference](https://cli.nylas.com/docs/commands)