History

Henrik Lissner 473eda795a fix(notmuch): missing notmuch-version.el Notmuch, like org, uses git describe to build a version string variable at install time, but Doom preforms shallow clones of its packages, where git describe does not work. Notmuch is one of our bigger packages and the variable isn't essential for normal use, so I've opted to build notmuch-version.el by hand. It lacks the commit offset, but it has enough information to work with. Fix #5581		2021-10-06 01:30:45 +02:00
..
autoload.el	feat(notmuch): allow notmuch module without (:ui workspaces)	2021-10-03 12:50:36 +02:00
config.el	fix(notmuch): messages open in tiny popup	2021-09-30 01:26:25 +02:00
packages.el	fix(notmuch): missing notmuch-version.el	2021-10-06 01:30:45 +02:00
README.org	docs(notmuch): fix links in readme	2021-08-06 03:16:52 -04:00

README.org

email/notmuch

Table of Contents
Description
- Module Flags
- Plugins
Prerequisites
- MacOS
- Arch Linux
- NixOS
- openSUSE
- Debian/Ubuntu
Features
Configuration
Troubleshooting

Table of Contents TOC

Description
- Module Flags
- Plugins
Prerequisites
- MacOS
- Arch Linux
- NixOS
- openSUSE
- Debian/Ubuntu
Features
Configuration
Troubleshooting

Description

This module turns Emacs into an email client using notmuch.

Module Flags

+org Enables org-mime for writing HTML emails using org-mode.
+afew Enables integration with afew.

Plugins

notmuch
org-mime* (with +org flag)
counsel-notmuch*
helm-notmuch*

Prerequisites

This module requires:

Either gmailieer (default), mbsync or offlineimap (to sync mail with)
notmuch, to index and tag your downloaded messages.
afew , optionally to initially tag your downloaded messages.

TODO MacOS

Arch Linux

Run one of the following commands.

pacman -S isync notmuch #mbsync

pacman -S offlineimap notmuch

See: Arch Wiki - Notmuch

NixOS

environment.systemPackages = with pkgs; [
    notmuch
    # And one of the following
    gmailieer
    isync
    offlineimap
];

An example of setting up mbsync and notmuch with home-manager

TODO openSUSE

TODO Debian/Ubuntu

Features

Keymap	Command	Description
`SPC m u`	`+notmuch/update`	Download, sync, and index emails with notmuch
`SPC m c`	`+notmuch/compose`	Compose new email

Configuration

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:

notmuch new

lieer

Lieer, formerly called Gmailieer, is the indexing tool used by default. To install lieer, see the installation docs.

offlineimap

To use offlineimap, change +notmuch-sync-backend:

;; add to ~/.doom.d/config.el
(setq +notmuch-sync-backend 'offlineimap)

Next, write a configuration file for offlineimap. Here is a comprehensive example and another minimal one.

As a real world example, here is my old config, where it is configured to download mail to \~/.mail. I used 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 mbsync, change +notmuch-sync-backend:

(setq +notmuch-sync-backend 'mbsync)

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

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

Start with writing a \~/.mbsyncrc to store your configuration. An example for GMAIL can be found on the ArchWiki which will also explain how its integration with notmuch for auto synchronization. A non-GMAIL example is available as a gist 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:

(setq +notmuch-sync-backend 'custom
      ;; Set this to an arbitrary shell command
      +notmuch-sync-command "my-notmuch-sync-cmd")

Sending mail

Customize `notmuch-hello` buffer

It is possible to change the *notmuch-hello* buffer if you want to.

(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))

Changing the `notmuch` landing page

You may want to forego the *notmuch-hello* buffer by having M-x =notmuch or SPC o m take you straight to a search page.

When using SPC 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.

(setq +notmuch-home-function (lambda () (notmuch-search "tag:inbox")))

Writing HTML Emails

The 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.

config.el

(after! org-mime
  (setq org-mime-export-options '(:section-numbers nil
                                  :with-author nil
                                  :with-toc nil)))