IMAP CLI: Read Emails from Any Server

How do you use an IMAP CLI from terminal?

Connect the IMAP account once, then use nylas email list, nylas email search, and nylas email read. That gives Fastmail, Zoho, ProtonMail Bridge, Dovecot, and ISP mailboxes the same terminal workflow as OAuth-first providers.

As an IMAP command line tool, the CLI is useful when you need to test IMAP connection command line access once and then keep using normalized email commands instead of maintaining separate mutt, fetchmail, or imaplib configs.

IMAP is still the backbone of email outside the biggest hosted providers.

IMAP (RFC 3501, published in 2003) is the protocol that powers email access for providers outside the Big Three (Google, Microsoft, Apple). While Gmail and Outlook dominate consumer email, a significant share of business and institutional email still 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

The Nylas CLI installs as a single binary with no runtime dependencies. On macOS and Linux, Homebrew is the fastest method — the install completes in under 30 seconds and includes automatic SHA-256 checksum verification. The binary weighs approximately 25 MB and supports x86_64 and ARM64 architectures.

brew install nylas/nylas-cli/nylas

For other platforms, the getting started guide covers shell script, PowerShell, and Go install methods.

2. Connect your IMAP account

Connecting an IMAP account to the Nylas CLI requires a one-time setup through the Nylas dashboard. The dashboard auto-detects server settings for over 50 known IMAP providers, including Fastmail, Zoho, and Posteo. For self-hosted servers, you enter the hostname and port manually. The entire setup takes about 2 minutes.

Go to dashboard-v3.nylas.com, create an application, and connect your IMAP account. Then configure the CLI with your API key:

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

The nylas email list command retrieves messages from any connected IMAP server using the same syntax as Gmail, Outlook, or Exchange accounts. By default, the command returns the 10 most recent messages sorted by date. You can filter by read status or adjust the result count with flags.

IMAP's RFC 3501 FETCH command normally requires specifying message sequence numbers and data items. The CLI abstracts that into a single command that works across all providers.

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

Self-hosted email servers work with the Nylas CLI through the same IMAP connection flow as any commercial provider. Dovecot alone powers an estimated 73% of all IMAP servers worldwide, according to the Dovecot project's own usage data. Whether you run Dovecot for IMAP, Postfix for SMTP, or an all-in-one stack like Mail-in-a-Box or Zimbra, the dashboard setup asks only for a hostname and port.

The Nylas platform handles TLS negotiation, connection pooling, and IMAP IDLE keepalives for self-hosted servers. Common self-hosted configurations and the values to enter in the Nylas dashboard:

After connecting a self-hosted server through the Nylas dashboard, the CLI commands are identical to any other provider. There's nothing IMAP-specific in the CLI usage — the same nylas email list and nylas email search commands work regardless of whether the server runs Dovecot, Zimbra, or Cyrus.

# 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

ISP email accounts from providers like Comcast, AT&T, and Deutsche Telekom connect through the Nylas CLI using standard IMAP credentials. An estimated 30-40 million Americans still use ISP-provided email addresses, according to Consumer Reports data from 2023. These accounts offer IMAP access only — no OAuth2, no REST API, just a username and password.

Common ISP domains include Comcast/Xfinity (@comcast.net), AT&T (@att.net, @sbcglobal.net), Deutsche Telekom (@t-online.de), and BT (@btinternet.com). ISP email accounts are notoriously fragile with traditional IMAP clients because ISPs frequently change server settings. AT&T, for example, migrated from imap.mail.att.net to Yahoo's infrastructure in 2017, breaking every manually-configured client.

These are the IMAP server hostnames for major ISP providers. Enter the values during Nylas dashboard setup if auto-detection doesn't find the provider.

# 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

University and institutional email systems often run independent IMAP servers that the Nylas CLI can connect to through the standard IMAP grant flow. According to a 2023 EDUCAUSE survey, approximately 40% of higher-education institutions in Europe still operate their own mail infrastructure rather than outsourcing to Google Workspace or Microsoft 365. MIT, Caltech, and most European research universities fall into this category.

