List Your IMAP Emails from the Command Line

The problem with IMAP clients

Connecting to an IMAP server from the command line usually means configuring mutt, fetchmail, or offlineimap with server-specific hostnames, ports, TLS settings, and credentials. Each provider has different settings, and debugging connection issues is painful.

Python's imaplib works but requires writing boilerplate for login, folder selection, search, and message parsing. There is no standard CLI that works across all IMAP providers out of the box.

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 IMAP account

Head to dashboard-v3.nylas.com, create an application, and connect your IMAP account (Fastmail, ProtonMail Bridge, Zoho, or any IMAP-compatible server). Then grab 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

# 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 "project update" --limit 5

# Search by sender
nylas email search "from:team@company.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'

A quick script to summarize your inbox:

#!/bin/bash
unread=$(nylas email list --unread --json | jq length)
echo "Unread emails: $unread"

nylas email list --unread --json \
  | jq -r '.[] | "\(.from[0].email): \(.subject)"' \
  | head -5

7. Supported IMAP providers

The Nylas CLI works with any standard IMAP server, including:

• Fastmail — full IMAP support with app passwords or OAuth
• ProtonMail — via ProtonMail Bridge (local IMAP proxy)
• Zoho Mail — IMAP access with app-specific passwords
• Self-hosted — Dovecot, Courier, Cyrus, or any RFC 3501-compliant server

8. Traditional IMAP clients vs Nylas CLI

Here is what it takes to list emails from an IMAP server with each approach:

9. Common IMAP server settings

If you are connecting an IMAP account through the Nylas dashboard, here are the server settings for popular providers. Nylas auto-detects most of these, but they are useful for troubleshooting:

10. IMAP folder mapping

IMAP folder names are not standardized — different servers use different names for the same concept. The Nylas CLI normalizes these automatically:

# List all folders to see what your server uses
nylas folder list

# Common folder name differences:
# Gmail:      "[Gmail]/Sent Mail"   → mapped to "Sent"
# Outlook:    "Sent Items"          → mapped to "Sent"
# Fastmail:   "Sent"                → "Sent"
# Dovecot:    "Sent" or "INBOX.Sent" → mapped to "Sent"

# The CLI normalizes these, but you can also use the raw names
nylas email list --folder "Sent"
nylas email list --folder "Drafts"
nylas email list --folder "Trash"

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 iCloud Mail emails — same workflow for Apple
• List Exchange emails — same workflow for Exchange
• Give AI agents email access via MCP
• Full command reference