roam/azosmail.org

azos/mail

• Architecture
• Conventions
• Gotchas
• Key Files

Architecture

• 3 accounts defined in features/mail/default.nix: zakobar (primary, aner@zakobar.com via privateemail.com IMAP/SMTP), gmail (anerisgreat@gmail.com), bgu (anerz@post.bgu.ac.il, gmail-flavor IMAP)
• Sync stack: mbsync (isync) pulls IMAP → ~/Maildir, msmtp sends, mu indexes for search/mu4e. Confirmed by live inspection (2026-10-08): generated ~/.config/isyncrc and ~/.config/msmtp/config are fully populated and actively syncing (recent .mbsyncstate timestamps); mu4e's mu4e-get-mail-command is literally mbsync -a.
• lieer was declared (services.lieer.enable=/=programs.lieer.enable) but had zero real footprint (no .gmailieer.json anywhere, no systemd units) — vestigial, removed from features/mail/default.nix.
• Credentials via pass: mbsync/anerisgreat@gmail.com, mbsync/anerz@post.bgu.ac.il, privateemail.com (zakobar account). All decrypt through the same GPG smartcard (yubikey) key.
• Periodic sync: systemd.user.timers.mbsync-timer runs every 5 min (2 min after login, then every OnUnitActiveSec). Guarded by a gpg --card-status presence check in the mbsyncSafe wrapper script so a missing yubikey skips the sync silently instead of triggering a pinentry "insert card" prompt — gpg --card-status only queries the reader and never itself invokes pinentry, making it a safe non-interactive gate.
• Mail client is mu4e in Emacs (azos-core/features/station/emacs/config.org), not notmuch (a notmuch-hello mode reference exists only in a linum-disable list, appears vestigial/unused)

Conventions

• mu4e contexts match by maildir prefix: /zakobar, /gmail, /bgu; each sets its own sent/drafts/trash/archive (archive = "All Mail" for gmail-flavor accounts)
• No user-defined tagging system — "tags" in this setup means mu4e flags (unread/trashed/replied) and Gmail labels, which arrive as IMAP folders under [Gmail]/ rather than mu4e-native tags
• Bookmarks (saved searches) defined in config: Inbox (all 3 combined), Unread, Today, Week
• Maildir shortcuts: z=/=g=/=b keys jump to each account's inbox
• Mail opens in a dedicated singleton tab via azos/mail/open (bound under the "open" keymap)

Gotchas

• mbsync's remove=/=expunge home-manager options (per-account mbsync.remove=/=mbsync.expunge) default to "none" and were never set — \Deleted flags synced down from IMAP but never actually got removed/expunged on either side, so trashed messages lingered forever in the local Maildir and showed up (struck-through) in any mu4e bookmark that didn't explicitly filter flag:trashed. Fixed 2026-10-08 by setting mbsync.remove = "both"=/=mbsync.expunge = "both" in features/mail/default.nix default_account_params, for all 3 accounts. Caveat: for Gmail-flavor accounts (gmail=/=bgu), Gmail's IMAP quirk means expunging any folder other than [Gmail]/Trash just removes that one label — the message survives under other labels (e.g. All Mail). zakobar (plain IMAP, no label system) has no such safety net: expunge there is a real, permanent, unrecoverable delete.
• BGU's Workspace account (anerz@post.bgu.ac.il) localizes/renames the Gmail "Trash" special-use label to [Gmail]/Bin instead of [Gmail]/Trash — caused mbsync error "channel bgu: far side box [Gmail]/Trash cannot be opened" plus a stale local [Gmail]/Trash maildir with orphaned messages. mu4e-trash-folder for the BGU context must be /bgu/[Gmail]/Bin. Fixed 2026-10-08 (merged stale local messages into Bin, updated context). Don't assume standard Gmail folder names for Workspace/edu accounts — verify via IMAP LIST per account.
• mu4e's "Inbox" bookmark historically did NOT exclude flag:trashed (unlike Unread/Today/Week) — direct cause of visibly crossed-out mail in Inbox. flag:trashed only reflects the literal Maildir T flag; it does NOT mean "located in a Trash/Bin/Spam-named folder." Because of Gmail's multi-label model, a genuinely-unread message filed anywhere also has a duplicate unread copy under [Gmail]/All Mail (same Message-ID, separate local file) — this inflated Unread-bookmark counts by ~2x. Fixed 2026-10-08: all four bookmarks (config.org, mu4e-bookmarks, ~line 95) now share one let-bound exclusion string filtering flag:trashed plus the Trash/Bin/Spam/All-Mail/"Deleted Messages" maildirs per account.
• Live Emacs session state and the on-disk literate config drift independently: a nix rebuild (azos-lauretta-update) only regenerates files on disk, it does NOT reload anything into an already-running Emacs — mu4e-contexts=/=mu4e-bookmarks etc. stay at whatever was last load-file'd or evaluated at startup. After editing config.org, hot-reload the specific top-level form that changed via emacsclient -e '(load-file "/tmp/x.el")' (extract just that sexp with exact matching parens — off-by-one line ranges silently truncate the form and error "End of file during parsing"). Forgetting to reload mu4e-contexts after fixing mu4e-trash-folder briefly almost recreated the just-deleted stale /bgu/[Gmail]/Trash folder, because the live session's BGU context still pointed at the old path and mu4e prompted "create trash folder?" on trash-mark-apply.
• Debugging mu4e live via emacsclient -e: (with-current-buffer "*mu4e-headers*" mu4e--search-last-query) shows the active search; (gethash docid mu4e--mark-map) on a buffer's message-at-point shows the exact pending mark+target before applying; (mu4e-context-vars (mu4e-context-current)) shows live (not file) context vars. Caution: if Emacs is blocked on a blocking minibuffer prompt (e.g. a y-or-n-p "create folder?" confirmation), queued emacsclient -e calls will hang/timeout rather than error — that's a sign a prompt is open and needs a human to answer it, not a crash.
• BGU mailing list cs_msc@mlists.cs.bgu.ac.il (List-Id: cs_msc.mlists.cs.bgu.ac.il) floods /bgu/logistics-cs-msc with announcement mail that's essentially never read (backlog since Jan 2024, ~330 messages). Intended fix is a Gmail filter in the BGU Workspace webclient (Settings → Filters and Blocked Addresses, matching list:cs_msc.mlists.cs.bgu.ac.il, action "mark as read", optionally applied retroactively to existing matches) — not a local/mu4e-side fix, since it's about delivery-time read-state for mail the user doesn't want to individually triage.

Key Files

• features/mail/default.nix — accounts, mbsync/msmtp/mu config, mu init activation script, mbsync-timer systemd service/timer
• azos-core/features/station/emacs/config.org (search "mu4e") — mu4e contexts, bookmarks, shortcuts, signing blacklist logic
• azos-core/features/station/emacs/_pkg.nix — mu4e package dependency