doomemacs/modules/email/notmuch/README.org

#+title:    :email notmuch
#+subtitle: Closest Emacs will ever be to multi-threaded
#+created:  July 31, 2018
#+since:    21.12.0

* Description :unfold:
This module turns Emacs into an email client using [[doom-package:][notmuch]].

** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +afew ::
  Enable integration with [[https://github.com/afewmail/afew][afew]].
- +org ::
  Enable [[doom-package:][org-mime]] for writing HTML emails using org-mode.

** Packages
- [[doom-package:][counsel-notmuch]] if [[doom-module:][:completion ivy]]
- [[doom-package:][helm-notmuch]] if [[doom-module:][:completion helm]]
- [[doom-package:][notmuch]]
- [[doom-package:][org-mime]]* if [[doom-module:][+org]]

** TODO Hacks
#+begin_quote
 🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module requires:

+ Either [[https://github.com/gauteh/lieer][gmailieer]] (default), [[https://isync.sourceforge.io/][mbsync]] or [[http://www.offlineimap.org/][offlineimap]] -- to sync mail with.
+ [[https://notmuchmail.org/][notmuch]] -- to index and tag your downloaded messages.
+ [[https://github.com/afewmail/afew][afew]] -- optionally to initially tag your downloaded messages.

** TODO MacOS

** Arch Linux
Run one of the following commands:
#+begin_src sh
pacman -S isync notmuch #mbsync
#+end_src
#+begin_src sh
pacman -S offlineimap notmuch
#+end_src

See: [[https://wiki.archlinux.org/index.php/Notmuch][Arch Wiki - Notmuch]]

** NixOS
#+begin_src nix
environment.systemPackages = with pkgs; [
    notmuch
    # And one of the following
    gmailieer
    isync
    offlineimap
];
#+end_src

[[https://github.com/Emiller88/dotfiles/blob/319841bd3b89e59b01d169137cceee3183aba4fc/modules/shell/mail.nix][An example of setting up mbsync and notmuch with home-manager]]

** TODO openSUSE
** TODO Debian/Ubuntu

* TODO Usage
#+begin_quote
 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

| Keymap          | Command            | Description                                   |
|-----------------+--------------------+-----------------------------------------------|
| [[kbd:][<localleader> u]] | ~+notmuch/update~  | Download, sync, and index emails with notmuch |
| [[kbd:][<localleader> c]] | ~+notmuch/compose~ | Compose new email                             |

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Downloading your email
To download your email you need a sync backend. Out of the box, this module
supports =Gmailier= (the default), =mbsync=, and =offlineimap= (ordered by
speed). You may define a custom one as well. The guides below will walk you
through setting them up with notmuch.

Later, once you've set up a sync backend and downloaded your email, you must
index your email for the first time:
#+begin_src sh
notmuch new
#+end_src

*** lieer
[[https://github.com/gauteh/lieer][Lieer]], formerly called Gmailieer, is the indexing tool used by default. To
install lieer, see the [[https://github.com/gauteh/lieer#installation][installation docs]].

*** offlineimap
To use [[https://www.offlineimap.org/][offlineimap]], change ~+notmuch-sync-backend~:
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(setq +notmuch-sync-backend 'offlineimap)
#+end_src

Next, write a configuration file for =offlineimap=. [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][Here is a comprehensive
example]] and [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf.minimal][another minimal one]].

As a real world example, [[https://github.com/hlissner/dotfiles/blob/5f146b6c39552c0cf38025406f5dba7389542b0a/shell/mu/.offlineimaprc][here is my old config]], where it is configured to
download mail to =$HOME/.mail=. I used [[https://www.passwordstore.org/][unix pass]] to securely store my login
credentials.

Finally, download your email with ~$ offlineimap -o~. This may take a while,
especially if you have thousands of emails.

*** mbsync
To use [[https://isync.sourceforge.io/][mbsync]], change ~+notmuch-sync-backend~:
#+begin_src emacs-lisp
(setq +notmuch-sync-backend 'mbsync)

;; Use `mbsync-xdg' if your mbsync config lives in $XDG_CONFIG_HOME/isync:
(setq +notmuch-sync-backend 'mbsync-xdg)
#+end_src

The steps needed to set up =notmuch= with =mbsync= are similar to the ones for
[[*offlineimap][offlineimap]].

Start with writing a =$HOME/.mbsyncrc= to store your configuration. An example
for GMAIL can be found on the [[https://wiki.archlinux.org/index.php/isync#Configuring][ArchWiki]] which will also explain how its
integration with notmuch for auto synchronization. A non-GMAIL example is
available as a gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]].

Finally, download your email with ~$ mbsync --all~. This may take a while, but
will be quicker than =offlineimap=.

*** Custom method
If you have a unique method for synchronizing your email, you can define your
own backend:
#+begin_src emacs-lisp
(setq +notmuch-sync-backend 'custom
      ;; Set this to an arbitrary shell command
      +notmuch-sync-command "my-notmuch-sync-cmd")
#+end_src

** Sending mail
- [[https://notmuchmail.org/notmuch-emacs/#index6h2][notmuch docs: Sending mail]]
- [[https://notmuchmail.org/emacstips/#index11h2][notmuch docs: msmtp, message mode and multiple accounts]]
- [[https://notmuchmail.org/emacstips/#index12h2][notmuch docs: sending mail using smtpmail]]

** Customize =*notmuch-hello*= buffer
It is possible to change the =*notmuch-hello*= buffer if you want to.
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(after! notmuch
  (setq notmuch-show-log nil
        notmuch-hello-sections `(notmuch-hello-insert-saved-searches
                                 notmuch-hello-insert-alltags)
        ;; To hide headers while composing an email
        notmuch-message-headers-visible nil))
#+end_src

** Changing the =notmuch= landing page
You may want to forego the =*notmuch-hello*= buffer by having ~M-x =notmuch~ or
[[kbd:][<leader> o m]] take you straight to a search page.

When using [[kbd:][<leader> o m]] the ~+notmuch-home-function~ is called. By default it
uses the ~notmuch~ function and so has the same familiar behavior of running a
vanilla install of notmuch-emacs. But, by overwriting this function you can run
a custom search as your landing page.
#+begin_src emacs-lisp
(setq +notmuch-home-function (lambda () (notmuch-search "tag:inbox")))
#+end_src

** Writing HTML Emails
The [[https://github.com/org-mime/org-mime][org-mime]] package provides functionality for composing emails in org-mode and
transforming them to HTML. This feature is enabled using the =+org= flag.

Example use cases:
- To convert an email to an HTML email use ~M-x org-mime-htmlize~.
- To compose email using an org-mode editor buffer, use ~M-x
  org-mime-edit-mail-in-org-mode~.

If you'd like to make configuration changes to =org-mime=, you may do so
normally. By default the output of =org-mime-htmlize= includes section numbers,
a byline, and a table of contents. That's probably more formal than the emails
you're used to sending, so here's some example configuration that turns those
features off:
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(after! org-mime
  (setq org-mime-export-options '(:section-numbers nil
                                  :with-author nil
                                  :with-toc nil)))
#+end_src

* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote