mutt

• Gmail Setup
• NeoMutt Workflows and Usage (Gmail Users Guide)
• Proton Mail Setup for NeoMutt

Gmail Setup

Gmail Setup for NeoMutt

This guide covers configuring NeoMutt to send and receive emails using a Gmail account via IMAP and SMTP, including Google Account security setup, GPG password encryption, and sidebar configuration.

---

1. Prerequisites & Google Account Configuration

Modern Gmail requires two-factor authentication (2FA) and an App Password for IMAP/SMTP client access. Direct password authentication is blocked by Google.

1. Enable 2-Step Verification:

   • Go to Google Account Security.
   • Under "How you sign in to Google", turn on 2-Step Verification if not already enabled.

2. Generate an App Password:

   • Navigate to App Passwords.
   • Enter a custom app name (e.g., NeoMutt).
   • Record the generated 16-character password (e.g. abcd efgh ijkl mnop).

3. Enable IMAP in Gmail:

   • Open Gmail in your browser -> Settings (gear icon) -> See all settings.
   • Go to the Forwarding and POP/IMAP tab.
   • Select Enable IMAP.
   • Click Save Changes.

---

2. Securely Encrypt Your Password with GPG

Run gpg interactively to encrypt your App Password directly to a .gpg file:

gpg -e -r "your.email@gmail.com" -o ~/.config/neomutt/gmail_pass.gpg

1. Run the command above.
2. Paste or type your 16-character App Password.
3. Press Enter, then press Ctrl+D (EOF) to save and finish.

---

3. Configuration (~/.config/neomutt/neomuttrc)

Create ~/.config/neomutt/neomuttrc. The imap_pass and smtp_pass settings dynamically decrypt the GPG file at runtime:

# ==============================================================================
# Identity & Account Settings
# ==============================================================================
set realname = "Your Full Name"
set from = "your.email@gmail.com"
set use_from = yes

# Authentication (Dynamically decrypt password via GPG)
set imap_user = "your.email@gmail.com"
set imap_pass = `gpg --batch --quiet --decrypt ~/.config/neomutt/gmail_pass.gpg`

# IMAP Server Settings
set folder = "imaps://imap.gmail.com:993"
set spoolfile = "+INBOX"
set postponed = "+[Gmail]/Drafts"
set record = "+[Gmail]/Sent Mail"
set trash = "+[Gmail]/Trash"

# SMTP Server Settings (Sending Mail)
set smtp_url = "smtps://your.email@gmail.com@smtp.gmail.com:465/"
set smtp_pass = `gpg --batch --quiet --decrypt ~/.config/neomutt/gmail_pass.gpg`

# Mailboxes for NeoMutt Sidebar
named-mailboxes "Inbox"      "+INBOX"
named-mailboxes "Sent"       "+[Gmail]/Sent Mail"
named-mailboxes "Drafts"     "+[Gmail]/Drafts"
named-mailboxes "All Mail"   "+[Gmail]/All Mail"
named-mailboxes "Spam"       "+[Gmail]/Spam"
named-mailboxes "Trash"      "+[Gmail]/Trash"

# ==============================================================================
# NeoMutt Sidebar Settings
# ==============================================================================
set sidebar_visible = yes
set sidebar_width = 24
set sidebar_short_path = yes
set sidebar_next_new_wrap = yes
set sidebar_format = "%D%?Z? [%Z]?%* %?N?%N/?"

# Sidebar Navigation Keybindings
bind index,pager \Cp sidebar-prev           # Ctrl+p: Previous folder
bind index,pager \Cn sidebar-next           # Ctrl+n: Next folder
bind index,pager \Co sidebar-open           # Ctrl+o: Open folder
bind index,pager B sidebar-toggle-visible  # B: Toggle sidebar visibility

# ==============================================================================
# Cache & Performance
# ==============================================================================
set header_cache = "~/.cache/neomutt/headers"
set message_cachedir = "~/.cache/neomutt/bodies"
set certificate_file = "~/.config/neomutt/certificates"

