ssp.sh / dotfiles
clone of my dotfiles.ssp.sh
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

update

sspaeti e5e1ee0e 344d0712

+84 -282
+84 -282
mutt/.config/mutt/notmuch/README.md
··· 1 1 # Notmuch Email Screening Setup 2 2 3 - This directory contains the configuration and scripts for using **notmuch** with Neomutt for tag-based email management instead of folder-based organization. 3 + Tag-based email management with **notmuch** + **mbsync** for Neomutt. 4 4 5 5 ## Overview 6 6 7 - Instead of moving emails between folders (INBOX, ScreenedOut, Feed, etc.), notmuch uses **tags** to organize emails: 7 + Instead of moving emails between folders, notmuch uses **tags**: 8 8 9 - - `screened-in` - Approved senders (stay in inbox) 9 + - `screened-in` - Approved senders (inbox) 10 10 - `screened-out` - Blocked senders (spam) 11 11 - `feed` - Newsletters/feeds 12 - - `papertrail` - Receipts and papertrail items 13 - - `to-screen` - New emails needing manual review 14 - - Plus standard tags: `inbox`, `archive`, `spam`, `waiting`, `someday`, etc. 15 - 16 - ## Directory Structure 17 - 18 - ``` 19 - ~/.config/mutt/ 20 - ├── muttrc-notmuch # Main Neomutt config (use instead of muttrc) 21 - └── notmuch/ 22 - ├── README.md # This file 23 - ├── notmuch-config # Notmuch database configuration 24 - ├── notmuch_screening.sh # Tag-based screening script 25 - ├── mbsyncrc.example # Example mbsync config (recommended) 26 - └── sync/ 27 - ├── notmuch_sync.sh # Sync script for offlineimap + notmuch 28 - └── mbsync_notmuch_sync.sh # Sync script for mbsync + notmuch (recommended) 29 - ``` 30 - 31 - ## Required Files (Already in Top-Level Directory) 32 - 33 - These files from your existing setup are still needed: 12 + - `papertrail` - Receipts 13 + - `to-screen` - Needs manual review 14 + - Plus: `inbox`, `archive`, `spam`, `waiting`, `someday`, etc. 34 15 35 - - `~/.config/mutt/screened_in.txt` - List of approved email addresses 36 - - `~/.config/mutt/screened_out.txt` - List of blocked email addresses 37 - - `~/.config/mutt/feed.txt` - List of newsletter/feed email addresses 38 - - `~/.config/mutt/papertrail.txt` - List of papertrail email addresses 39 - - `~/.config/mutt/color.muttrc` - Your color scheme 40 - - `~/.config/mutt/signature` - Email signature 41 - - `~/.config/mutt/mailcap` - MIME type handlers 42 - - `~/.dotfiles/zsh/.secret.muttrc` - Password/secrets file 43 - 44 - ## Installation & Setup 45 - 46 - ### Prerequisites 47 - 48 - Install required packages on Arch Linux: 16 + ## Quick Start 49 17 50 18 ```bash 51 - # For notmuch 52 - sudo pacman -S notmuch 19 + # 1. Install packages 20 + sudo pacman -S notmuch isync 53 21 54 - # For mbsync (recommended over offlineimap) 55 - sudo pacman -S isync 22 + # 2. Configure mbsync 23 + cp ~/.config/mutt/notmuch/mbsyncrc.example ~/.mbsyncrc 24 + # Edit ~/.mbsyncrc - update PassCmd for password 56 25 57 - # If keeping offlineimap 58 - sudo pacman -S offlineimap 26 + # 3. Initial sync 27 + cd ~/.config/mutt 28 + make notmuch-sync # Downloads all emails (takes time) 59 29 60 - # Required utilities (likely already installed) 61 - sudo pacman -S formail grep sed coreutils 62 - ``` 30 + # 4. Initialize notmuch 31 + make notmuch-init # Indexes emails 63 32 64 - ### Option 1: Keep offlineimap (Easier Migration) 65 - 66 - 1. **Initialize notmuch database:** 67 - ```bash 68 - notmuch setup 69 - ``` 70 - - Database path: `/home/sspaeti/Documents/mutt/sspaeti.com` 71 - - Your name: `Simon Späti` 72 - - Primary email: `simon@ssp.sh` 73 - - Other emails: `simon@sspaeti.com;simu@sspaeti.com` 33 + # 5. Run screening 34 + make notmuch-screen # Tags emails based on lists 74 35 75 - 2. **Or use the pre-configured notmuch-config:** 76 - ```bash 77 - export NOTMUCH_CONFIG=~/.config/mutt/notmuch/notmuch-config 78 - notmuch new 79 - ``` 36 + # 6. Launch neomutt 37 + neomutt 38 + ``` 80 39 81 - 3. **Test the setup:** 82 - ```bash 83 - # Run initial screening 84 - ~/.config/mutt/notmuch/notmuch_screening.sh 85 - 86 - # Launch Neomutt with notmuch config 87 - neomutt -F ~/.config/mutt/muttrc-notmuch 88 - ``` 89 - 90 - 4. **Update your sync workflow:** 91 - - Use `~/.config/mutt/notmuch/sync/notmuch_sync.sh` instead of your old sync script 92 - - Or set up a cron job/systemd timer for automatic syncing 93 - 94 - ### Option 2: Upgrade to mbsync (Recommended) 95 - 96 - **Why mbsync?** 97 - - 3-5x faster than offlineimap 98 - - Actively maintained (offlineimap is dormant) 99 - - Better IMAP compliance 100 - - Lower resource usage 101 - 102 - **Setup Steps:** 103 - 104 - 1. **Configure mbsync:** 105 - ```bash 106 - cp ~/.config/mutt/notmuch/mbsyncrc.example ~/.mbsyncrc 107 - ``` 108 - 109 - 2. **Edit `~/.mbsyncrc`:** 110 - - Update the `PassCmd` line to match your password method 111 - - Verify folder names match your IMAP server 112 - 113 - 3. **Initial sync (takes a while):** 114 - ```bash 115 - mbsync -V sspaeti.com 116 - ``` 117 - 118 - 4. **Initialize notmuch:** 119 - ```bash 120 - export NOTMUCH_CONFIG=~/.config/mutt/notmuch/notmuch-config 121 - notmuch new 122 - ``` 123 - 124 - 5. **Run initial screening:** 125 - ```bash 126 - ~/.config/mutt/notmuch/notmuch_screening.sh 127 - ``` 128 - 129 - 6. **Launch Neomutt:** 130 - ```bash 131 - neomutt -F ~/.config/mutt/muttrc-notmuch 132 - ``` 133 - 134 - 7. **Update your workflow:** 135 - - Use `~/.config/mutt/notmuch/sync/mbsync_notmuch_sync.sh` for syncing 136 - 137 - ## Usage 138 - 139 - ### Starting Neomutt with Notmuch 40 + ## Daily Usage 140 41 141 42 ```bash 142 - neomutt -F ~/.config/mutt/muttrc-notmuch 143 - ``` 43 + cd ~/.config/mutt 144 44 145 - Or create an alias in your shell config: 146 - ```bash 147 - alias mutt="neomutt -F ~/.config/mutt/muttrc-notmuch" 45 + make sync # Sync once (fetch → screen → sync back) 46 + make # Start continuous loop (syncs every 10 min) 47 + make help # Show all commands 148 48 ``` 149 49 150 - ### Key Bindings (Same as Before!) 50 + ## Key Bindings in Neomutt 151 51 152 - **Screening macros:** 153 - - `I` - Screen in sender (add to approved list, tag as `screened-in`) 154 - - `O` - Screen out sender (add to blocked list, tag as `screened-out`) 155 - - `F` - Add sender to Feed list (tag as `feed`) 156 - - `P` - Add sender to PaperTrail list (tag as `papertrail`) 52 + **Screening (in email view):** 53 + - `I` - Approve sender → inbox 54 + - `O` - Block sender → spam 55 + - `F` - Add to Feed 56 + - `P` - Add to PaperTrail 157 57 158 - **Navigation (using virtual mailboxes):** 159 - - `gi` - Go to INBOX 160 - - `gk` - Go to ToScreen (emails needing review) 161 - - `go` - Go to ScreenedOut 162 - - `gf` - Go to Feed 163 - - `gp` - Go to PaperTrail 164 - - `gw` - Go to Waiting 165 - - `gm` - Go to Someday 166 - - `ga` - Go to Archive 167 - - `gt` - Go to Trash 168 - - `gs` - Go to Sent 58 + **Navigation:** 59 + - `gi` - INBOX, `gk` - ToScreen, `go` - ScreenedOut 60 + - `gf` - Feed, `gp` - PaperTrail, `gw` - Waiting 61 + - `gm` - Someday, `ga` - Archive, `gt` - Trash 169 62 170 - **Tagging macros:** 171 - - `Mi` - Tag as inbox 172 - - `Mo` - Tag as screened-out 173 - - `Mf` - Tag as feed 174 - - `Mp` - Tag as papertrail 175 - - `Mw` - Tag as waiting 176 - - `Mm` - Tag as someday 177 - - `Ma` - Tag as archive 178 - - `Mt` - Tag as trash 63 + **Tagging:** 64 + - `Mi` - inbox, `Mo` - screened-out, `Mf` - feed 65 + - `Mw` - waiting, `Mm` - someday, `Ma` - archive 179 66 180 67 **Sync:** 181 - - `S` - Sync emails and run screening 182 - - `A` - Run screening only 183 - 184 - ### How Screening Works 185 - 186 - 1. **Automatic screening on sync:** 187 - - New emails are indexed by notmuch 188 - - Screening script checks sender against your lists 189 - - Tags are applied automatically 190 - 191 - 2. **Manual screening:** 192 - - Review emails in "ToScreen" mailbox (`gk`) 193 - - Press `I` to approve sender → moves to INBOX 194 - - Press `O` to block sender → tags as spam 195 - - Press `F` for feeds, `P` for papertrail 196 - 197 - 3. **List updates:** 198 - - When you approve/block a sender, their email is added to the respective .txt file 199 - - Previously received emails from that sender are retagged automatically 200 - 201 - ## Files Explained 202 - 203 - ### notmuch-config 204 - Notmuch database configuration. Defines: 205 - - Database path 206 - - Your email addresses 207 - - Default tags for new emails 208 - - Synchronization settings 209 - 210 - ### notmuch_screening.sh 211 - Core screening logic. This script: 212 - 1. Runs `notmuch new` to index new emails 213 - 2. Reads your screened lists (screened_in.txt, screened_out.txt, etc.) 214 - 3. Applies appropriate tags to emails based on sender 215 - 4. Retags emails in ToScreen if sender status changed 216 - 217 - **You should run this after each sync.** 218 - 219 - ### sync/notmuch_sync.sh 220 - Complete sync workflow for **offlineimap**: 221 - 1. Checks Wi-Fi connection 222 - 2. Runs offlineimap to fetch new emails 223 - 3. Runs notmuch screening 224 - 4. Syncs again to push any local changes 225 - 226 - ### sync/mbsync_notmuch_sync.sh 227 - Complete sync workflow for **mbsync**: 228 - 1. Checks Wi-Fi connection 229 - 2. Runs mbsync to fetch new emails 230 - 3. Runs notmuch screening 231 - 4. Syncs again to push any local changes 232 - 233 - ### mbsyncrc.example 234 - Template configuration for mbsync. Copy to `~/.mbsyncrc` and customize. 235 - 236 - ## Automation 237 - 238 - ### Systemd Timer (Recommended) 239 - 240 - Create `~/.config/systemd/user/mutt-sync.service`: 241 - ```ini 242 - [Unit] 243 - Description=Mutt Email Sync with Notmuch 68 + - `S` - Sync all, `A` - Screen only 244 69 245 - [Service] 246 - Type=oneshot 247 - ExecStart=/home/sspaeti/.config/mutt/notmuch/sync/mbsync_notmuch_sync.sh 248 - ``` 70 + ## How It Works 249 71 250 - Create `~/.config/systemd/user/mutt-sync.timer`: 251 - ```ini 252 - [Unit] 253 - Description=Sync emails every 10 minutes 254 - 255 - [Timer] 256 - OnBootSec=2min 257 - OnUnitActiveSec=10min 258 - 259 - [Install] 260 - WantedBy=timers.target 261 - ``` 262 - 263 - Enable and start: 264 - ```bash 265 - systemctl --user enable --now mutt-sync.timer 266 - ``` 267 - 268 - ### Cron Job Alternative 269 - 270 - Add to crontab (`crontab -e`): 271 - ```bash 272 - */10 * * * * /home/sspaeti/.config/mutt/notmuch/sync/mbsync_notmuch_sync.sh 273 - ``` 72 + 1. **mbsync** downloads emails from IMAP to local Maildir 73 + 2. **notmuch** indexes emails and applies tags based on: 74 + - `~/.dotfiles/mutt/.lists/screened_in.txt` 75 + - `~/.dotfiles/mutt/.lists/screened_out.txt` 76 + - `~/.dotfiles/mutt/.lists/feed.txt` 77 + - `~/.dotfiles/mutt/.lists/papertrail.txt` 78 + 3. Emails from unknown senders get tagged `to-screen` 79 + 4. Review `ToScreen` mailbox and press `I`/`O`/`F`/`P` to categorize 274 80 275 81 ## Troubleshooting 276 82 277 - ### Notmuch can't find database 83 + **Notmuch can't find database:** 278 84 ```bash 279 85 export NOTMUCH_CONFIG=~/.config/mutt/notmuch/notmuch-config 280 86 notmuch new 281 87 ``` 282 88 283 - ### Tags not applying 284 - Check that your .txt files have proper formatting: 89 + **Virtual mailboxes empty:** 285 90 ```bash 286 - # Remove trailing whitespace 287 - sed -i 's/[[:space:]]*$//' ~/.config/mutt/screened_in.txt 91 + # Check tags 92 + NOTMUCH_CONFIG=~/.config/mutt/notmuch/notmuch-config notmuch search tag:inbox 288 93 ``` 289 94 290 - ### Virtual mailboxes empty 291 - Run notmuch manually to check: 95 + **mbsync authentication fails:** 292 96 ```bash 293 - notmuch search tag:to-screen 294 - notmuch search tag:inbox 97 + # Test password extraction 98 + grep imap_pass ~/.dotfiles/zsh/.secret.muttrc | cut -d'"' -f2 295 99 ``` 296 100 297 - ### mbsync authentication fails 298 - Check password command in `~/.mbsyncrc`: 299 - ```bash 300 - # Test password retrieval 301 - grep HOSTPOINT_SMTP_PASSWORD_SIMU ~/.dotfiles/zsh/.secret.muttrc | cut -d'"' -f2 101 + ## Files 102 + 302 103 ``` 104 + ~/.config/mutt/ 105 + ├── muttrc # Main config 106 + ├── Makefile # make sync, make help 107 + └── notmuch/ 108 + ├── notmuch-config # DB config 109 + ├── notmuch_screening.sh # Tagging script 110 + ├── mbsyncrc.example # mbsync template 111 + └── sync/mbsync_notmuch_sync.sh 303 112 304 - ## Migration from Folder-Based System 113 + ~/.dotfiles/mutt/.lists/ # Email lists (git ignored) 114 + ├── screened_in.txt # 1,723 approved senders 115 + ├── screened_out.txt # 1,287 blocked senders 116 + ├── feed.txt # 107 newsletters 117 + └── papertrail.txt # 12 receipts 305 118 306 - Your existing folder-based setup will continue to work. To migrate: 119 + ~/.mbsyncrc # mbsync config 120 + ``` 307 121 308 - 1. **Keep both configs** - Use `muttrc` for old system, `muttrc-notmuch` for new 309 - 2. **Test thoroughly** with notmuch before fully switching 310 - 3. **Your .txt files work with both** - They're shared between systems 311 - 4. **No data loss** - Notmuch doesn't modify your maildir, just indexes it 122 + ## Why Notmuch? 312 123 313 - ## Advantages of Notmuch 124 + - **Faster search** - Full-text search across all email 125 + - **Multiple tags** - Email can be "waiting" AND "important" 126 + - **No file moving** - Tags are metadata, files stay in place 127 + - **Better threading** - Excellent conversation threading 128 + - **Scriptable** - Easy custom tag rules 314 129 315 - 1. **Multiple tags per email** - An email can be both "waiting" and "important" 316 - 2. **Faster search** - Full-text search across all email 317 - 3. **No file moving** - Tags are just metadata, files stay in place 318 - 4. **Better threading** - Notmuch excels at conversation threading 319 - 5. **Scriptable** - Easy to write custom tag rules 320 - 321 - ## Additional Resources 322 - 323 - - [Notmuch Documentation](https://notmuchmail.org/documentation/) 324 - - [Neomutt Notmuch Integration](https://neomutt.org/feature/notmuch) 325 - - [mbsync Documentation](https://isync.sourceforge.io/mbsync.html) 130 + ## Resources 326 131 327 - ## Support 328 - 329 - If you encounter issues: 330 - 1. Check logs in `~/.config/mutt/logs/` 331 - 2. Run screening script manually to see errors 332 - 3. Test notmuch commands directly: `notmuch search`, `notmuch tag`, etc. 132 + - [Notmuch Docs](https://notmuchmail.org/doc/latest/man1/notmuch.html) 133 + - [Neomutt Notmuch](https://neomutt.org/feature/notmuch) 134 + - [mbsync Docs](https://isync.sourceforge.io/mbsync.html)