Every IMAP server needs its own hostname, port, TLS mode, and authentication method, and getting one wrong often shows up as a vague connection error. The usual fix is a config file per account. A better fix is to connect each mailbox once and use the same commands for all of them.
What is the IMAP configuration problem?
IMAP (RFC 9051, formerly RFC 3501) reaches almost every mailbox outside Gmail, Outlook, and Exchange: Fastmail, Zoho, self-hosted Dovecot, and ISP accounts. Reading from it with mutt, fetchmail, or Python’s imaplib means you handle the connection, folders, and MIME parsing yourself. Here is a .muttrc for one Fastmail 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
That is eight lines for one account. Add a self-hosted server with a self-signed certificate, an ISP account on a different port, and a university account that supports STARTTLS only on port 143, and you maintain three more blocks. Every tool that reads your mail needs its own copy of each block.
How do I connect an IMAP mailbox from the terminal?
Run the login command with the imap provider. It prompts for the IMAP username, password, host, and port (default 993) in the terminal, with no browser step.
After you connect an IMAP account, nylas email list returns the 10 most recent messages from INBOX by default. The same syntax works for Gmail, Outlook, and Exchange accounts.
# List recent messages
nylas email list
# Show only unread messages
nylas email list --unread
# Limit to 25 results
nylas email list --limit 25
# Show message IDs
nylas email list --id
The CLI replaces the IMAP FETCH details (sequence numbers and data items) with these flags. Search takes a free-text query plus filter flags, and reading a message needs its ID:
Can I connect self-hosted servers like Dovecot, Zimbra, or Cyrus?
Yes, as long as the server is reachable from the internet, because Nylas connects to it from its own infrastructure. Run nylas auth login --provider imap and enter your server’s username, password, host, and port. These are the hostnames and ports you would typically enter. Use your own domain’s values.
Server stack
IMAP hostname
Port
TLS
Dovecot (standard)
mail.yourdomain.com
993
Implicit TLS
Mail-in-a-Box
box.yourdomain.com
993
Implicit TLS
Zimbra
mail.yourdomain.com
993
Implicit TLS
Courier IMAP
mail.yourdomain.com
993 or 143
Implicit TLS or STARTTLS
Cyrus IMAP
mail.yourdomain.com
993
Implicit TLS
hMailServer (Windows)
mail.yourdomain.com
993
Implicit TLS
Once connected, nothing in the CLI is IMAP-specific:
nylas email list --limit 10
nylas email search "*" --from client@example.com
nylas email list --folder SENT --limit 5
What about ISP and telecom accounts?
Comcast, AT&T, Deutsche Telekom, and BT accounts typically use IMAP with your full address and a mail-specific password the ISP issues, such as AT&T’s Secure Mail Key. Settings change, so check your provider’s help page. AT&T mail runs on Yahoo’s infrastructure, but AT&T still publishes its own att.net hostnames. Enter the values when nylas auth login --provider imap prompts for them:
How do I connect to email from a CLI without an OAuth browser login?
For IMAP, nylas auth login --provider imap asks for your username, password, host, and port in the terminal. Yahoo asks for an app password and iCloud for an app-specific password. Google, Microsoft, and Exchange open a browser OAuth flow. For the CLI itself, nylas auth config --api-key sets an API key directly.
What if IMAP is part of your product?
If your application lets customers connect any mailbox, you need IMAP handled the same way you handle Gmail and Microsoft: one normalized message model, real-time webhooks for new mail, and no per-server code. The Nylas Email API works across Gmail, Microsoft 365, Exchange, Yahoo, iCloud, and IMAP providers through one integration. Install the CLI with brew install nylas/nylas-cli/nylas, connect one IMAP mailbox, and run nylas email list --unread. The full IMAP guide has more examples, and the Nylas IMAP provider guide covers the API side.
Frequently asked questions
How do I list and search my inbox from the command line?
Connect the mailbox once, then run nylas email list for the 10 most recent INBOX messages. Add --unread for unread only, --limit 25 for more, or --folder SENT for another folder. Search with nylas email search "*" --from client@example.com, and open a message with nylas email read and its ID.
How do I read IMAP email without configuring each server?
Connect each mailbox once with nylas auth login --provider imap, then use the same list, search, and read commands for IMAP, Gmail, Outlook, and Exchange accounts. You skip the per-account hostname, port, TLS mode, and authentication blocks that a mutt config needs.
How do I connect a self-hosted IMAP server like Dovecot?
Run nylas auth login --provider imap and enter the username, password, host, and port. For example, enter mail.yourdomain.com with port 993. The default port is 993. The same list, search, and read commands then work as for any other account.
How do I authenticate a CLI to email without an OAuth browser login?
For IMAP, nylas auth login --provider imap prompts for your username, password, host, and port in the terminal. Yahoo asks for an app password and iCloud for an app-specific password. Google, Microsoft, and Exchange use a browser OAuth flow.
Do ISP email accounts support OAuth over IMAP?
Usually not for third-party tools. These ISPs typically use IMAP with your full address and a mail-specific password the ISP issues, such as AT&T’s Secure Mail Key. Settings change, so check your ISP’s help page for current hostnames and ports.
When should I use an email API instead of the CLI?
Use the CLI for your own mailboxes. If your application needs every customer’s inbox, you need one normalized message model, real-time webhooks for new mail, and no per-server code, which is what the Nylas Email API provides.
Email and Contacts API 
Calendar API & Scheduler 
Notetaker API 
Agent Accounts 
Sales & CRM 
Recruiting & ATS 
Healthcare
Financial
Legal
Real Estate
Education
Field Services
Docs
SDKs
Guides
Integrations
API status
Changelog
Support
Professional Services