# Connection & Sync Settings
set move = no                  # Do not auto-move read messages
set imap_keepalive = 900       # Keep IMAP connection active
set mail_check = 60            # Poll for new mail every 60s
set timeout = 10               # Idle timeout before checking mail

# ==============================================================================
# UI & Threading Settings
# ==============================================================================
set sort = threads             # Thread conversation view
set sort_aux = reverse-last-date-received
set sort_re = yes

---

4. Usage & Verification

1. Launch NeoMutt:

   neomutt
   

2. Sidebar Navigation:
   • Ctrl+n / Ctrl+p: Move cursor down/up through mailboxes in sidebar.
   • Ctrl+o: Select and switch to the highlighted sidebar folder.
   • B: Toggle sidebar visibility on/off.
3. Send Test Email: Press m in index view to compose and send a message.

NeoMutt Workflows and Usage (Gmail Users Guide)

This guide translates familiar Gmail web UI concepts into NeoMutt workflows. It covers interface navigation, reading, replying, searching, composing, attaching files, and sending emails directly from the command line.

---

1. Key Concepts: Gmail vs. NeoMutt

Gmail Concept	NeoMutt Equivalent	Explanation / Behavior
Labels / Folders	Mailboxes / Folders	Gmail labels map to IMAP folders like +[Gmail]/All Mail, +[Gmail]/Sent Mail, etc.
Archive (e or y)	Delete / Move (d or s)	In Gmail, "archiving" removes the INBOX label. In NeoMutt, move (s) the message to +[Gmail]/All Mail.
Threads / Conversations	Threaded View (sort = threads)	NeoMutt displays email chains visually nested as tree structures.
Search Bar (/)	Search (/) & Limit (l)	Search filters current mailbox; Limit filters displayed list to matching patterns.
Starred Messages	Flagged Messages (F)	Flagging a message sets the F flag, which maps to Gmail Stars.
Drafts	Postponed Messages (P)	Saving an unfinished email stores it in +[Gmail]/Drafts (Postponed folder).

---

2. Understanding the NeoMutt Interface

The NeoMutt UI is split into key sections:

+------------------+-------------------------------------------------------------+
| Sidebar          | Index View (Email List)                                     |
|                  |                                                             |
| N 1 Inbox (12)   |  1 N  Jan 12 Alice Smith     (1.2K) Meeting Notes           |
|   2 Sent         |  2    Jan 11 Bob Johnson     (4.5K) Re: Project Update     |
|   3 Drafts (1)   |  3 F  Jan 10 Server Alerts   (10K)  [URGENT] High Load     |
|   4 All Mail     |                                                             |
+------------------+-------------------------------------------------------------+
| Status Bar       | -- NeoMutt: Inbox [Msgs:12 New:1 Flagged:1] (threads) ---  |
+------------------+-------------------------------------------------------------+
| Help Line        | q:Quit  d:Del  r:Reply  m:Mail  c:ChangeFolder  /:Search    |
+------------------+-------------------------------------------------------------+

Status Flags in Index View

• N: New / Unread email
• O: Old (unread, but seen in previous session)
• r: Replied to
• F: Flagged / Starred
• D: Marked for deletion
• +: Message is addressed specifically to you

---

3. Navigation & Reading Messages

Moving Between Messages and Folders

• j / k (or Down / Up arrows): Move to next/previous email in list.
• Enter / Space: Open highlighted email in Pager view.
• q: Exit current view (leave message view back to index, or quit NeoMutt from index).
• c: Change mailbox (e.g. type +[Gmail]/Spam or =INBOX and press Enter).
• Sidebar Controls:
  • Ctrl+n: Move to next folder in sidebar.
  • Ctrl+p: Move to previous folder in sidebar.
  • Ctrl+o: Open highlighted folder in sidebar.
  • B: Toggle sidebar visibility.

Reading Messages in Pager View

