How to List IMAP Emails from the Command Line

IMAP is still the backbone of email

IMAP (RFC 3501, published in 2003) is the protocol that powers email access for providers outside the Big Three (Google, Microsoft, Apple). According to Radicati Group's 2024 Email Statistics Report, there are 4.48 billion email users worldwide. While Gmail and Outlook dominate consumer email, a significant share of business and institutional email runs on IMAP-only servers.

Self-hosted email administrators, ISP account holders, university students, and users of privacy-focused providers like Fastmail or Posteo all depend on IMAP. The protocol works, but configuring IMAP clients from the command line is painful.

The IMAP configuration problem

Every IMAP server has its own hostname, port, TLS mode, and authentication method. To connect with mutt, fetchmail, or Python's imaplib, you need to know all four. Get one wrong and you'll stare at a connection timeout for 30 seconds before seeing a cryptic error.

Here's what a typical .muttrc configuration looks like for a single provider:

# .muttrc for Fastmail — 8 lines of config for one account
set imap_user = "you@fastmail.com"
set imap_pass = "app-specific-password-here"
set folder = "imaps://imap.fastmail.com:993/"
set spoolfile = "+INBOX"
set record = "+Sent"
set postponed = "+Drafts"
set ssl_starttls = yes
set ssl_force_tls = yes

Multiply this by every IMAP account you have. Now add a self-hosted server with a self-signed certificate, an ISP account with a different port, and a university account that only supports STARTTLS on port 143. That's three separate config blocks with different TLS settings, and any password change breaks the connection silently.

1. Install the Nylas CLI

brew install nylas/nylas-cli/nylas

Need a different install method? The getting started guide covers shell script, PowerShell, and Go.

2. Connect your IMAP account

Head to dashboard-v3.nylas.com, create an application, and connect your IMAP account. During setup, enter your IMAP server details (Nylas auto-detects settings for known providers like Fastmail and Zoho). Then configure the CLI:

nylas auth config
# Paste your API key when prompted

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

3. List your emails

# List recent messages
nylas email list

# Show only unread messages
nylas email list --unread

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

Self-hosted email servers (Dovecot, Postfix, Zimbra)

If you run your own mail server — Dovecot for IMAP, Postfix for SMTP, or an all-in-one stack like Mail-in-a-Box or Zimbra — the Nylas CLI connects the same way. The dashboard setup asks for your IMAP hostname and port. Nylas handles TLS negotiation, connection pooling, and IMAP IDLE keepalives.

Common self-hosted configurations and what to enter in the Nylas dashboard:

After connecting, the commands are identical to any other provider. There's nothing IMAP-specific in the CLI usage:

# Self-hosted Dovecot server — same commands as Gmail or Outlook
nylas email list --limit 10
nylas email search "from:client@example.com"
nylas email list --folder "Sent" --limit 5

ISP and telecom email accounts

Millions of people still use email addresses from their internet provider: Comcast/Xfinity (@comcast.net), AT&T (@att.net, @sbcglobal.net), Deutsche Telekom (@t-online.de), BT (@btinternet.com), and others. These accounts only offer IMAP access — no OAuth2, no REST API, just IMAP with a username and password.

ISP email accounts are notoriously fragile with traditional IMAP clients because ISPs frequently change their server settings. AT&T, for example, migrated from imap.mail.att.net to Yahoo's infrastructure in 2017, breaking every manually-configured client.

# Common ISP IMAP servers (for reference during Nylas dashboard setup)
# Comcast/Xfinity: imap.comcast.net:993
# AT&T:            imap.mail.att.net:993
# Verizon:         incoming.verizon.net:993
# Deutsche Telekom: secureimap.t-online.de:993
# BT Internet:     imap4.btconnect.com:993

# After connecting through the dashboard, it's the same commands:
nylas email list --limit 10

University and institutional email

Many universities run their own IMAP servers (often Cyrus or Dovecot behind a load balancer) rather than outsourcing to Google or Microsoft. MIT, Caltech, and most European universities still operate independent mail infrastructure. These accounts often have specific requirements:

• VPN may be required for off-campus IMAP access
• STARTTLS on port 143 instead of implicit TLS on port 993
• Kerberos or LDAP authentication instead of plain passwords
• Aggressive connection timeouts (often 5 minutes vs the IMAP standard of 30 minutes)