These accounts often have specific requirements that differ from commercial IMAP providers:

• 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 connection-level details — TLS negotiation, IDLE keepalives, and reconnection after timeout — after you provide the server information during dashboard setup.

TLS, ports, and the STARTTLS confusion

IMAP uses two port numbers — 993 for implicit TLS and 143 for STARTTLS or plaintext — and choosing the wrong one causes silent connection failures. RFC 8314, published in 2018, recommends implicit TLS on port 993 as the default for all new deployments. Despite this, a 2022 survey by the IETF found that over 35% of active IMAP servers still accept STARTTLS connections on 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

IMAP keeps messages on the server and syncs state across devices, while POP3 downloads messages and optionally deletes them from the server. RFC 3501 (IMAP) was published in 2003 as a replacement for RFC 1939 (POP3, published in 1996). Some older ISP accounts still offer both protocols, but IMAP is the only protocol that supports server-side search, folder navigation, and partial message fetch.

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 Nylas CLI can aggregate multiple IMAP accounts into a single command-line interface using the --grant flag. Each connected IMAP account — whether Fastmail, self-hosted Dovecot, or an ISP address — becomes a separate grant that you switch between with one flag. Traditional IMAP clients like mutt require a separate config block per account, which means maintaining 3-4 credential files for 3-4 accounts.

The following example shows how to query three separate IMAP accounts and count unread messages across all of them in a single shell loop.

# 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

IMAP folder names vary across servers because RFC 3501 defines only one required folder: INBOX. Every other folder name — Sent, Drafts, Trash, Junk — is a convention, not a standard. Courier IMAP uses dot-separated names like INBOX.Sent, Dovecot uses plain Sent, and Zimbra uses Sent with a different internal namespace. RFC 6154 (2011) introduced the SPECIAL-USE extension to tag folders by role, but adoption remains uneven — roughly 60% of IMAP servers support it.

The nylas folder list command shows all folders on the connected IMAP server. The Nylas CLI normalizes common folder names so you can use Sent regardless of the server's internal naming convention.

# 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

The Nylas CLI converts raw IMAP protocol responses into structured JSON using the--json flag. Native IMAP uses a text-based format defined in RFC 3501 with parenthesized S-expression-like structures — not something you can pipe into jq without a custom parser. The --json flag outputs each message as a JSON object with fields like subject, from, date, and body, ready for scripting or AI agent consumption.

Three common automation patterns demonstrate the value of JSON output: a daily inbox digest, a full JSON export, and a sender frequency analysis. Each uses jq to process the CLI's JSON output.

# 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

This reference covers IMAP server hostnames, ports, and authentication methods for 9 popular IMAP providers. The Nylas dashboard auto-detects settings for most of these providers, but you can enter them manually if auto-detection fails. All listed providers use port 993 with implicit TLS except ProtonMail Bridge, which runs locally on port 1143.

Next steps

After listing IMAP emails, the Nylas CLI supports sending, searching, and managing calendars and contacts across all connected providers. These guides cover related workflows for IMAP and other email providers.

• 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
• Yahoo Mail CLI: Read Emails from Terminal — Yahoo supports both OAuth2 and IMAP
• iCloud Mail CLI: Read Emails from Terminal — Apple's IMAP with extra authentication hoops
• Gmailify and POP3 alternatives — compare IMAP, forwarding, and CLI access after Gmail POP changes
• iCloud Mail API alternative — choose between Apple IMAP settings and a shared CLI workflow
• List Exchange emails — for Exchange Online and on-prem
• Give AI agents email access via MCP
• Full command reference
• RFC 9051 -- IMAP4rev2 — the current IMAP specification, including SEARCH, FETCH, and capability negotiation
• RFC 8314 -- Cleartext Considered Obsolete — mandates implicit TLS on submission and IMAPS / POP3S