• Space: Page down / scroll down through email text.
• -: Page up / scroll up.
• J / K: Jump to next / previous thread.
• v: View attachments list inside the email.
• h: Toggle display of raw email headers.

---

4. Searching & Filtering Mail

NeoMutt provides powerful search syntax using pattern modifiers:

Search within Current Mailbox (/)

Press / and enter a search pattern:

• / Alice: Search subject and body for "Alice".
• /~f Alice: Search messages From Alice.
• /~s Meeting: Search messages with Subject containing "Meeting".
• /~b "project update": Search message Body for phrase.
• /~N: Search for New (unread) messages.
• /~F: Search for Flagged (starred) messages.
• /~d <1d: Search for messages received in the last 1 day.

Press n to jump to the next search match, or N to jump to the previous match.

Filtering (Limiting) the View (l)

Press l (lowercase L) to hide all emails except those matching a pattern:

• l ~N: Show only unread emails.
• l ~f boss@example.com: Show only emails from boss@example.com.
• l all: Reset limit (show all emails again).

---

5. Replying, Forwarding & Managing Mail

• r: Reply to sender.
• g: Group reply (Reply All).
• f: Forward message.
• d: Mark message for deletion (purged on exit/folder sync).
• u: Undelete marked message.
• F: Flag / Star message.
• N: Toggle new/read status.
• s: Save / Move message to another IMAP folder.

---

6. Composing & Drafting Emails

Creating a New Email (m)

1. Press m in index view.
2. Enter recipient address (To:) and press Enter.
3. Enter subject (Subject:) and press Enter.
4. NeoMutt opens your configured text editor (e.g. Vim, Nano).
5. Type your email body, save, and exit the editor.

The Compose Menu

After exiting your editor, you are placed in NeoMutt's Compose Menu:

-- NeoMutt: Compose  [To: user@example.com, Subject: Test] -------------------
From: Your Name <your.email@gmail.com>
To: user@example.com
Cc:
Bcc:
Subject: Test
Attachments:
- I     1 /tmp/neomutt-body  [text/plain, 7bit, 0.1K]

y:Send  q:Abort  p:Postpone  e:EditBody  a:AttachFile  t:To  c:Cc  s:Subj

• y: Send the email immediately.
• a: Attach file (opens file browser to select file).
• p: Postpone (saves email to Gmail Drafts folder to edit later).
• e: Re-edit email body in text editor.
• t: Edit To: recipient.
• c: Add Cc: recipient.
• b: Add Bcc: recipient.
• s: Edit Subject:.
• q: Cancel / Abort composition.

Resuming Postponed Drafts (R)

Press R in index view to open the postponed draft list and resume editing.

---

7. Command Line Sending & Attachments

NeoMutt can be executed non-interactively directly from the shell or scripts to send emails with attachments.

Send Simple Email from Terminal

echo "This is the email body." | neomutt -s "Server Notification" recipient@example.com

Send Email with Attachment (-a)

neomutt -s "Quarterly Report" -a /path/to/report.pdf -- recipient@example.com < /path/to/message.txt

Note: The -- separator is required to denote the end of attachment flags before recipient addresses.

Send to Multiple Recipients with Attachments

neomutt -s "Project Backup"   -a /tmp/backup.tar.gz   -a /tmp/logs.txt   -- user1@example.com user2@example.com < /dev/null

Proton Mail Setup for NeoMutt

Because Proton Mail uses end-to-end encryption, standard email clients cannot connect directly to Proton Mail servers using normal IMAP/SMTP.

To access Proton Mail via NeoMutt, you must run a bridge service locally that decrypts/encrypts messages on your machine and exposes local IMAP/SMTP endpoints for NeoMutt.

---

1. Prerequisites: Bridge Service Options

There are two primary ways to run the bridge on Linux:

Option A: Official Proton Mail Bridge (Recommended for paid accounts)

The official desktop/CLI bridge provided by Proton.