The Nylas CLI handles the connection-level details after you provide the server information during dashboard setup.

TLS, ports, and the STARTTLS confusion

The IMAP port situation confuses even experienced sysadmins. RFC 8314 (published in 2018) recommends implicit TLS on port 993 as the default. But many servers still support STARTTLS on port 143, and some older servers only support port 143.

The STARTTLS approach has a known vulnerability: a man-in-the-middle can strip the STARTTLS command before the client sees it, forcing a plaintext connection. This is why RFC 8314 recommends implicit TLS. The Nylas platform always uses TLS for IMAP connections.

IMAP vs POP3: why IMAP matters

Some older accounts (especially ISP email) offer both IMAP and POP3 access. The difference is significant:

If your provider offers both, always choose IMAP. The Nylas CLI doesn't support POP3 because IMAP provides a strictly superior interface for CLI operations — server-side search, folder navigation, and partial message fetch all require IMAP.

Aggregating multiple IMAP accounts

The strongest IMAP use case for the CLI is account aggregation. If you have a Fastmail account, a self-hosted server, and an ISP email, you'd normally configure each one separately in mutt or Thunderbird. With the Nylas CLI, each account is a grant:

# Switch between accounts using the --grant flag
nylas email list --grant "you@fastmail.com" --limit 5
nylas email list --grant "you@selfhosted.org" --limit 5
nylas email list --grant "you@comcast.net" --limit 5

# Search across a specific account
nylas email search "invoice" --grant "you@fastmail.com"

# Count unread across all accounts in one script
for grant in "you@fastmail.com" "you@selfhosted.org" "you@comcast.net"; do
  count=$(nylas email list --unread --json --grant "$grant" | jq length)
  echo "$grant: $count unread"
done

IMAP folder names are not standard

RFC 3501 defines INBOX as the only required folder name. Everything else — Sent, Drafts, Trash, Junk — is a convention, not a standard. Different servers use different names:

# List all folders on your IMAP server
nylas folder list

# Folder name differences across providers:
# Fastmail:   "Sent", "Trash", "Junk Mail", "Archive"
# Dovecot:    "Sent" or "INBOX.Sent" (namespace prefix varies)
# Zimbra:     "Sent", "Trash", "Junk"
# Zoho:       "Sent", "Trash", "Spam"
# Courier:    "INBOX.Sent", "INBOX.Trash" (dot-separated hierarchy)

# The Nylas CLI normalizes common folder names
nylas email list --folder "Sent"
nylas email list --folder "Drafts"
nylas email list --folder "Trash"

The INBOX. prefix is a Courier IMAP convention from the early 2000s. If you see it in nylas folder list output, your server uses the old-style namespace. The CLI handles both formats.

JSON output for IMAP automation

IMAP servers don't return JSON — they speak the IMAP protocol, which uses a proprietary text format defined in RFC 3501. The Nylas CLI translates IMAP responses into clean JSON that you can pipe into jq, a script, or an AI agent:

# Daily inbox digest from your self-hosted server
nylas email list --unread --json --limit 50 | \
  jq -r '.[] | "\(.date | split("T")[0]) | \(.from[0].name // .from[0].email) | \(.subject)"' | \
  column -t -s '|'

# Export the last 100 messages as a JSON file for analysis
nylas email list --limit 100 --json > inbox-export.json

# Find the most frequent senders
nylas email list --limit 200 --json | \
  jq -r '[.[] | .from[0].email] | group_by(.) |
  map({sender: .[0], count: length}) |
  sort_by(-.count) | .[:10] |
  .[] | "\(.count)	\(.sender)"'

IMAP provider reference

Server settings for popular IMAP providers (useful during Nylas dashboard setup — Nylas auto-detects most of these):

Next steps

• Send email from the terminal — compose and send from any IMAP account
• List Gmail emails — Gmail uses its own API, but the CLI commands are identical
• List Outlook emails — same workflow for Microsoft 365
• List Yahoo Mail emails — Yahoo supports both OAuth2 and IMAP
• List iCloud Mail emails — Apple's IMAP with extra authentication hoops
• List Exchange emails — for Exchange Online and on-prem
• Give AI agents email access via MCP
• Full command reference