# mutt

# 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](https://myaccount.google.com/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](https://myaccount.google.com/apppasswords).
   - 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:

```bash
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:

```muttrc
# ==============================================================================
# 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:
   ```bash
   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:

```text
+------------------+-------------------------------------------------------------+
| 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**:

```text
-- 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
```bash
echo "This is the email body." | neomutt -s "Server Notification" recipient@example.com
```

### Send Email with Attachment (`-a`)
```bash
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
```bash
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:
   ```bash
   # 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:
   ```bash
   # Arch Linux
   sudo pacman -S hydroxide
   ```
2. Authenticate with Proton Mail:
   ```bash
   hydroxide auth <your-username>
   ```
3. Start Hydroxide services:
   ```bash
   hydroxide imap &
   hydroxide smtp &
   ```
4. Generate bridge status/credentials:
   ```bash
   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`):

```muttrc
# ==============================================================================
# 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:
```bash
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:
   ```bash
   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:
   ```muttrc
   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`:

```ini
[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:
```bash
systemctl --user daemon-reload
systemctl --user enable --now proton-bridge
```