1. Download and install Proton Mail Bridge from the official site or package manager:

   # Arch Linux (AUR)
   yay -S protonmail-bridge
   
   # Debian / Ubuntu (via official DEB package)
   sudo dpkg -i protonmail-bridge_*.deb
   

2. Open Proton Mail Bridge and log in with your Proton credentials.
3. Note down the local IMAP/SMTP credentials generated by Bridge (typically):
   • IMAP Host: 127.0.0.1 (Port 1143, STARTTLS)
   • SMTP Host: 127.0.0.1 (Port 1025, STARTTLS)
   • Username: Your full Proton email address
   • Password: Bridge-generated app password (not your main Proton password)

---

Option B: Hydroxide (Open-Source CLI Bridge)

A lightweight third-party open-source CLI bridge written in Go. Works great on headless servers.

1. Install Hydroxide:

   # Arch Linux
   sudo pacman -S hydroxide
   

2. Authenticate with Proton Mail:

   hydroxide auth <your-username>
   

3. Start Hydroxide services:

   hydroxide imap &
   hydroxide smtp &
   

4. Generate bridge status/credentials:

   hydroxide card
   

---

2. NeoMutt Configuration (~/.config/neomutt/neomuttrc)

Add the following profile block to your ~/.config/neomutt/neomuttrc (or create a dedicated profile file like ~/.config/neomutt/profiles/proton):

# ==============================================================================
# Proton Mail Account Settings
# ==============================================================================
set realname = "Your Name"
set from = "your.email@proton.me"
set use_from = yes

# Authentication details (Proton Bridge local credentials)
set imap_user = "your.email@proton.me"
set imap_pass = "your-bridge-generated-password"

# Local Bridge IMAP Settings
set folder = "imap://127.0.0.1:1143/"
set spoolfile = "+INBOX"
set postponed = "+Drafts"
set record = "+Sent"
set trash = "+Trash"

# Local Bridge SMTP Settings
set smtp_url = "smtp://your.email@proton.me@127.0.0.1:1025/"
set smtp_pass = "your-bridge-generated-password"

# Disable SSL verification for localhost STARTTLS (Bridge handles encryption)
set ssl_starttls = yes
set ssl_force_tls = no

# Mailboxes for NeoMutt Sidebar
named-mailboxes "Inbox"   "+INBOX"
named-mailboxes "Drafts"  "+Drafts"
named-mailboxes "Sent"    "+Sent"
named-mailboxes "Archive" "+Archive"
named-mailboxes "Spam"    "+Spam"
named-mailboxes "Trash"   "+Trash"

# Cache Directories
set header_cache = "~/.cache/neomutt/proton/headers"
set message_cachedir = "~/.cache/neomutt/proton/bodies"

Ensure the local cache directories exist:

mkdir -p ~/.cache/neomutt/proton/headers ~/.cache/neomutt/proton/bodies

---

3. Securing Bridge Credentials with GPG

As with Gmail, encrypt your local Bridge password using GPG:

1. Store password in encrypted file:

   echo "your-bridge-generated-password" | gpg -e -r "your.email@proton.me" -o ~/.config/neomutt/proton_pass.gpg
   

2. In ~/.config/neomutt/neomuttrc, dynamically set credentials:

   set imap_pass = `gpg --batch --quiet --decrypt ~/.config/neomutt/proton_pass.gpg`
   set smtp_pass = `gpg --batch --quiet --decrypt ~/.config/neomutt/proton_pass.gpg`
   

---

4. Running as a Background Service (Systemd)

To make sure the Bridge runs automatically in the background so NeoMutt can connect anytime:

Create ~/.config/systemd/user/proton-bridge.service:

[Unit]
Description=Proton Mail Bridge
After=network.target

[Service]
ExecStart=/usr/bin/protonmail-bridge --non-interactive
Restart=on-failure

[Install]
WantedBy=default.target

Enable and start the service:

systemctl --user daemon-reload
systemctl --user enable --now proton-bridge