emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs(:email): update READMEs to new format

Browse source
This commit is contained in:
Henrik Lissner 2021-10-16 01:27:18 +02:00 • committed by Henrik Lissner
parent 73c1dd1338
commit 2dcef764f1
4 changed files with 303 additions and 207 deletions
Download patch file Download diff file Expand all files Collapse all files

8
modules/email/README.org Normal file
View file

@ -0,0 +1,8 @@
← [[doom-module-index:][Back to module index]] ↖ [[doom-module-source:email][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :email
#+CREATED: October 14, 2021
#+SINCE: 21.12.0
* Description
Modules that turn Emacs in an email client.

250
modules/email/mu4e/README.org
View file

@ -1,79 +1,88 @@
#+TITLE: email/mu4e ← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::email mu4e][Issues]] ↖ [[doom-module-source:email/mu4e][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
#+DATE: April 8, 2017 --------------------------------------------------------------------------------
#+SINCE: v2.0 #+TITLE: :email mu4e
#+STARTUP: inlineimages #+SUBTITLE: The great filter Hanson hadn't anticipated
#+CREATED: April 08, 2017
#+SINCE: 2.0.0
* Table of Contents :TOC:noexport: * Description :unfold:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#nixos][NixOS]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#offlineimap][offlineimap]]
- [[#mbsync][mbsync]]
- [[#fetching-your-mail-in-other-ways][Fetching your mail in other ways]]
- [[#mu-and-mu4e][mu and mu4e]]
- [[#orgmsg][OrgMsg]]
- [[#mu4e-alert][mu4e-alert]]
- [[#troubleshooting][Troubleshooting]]
- [[#no-such-file-or-directory-mu4e][=No such file or directory, mu4e=]]
- [[#void-function-org-time-add-error-on-gentoo][~(void-function org-time-add)~ error on Gentoo]]
* Description
This module makes Emacs an email client, using [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]]. This module makes Emacs an email client, using [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]].
#+begin_quote - Tidied mu4e headers view, with flags from [[doom-package:][all-the-icons]].
I want to live in Emacs, but as we all know, living is incomplete without email. - Consistent coloring of reply depths (across compose and gnus modes).
So I prayed to the text editor gods and they (I) answered. Emacs+evil's editing - Prettified =mu4e:main= view.
combined with org-mode for writing emails? /Yes please./ - Cooperative locking of the =mu= process. Another Emacs instance may request
access, or grab the lock when it's available.
- [[doom-package:][org-msg]] integration with [[doom-module:][+org]], which can be toggled per-message, with revamped
style and an accent color.
- Gmail integrations with the [[doom-module:][+gmail]] flag.
- Email notifications with [[doom-package:][mu4e-alert]], and (on Linux) a customised notification
style.
It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my email #+begin_quote
via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can understand). 💡 I want to live in Emacs, but as we all know, living is incomplete without
email. So I prayed to the text editor gods and they (I) answered.
Emacs+evil's editing combined with org-mode for writing emails? /Yes
please./
It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my
email via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can
understand).
#+end_quote #+end_quote
** Maintainers ** Maintainers
+ [[https://github.com/tecosaur][@tecosaur]] - [[doom-user:][@tecosaur]]
** Module Flags [[doom-contrib-maintainer:][Become a maintainer?]]
+ =+gmail= Enables gmail-specific configuration for mail ~To~ or ~From~ a gmail
address, or a maildir with ~gmail~ in the name.
+ =+org= Use =org-msg= for composing email in Org, then sending a multipart text
(ASCII export) and HTML message.
** Plugins ** Module flags
+ [[https://github.com/iqbalansari/mu4e-alert][mu4e-alert]] - +gmail ::
+ =+org= Enable gmail-specific configuration for mail ~To~ or ~From~ a gmail address,
+ [[https://github.com/jeremy-compostella/org-msg][org-msg]] or a maildir with ~gmail~ in the name.
- +org ::
Use [[doom-package:][org-msg]] for composing email in Org, then sending a multipart text (ASCII
export) and HTML message.
** Packages
- [[doom-package:][mu4e-alert]]
- [[doom-package:][org-msg]] 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.]]
* Prerequisites
This module requires: This module requires:
+ [[https://www.djcbsoftware.nl/code/mu/][mu]], to index your downloaded messages and to provide the [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]] package. - [[https://www.djcbsoftware.nl/code/mu/][mu]], to index your downloaded messages and to provide the [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]] package.
+ A program to sync your mail. This module comes with builtin support for - A program to sync your mail. This module comes with builtin support for [[https://isync.sourceforge.io/][mbsync]]
[[https://isync.sourceforge.io/][mbsync]] (recommended, default) or [[http://www.offlineimap.org/][offlineimap]] but you can sync mail in (recommended, default) or [[http://www.offlineimap.org/][offlineimap]] but you can sync mail in other ways too.
other ways too.
#+name: Install Matrix #+name: Install Matrix
| Platform | Install command | Base packages | | Platform | Install command | Base packages |
|---------------+--------------------------+-------------------------| |---------------+----------------------------+-------------------------|
| MacOS | ~brew install <pkgs>~ | =mu= | | MacOS | ~$ brew install <pkgs>~ | =mu= |
| Arch | ~pacman -S <pkgs>~ | (AUR, ~yay -S~) =mu= | | Arch | ~$ pacman -S <pkgs>~ | (AUR, ~$ yay -S~) =mu= |
| openSUSE | ~zypper install <pkgs>~ | =maildir-utils=, =mu4e= | | openSUSE | ~$ zypper install <pkgs>~ | =maildir-utils=, =mu4e= |
| Fedora | ~dnf install <pkgs>~ | =maildir-utils= | | Fedora | ~$ dnf install <pkgs>~ | =maildir-utils= |
| Debian/Ubuntu | ~apt-get install <pkgs>~ | =maildir-utils=, =mu4e= | | Debian/Ubuntu | ~$ apt-get install <pkgs>~ | =maildir-utils=, =mu4e= |
Then install either the =isync= (=mbsync=) or =offlineimap= package. Then install either the =isync= (=mbsync=) or =offlineimap= package.
To send mail, mu4e uses [[https://www.gnu.org/software/emacs/manual/html_mono/smtpmail.html][smtpmail]] (an Emacs library) by default. To send mail, mu4e uses [[https://www.gnu.org/software/emacs/manual/html_mono/smtpmail.html][smtpmail]] (an Emacs library) by default. You can also run
You can also run a local SMTP server like =sendmail= or =postfix=, or use an SMTP a local SMTP server like =sendmail= or =postfix=, or use an SMTP forwarder such
forwarder such as =msmtp= (recommended). as =msmtp= (recommended).
If you use =msmtp=, you'll likely want to add the following to your If you use =msmtp=:
=config.el=:
#+begin_src emacs-lisp #+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(after! mu4e (after! mu4e
(setq sendmail-program (executable-find "msmtp") (setq sendmail-program (executable-find "msmtp")
send-mail-function #'smtpmail-send-it send-mail-function #'smtpmail-send-it
@ -83,42 +92,40 @@ If you use =msmtp=, you'll likely want to add the following to your
#+end_src #+end_src
** NixOS ** NixOS
#+BEGIN_SRC nix #+begin_src nix
environment.systemPackages = with pkgs; [ environment.systemPackages = with pkgs; [
mu mu
# And one of the following # And one of the following
isync isync
offlineimap offlineimap
]; ];
#+END_SRC #+end_src
[[https://github.com/Emiller88/dotfiles/blob/5eaabedf1b141c80a8d32e1b496055231476f65e/modules/shell/mail.nix][An example of setting up mbsync and mu with home-manager]] [[https://github.com/Emiller88/dotfiles/blob/5eaabedf1b141c80a8d32e1b496055231476f65e/modules/shell/mail.nix][An example of setting up mbsync and mu with home-manager]]
* Features * TODO Usage
+ Tidied mu4e headers view, with flags from =all-the-icons= #+begin_quote
+ Consistent coloring of reply depths (across compose and gnus modes) 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
+ Prettified =mu4e:main= view #+end_quote
+ Cooperative locking of the =mu= process. Another Emacs instance may request
access, or grab the lock when it's available. * TODO Configuration
+ =org-msg= integration with =+org=, which can be toggled per-message, with revamped style and #+begin_quote
an accent color 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
+ Gmail integrations with the =+gmail= flag #+end_quote
+ Email notifications with =mu4e-alert=, and (on Linux) a customised notification style
* Configuration
** offlineimap ** offlineimap
This module uses =mbsync= by default. To use =offlineimap=, change ~+mu4e-backend~: This module uses =mbsync= by default. To use =offlineimap=, change
~+mu4e-backend~:
#+BEGIN_SRC emacs-lisp #+begin_src emacs-lisp
(setq +mu4e-backend 'offlineimap) (setq +mu4e-backend 'offlineimap)
#+END_SRC #+end_src
Next, you need to write a configuration file for =offlineimap=. Mine can be found Next, you need to write a configuration file for =offlineimap=. Mine can be
[[https://github.com/hlissner/dotfiles/blob/be0dce5dae8f3cbafaac0cc44269d84b4a742c46/shell/mu/][in my dotfiles repository]]. It is configured to download mail to ~\~/.mail~. I found [[https://github.com/hlissner/dotfiles/blob/be0dce5dae8f3cbafaac0cc44269d84b4a742c46/shell/mu/][in my dotfiles repository]]. It is configured to download mail to
use [[https://www.passwordstore.org/][unix pass]] to securely store my login credentials. You can find a *very* ~\~/.mail~. I use [[https://www.passwordstore.org/][unix pass]] to securely store my login credentials. You can find
detailed configuration [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][here]]. a *very* detailed configuration [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][here]].
Next you can download your email with ~offlineimap -o~. This may take a while, Next you can download your email with ~$ offlineimap -o~. This may take a while,
especially if you have thousands of mails. especially if you have thousands of mails.
You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section. You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section.
@ -127,12 +134,12 @@ You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section.
The steps needed to set up =mu4e= with =mbsync= are very similar to the ones for The steps needed to set up =mu4e= with =mbsync= are very similar to the ones for
[[#offlineimap][offlineimap]]. [[#offlineimap][offlineimap]].
Start with writing a ~~/.mbsyncrc~. An example for Gmail can be found on Start with writing a =~/.mbsyncrc=. An example for Gmail can be found on
[[http://pragmaticemacs.com/emacs/migrating-from-offlineimap-to-mbsync-for-mu4e/][pragmaticemacs.com]]. A non-Gmail example is available as a gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]]. The [[http://isync.sourceforge.net/mbsync.html][manual [[http://pragmaticemacs.com/emacs/migrating-from-offlineimap-to-mbsync-for-mu4e/][pragmaticemacs.com]]. A non-Gmail example is available as a gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]]. The [[http://isync.sourceforge.net/mbsync.html][manual
page]] contains all needed information to set up your own. page]] contains all needed information to set up your own.
Next you can download your email with ~mbsync --all~. This may take a while, but Next you can download your email with ~$ mbsync --all~. This may take a while,
should be quicker than =offlineimap= ;). but should be quicker than =offlineimap= ;).
You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section. You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section.
@ -142,19 +149,20 @@ tailored =mbsync= command to just fetch the new changes.
If this is of interest, this approach can be seen [[https://tecosaur.github.io/emacs-config/config.html#fetching][in @tecosaur's config]] where If this is of interest, this approach can be seen [[https://tecosaur.github.io/emacs-config/config.html#fetching][in @tecosaur's config]] where
[[https://gitlab.com/shackra/goimapnotify][goimapnotify]] is used for this. [[https://gitlab.com/shackra/goimapnotify][goimapnotify]] is used for this.
** Fetching your mail in other ways ** Fetching your mail in other ways
You also have the possiblity to invoke an arbitary shell command to fetch your You also have the possiblity to invoke an arbitary shell command to fetch your
mail by disabling this module's backend selection and setting the value of the mail by disabling this module's backend selection and setting the value of the
~mu4e-get-mail-command~ to the command you want to execute. ~mu4e-get-mail-command~ to the command you want to execute:
#+BEGIN_SRC emacs-lisp #+begin_src emacs-lisp
(setq +mu4e-backend nil) (setq +mu4e-backend nil)
(after! mu4e (after! mu4e
(setq mu4e-get-mail-command "your_command")) (setq mu4e-get-mail-command "your_command"))
#+END_SRC #+end_src
If your command prompts you for a passphrase, you might want to change the value If your command prompts you for a passphrase, you might want to change the value
of the ~mu4e~get-mail-password-regexp~ such that =mu4e= will recognize the of the ~mu4e~get-mail-password-regexp~ such that [[doom-package:][mu4e]] will recognize the prompt
prompt and let you provide the passphrase from within Emacs. and let you provide the passphrase from within Emacs.
** mu and mu4e ** mu and mu4e
You should have your email downloaded already. If you have not, you need to set You should have your email downloaded already. If you have not, you need to set
@ -162,24 +170,23 @@ You should have your email downloaded already. If you have not, you need to set
Before you can use =mu4e= or the CLI program =mu=, you need to index your email Before you can use =mu4e= or the CLI program =mu=, you need to index your email
initially. How to do that differs a little depending on the version of =mu= you initially. How to do that differs a little depending on the version of =mu= you
use. You can check your version with ~mu --version~. use. You can check your version with ~$ mu --version~.
For =mu= *>=1.4* you need to run two commands: For =mu= *>=1.4* you need to run two commands:
#+BEGIN_SRC sh #+begin_src sh
mu init --maildir ~/.mail --my-address email@example.com mu init --maildir ~/.mail --my-address email@example.com
mu index mu index
#+END_SRC #+end_src
=mu= *<1.4* only requires one command: =mu= *<1.4* only requires one command:
#+BEGIN_SRC sh #+begin_src sh
mu index --maildir ~/.mail mu index --maildir $HOME/.mail
#+END_SRC #+end_src
Be sure to replace ~~/.mail~ with the directory containing your mail. Be sure to replace =$HOME/.mail= with the directory containing your mail.
Then configure Emacs to use your email address: Then configure Emacs to use your email address:
#+begin_src emacs-lisp
#+BEGIN_SRC emacs-lisp :tangle no
;; Each path is relative to the path of the maildir you passed to mu ;; Each path is relative to the path of the maildir you passed to mu
(set-email-account! "bar.com" (set-email-account! "bar.com"
'((mu4e-sent-folder . "/bar.com/Sent Mail") '((mu4e-sent-folder . "/bar.com/Sent Mail")
@ -190,14 +197,13 @@ Then configure Emacs to use your email address:
(user-mail-address . "foo@bar.com") ;; only needed for mu < 1.4 (user-mail-address . "foo@bar.com") ;; only needed for mu < 1.4
(mu4e-compose-signature . "---\nYours truly\nThe Baz")) (mu4e-compose-signature . "---\nYours truly\nThe Baz"))
t) t)
#+END_SRC #+end_src
If you use multiple email accounts, defining them with ~set-email-account!~ will If you use multiple email accounts, defining them with ~set-email-account!~ will
automatically set the appropriate account context when replying to emails in automatically set the appropriate account context when replying to emails in
that account's maildir. ~mu4e-context-policy~ and ~mu4e-compose-context-policy~ that account's maildir. ~mu4e-context-policy~ and ~mu4e-compose-context-policy~
can be modified to change context behavior when opening mu4e and composing can be modified to change context behavior when opening mu4e and composing
email: email:
#+begin_src emacs-lisp #+begin_src emacs-lisp
(setq mu4e-context-policy 'ask-if-none (setq mu4e-context-policy 'ask-if-none
mu4e-compose-context-policy 'always-ask) mu4e-compose-context-policy 'always-ask)
@ -209,7 +215,7 @@ you are not replying to an email to or from one of the specified aliases, you
will be prompted for an alias to send from. will be prompted for an alias to send from.
*** Gmail *** Gmail
With the =+gmail= flag, integrations are applied which account for the different With the [[doom-module:][+gmail]] flag, integrations are applied which account for the different
behaviour of Gmail. behaviour of Gmail.
The integrations are applied to addresses with /both/ "@gmail.com" in the The integrations are applied to addresses with /both/ "@gmail.com" in the
@ -222,8 +228,8 @@ benefit from the integrations:
("example@example.com" . "/example"))) ("example@example.com" . "/example")))
#+end_src #+end_src
If you only use Gmail, you can improve performance due to the way Gmail If you only use Gmail, you can improve performance due to the way Gmail presents
presents messages over IMAP: messages over IMAP:
#+begin_src emacs-lisp #+begin_src emacs-lisp
;; don't need to run cleanup after indexing for gmail ;; don't need to run cleanup after indexing for gmail
(setq mu4e-index-cleanup nil (setq mu4e-index-cleanup nil
@ -238,14 +244,15 @@ as deleted: Auto-Expunge off - Wait for the client to update the server." and
folder: Move the message to the trash" for the integrations to work as expected. folder: Move the message to the trash" for the integrations to work as expected.
** OrgMsg ** OrgMsg
With the =+org= flag, =org-msg= is installed, and ~org-msg-mode~ is enabled before With the [[doom-module:][+org]] flag, [[doom-package:][org-msg]] is installed, and ~org-msg-mode~ is enabled before
composing the first message. To disable ~org-msg-mode~ by default, simply composing the first message. To disable ~org-msg-mode~ by default:
#+BEGIN_SRC emacs-lisp :tangle no #+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(setq mu4e-compose--org-msg-toggle-next nil) (setq mu4e-compose--org-msg-toggle-next nil)
#+END_SRC #+end_src
To toggle org-msg for a single message, just apply the universal argument to the To toggle org-msg for a single message, just apply the universal argument to the
compose or reply command (=SPC u= with ~evil~, =C-u= otherwise). compose or reply command ([[kbd:][SPC u]] with [[doom-package:][evil]], [[kbd:][C-u]] otherwise).
The accent color that Doom uses can be customised by setting The accent color that Doom uses can be customised by setting
~+org-msg-accent-color~ to a CSS color string. ~+org-msg-accent-color~ to a CSS color string.
@ -253,35 +260,36 @@ The accent color that Doom uses can be customised by setting
** mu4e-alert ** mu4e-alert
This provides notifications through the [[https://github.com/jwiegley/alert][alert]] library. This provides notifications through the [[https://github.com/jwiegley/alert][alert]] library.
If you don't like this, simply add If you don't like this use:
#+begin_src emacs-lisp #+begin_src emacs-lisp
;; add to $DOOMDIR/packages.el
(package! mu4e-alert :disable t) (package! mu4e-alert :disable t)
#+end_src #+end_src
to your [[elisp:(find-file (expand-file-name "packages.el" doom-private-dir))][packages.el]] and it will not be used.
* Troubleshooting * Troubleshooting
[[doom-report:][Report an issue?]]
** =No such file or directory, mu4e= ** =No such file or directory, mu4e=
You will get =No such file or directory, mu4e= errors if you don't run ~doom You will get =No such file or directory, mu4e= errors if you don't run ~$ doom
sync~ after installing =mu= through your package manager. sync~ after installing =mu= through your package manager.
Some times the the ~mu~ package does not include ~mu4e~ (*cough Ubuntu*). Some times the the ~mu~ package does not include ~mu4e~ (*cough Ubuntu*). if
if that's the case you will need to [[https://github.com/djcb/mu][install]] it and add it to your ~load-path~ that's the case you will need to [[https://github.com/djcb/mu][install]] it and add it to your ~load-path~ you
you can do that by... can do that by:
#+BEGIN_SRC emacs-lisp :tangle no #+begin_src emacs-lisp
(add-to-list 'load-path "your/path/to/mu4e") (add-to-list 'load-path "your/path/to/mu4e")
;; if you installed it using your package manager ;; if you installed it using your package manager
(add-to-list 'load-path "/usr/share/emacs/site-lisp/mu4e") (add-to-list 'load-path "/usr/share/emacs/site-lisp/mu4e")
;; if you built from source ;; if you built from source
(add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e") (add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e")
#+END_SRC #+end_src
If you have completely lost your install then you can use this handy command! If you have completely lost your install then you can use:
#+begin_src sh
#+BEGIN_SRC shell
find / -type d -iname '*mu4e*' find / -type d -iname '*mu4e*'
# I recommend rerouting all of the errors to /dev/null # I recommend rerouting all of the errors to /dev/null
find / -type d -iname '*mu4e*' 2> /dev/null find / -type d -iname '*mu4e*' 2> /dev/null
#+END_SRC #+end_src
** ~(void-function org-time-add)~ error on Gentoo ** ~(void-function org-time-add)~ error on Gentoo
Gentoo users will see this error because [[https://gitweb.gentoo.org/repo/gentoo.git/tree/net-mail/mu/files/70mu-gentoo.el#n2][the =net-mail/mu= package eagerly loads Gentoo users will see this error because [[https://gitweb.gentoo.org/repo/gentoo.git/tree/net-mail/mu/files/70mu-gentoo.el#n2][the =net-mail/mu= package eagerly loads
@ -291,3 +299,11 @@ version that Doom installs.
Later versions of the =net-mail/mu= package have [[https://gitweb.gentoo.org/repo/gentoo.git/commit/net-mail/mu?id=770e1fccb119fbce8ba6d16021a3598123f212ff][fixed this issue]], but you may Later versions of the =net-mail/mu= package have [[https://gitweb.gentoo.org/repo/gentoo.git/commit/net-mail/mu?id=770e1fccb119fbce8ba6d16021a3598123f212ff][fixed this issue]], but you may
need to switch to the unstable build of =net-mail/mu= to see it. need to switch to the unstable build of =net-mail/mu= to see it.
* 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

192
modules/email/notmuch/README.org
View file

@ -1,62 +1,61 @@
#+TITLE: email/notmuch ← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::email notmuch][Issues]] ↖ [[doom-module-source:email/notmuch][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
#+DATE: May 5, 2019 --------------------------------------------------------------------------------
#+SINCE: v2.0 #+TITLE: :email notmuch
#+STARTUP: inlineimages #+SUBTITLE: Closest Emacs will ever be to multi-threaded
#+CREATED: May 05, 2019
#+SINCE: 2.0.0
* Table of Contents :TOC: * Description :unfold:
- [[#description][Description]] This module turns Emacs into an email client using [[doom-package:][notmuch]].
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#macos][MacOS]]
- [[#arch-linux][Arch Linux]]
- [[#nixos][NixOS]]
- [[#opensuse][openSUSE]]
- [[#debianubuntu][Debian/Ubuntu]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#downloading-your-email][Downloading your email]]
- [[#sending-mail][Sending mail]]
- [[#customize-notmuch-hello-buffer][Customize =*notmuch-hello*= buffer]]
- [[#changing-the-notmuch-landing-page][Changing the =notmuch= landing page]]
- [[#writing-html-emails][Writing HTML Emails]]
- [[#troubleshooting][Troubleshooting]]
* Description ** Maintainers
This module turns Emacs into an email client using [[https://notmuchmail.org/][notmuch]]. *This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags ** Module flags
+ =+org= Enables org-mime for writing HTML emails using org-mode. - +afew ::
+ =+afew= Enables integration with =afew=. Enable integration with [[https://github.com/afewmail/afew][afew]].
- +org ::
Enable [[doom-package:][org-mime]] for writing HTML emails using org-mode.
** Plugins ** Packages
+ [[https://notmuchmail.org/][notmuch]] - [[doom-package:][counsel-notmuch]] if [[doom-module:][:completion ivy]]
+ [[https://github.com/org-mime/org-mime][org-mime]]* (with =+org= flag) - [[doom-package:][helm-notmuch]] if [[doom-module:][:completion helm]]
+ [[https://github.com/fuxialexander/counsel-notmuch][counsel-notmuch]]* - [[doom-package:][notmuch]]
+ [[https://github.com/emacs-helm/helm-notmuch][helm-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.]]
* Prerequisites
This module requires: 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) + 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://notmuchmail.org/][notmuch]] -- to index and tag your downloaded messages.
+ [[https://github.com/afewmail/afew][afew]] , optionally to initially tag your downloaded messages. + [[https://github.com/afewmail/afew][afew]] -- optionally to initially tag your downloaded messages.
** TODO MacOS ** TODO MacOS
** Arch Linux ** Arch Linux
Run one of the following commands. Run one of the following commands:
#+begin_src sh
#+BEGIN_SRC sh
pacman -S isync notmuch #mbsync pacman -S isync notmuch #mbsync
#+END_SRC #+end_src
#+BEGIN_SRC sh #+begin_src sh
pacman -S offlineimap notmuch pacman -S offlineimap notmuch
#+END_SRC #+end_src
See: [[https://wiki.archlinux.org/index.php/Notmuch][Arch Wiki - Notmuch]] See: [[https://wiki.archlinux.org/index.php/Notmuch][Arch Wiki - Notmuch]]
** NixOS ** NixOS
#+BEGIN_SRC nix #+begin_src nix
environment.systemPackages = with pkgs; [ environment.systemPackages = with pkgs; [
notmuch notmuch
# And one of the following # And one of the following
@ -64,20 +63,28 @@ environment.systemPackages = with pkgs; [
isync isync
offlineimap offlineimap
]; ];
#+END_SRC #+end_src
[[https://github.com/Emiller88/dotfiles/blob/319841bd3b89e59b01d169137cceee3183aba4fc/modules/shell/mail.nix][An example of setting up mbsync and notmuch with home-manager]] [[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 openSUSE
** TODO Debian/Ubuntu ** TODO Debian/Ubuntu
* Features * TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
| Keymap | Command | Description | | Keymap | Command | Description |
| ~SPC m u~ | =+notmuch/update= | Download, sync, and index emails with notmuch | |-----------------+--------------------+-----------------------------------------------|
| ~SPC m c~ | =+notmuch/compose= | Compose new email | | [[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
* Configuration
** Downloading your email ** Downloading your email
To download your email you need a sync backend. Out of the box, this module To download your email you need a sync backend. Out of the box, this module
supports =Gmailier= (the default), =mbsync=, and =offlineimap= (ordered by supports =Gmailier= (the default), =mbsync=, and =offlineimap= (ordered by
@ -86,109 +93,118 @@ through setting them up with notmuch.
Later, once you've set up a sync backend and downloaded your email, you must Later, once you've set up a sync backend and downloaded your email, you must
index your email for the first time: index your email for the first time:
#+begin_src sh
#+BEGIN_SRC sh
notmuch new notmuch new
#+END_SRC #+end_src
*** lieer *** lieer
[[https://github.com/gauteh/lieer][Lieer]], formerly called Gmailieer, is the indexing tool used by default. To
[[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]]. install lieer, see the [[https://github.com/gauteh/lieer#installation][installation docs]].
*** offlineimap *** offlineimap
To use [[https://www.offlineimap.org/][offlineimap]], change ~+notmuch-sync-backend~: To use [[https://www.offlineimap.org/][offlineimap]], change ~+notmuch-sync-backend~:
#+begin_src emacs-lisp
#+BEGIN_SRC emacs-lisp ;; add to $DOOMDIR/config.el
;; add to ~/.doom.d/config.el
(setq +notmuch-sync-backend 'offlineimap) (setq +notmuch-sync-backend 'offlineimap)
#+END_SRC #+end_src
Next, write a configuration file for =offlineimap=. [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][Here is a comprehensive 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]]. 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 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 ~\~/.mail~. I used [[https://www.passwordstore.org/][unix pass]] to securely store my login download mail to =$HOME/.mail=. I used [[https://www.passwordstore.org/][unix pass]] to securely store my login
credentials. credentials.
Finally, download your email with ~offlineimap -o~. This may take a while, Finally, download your email with ~$ offlineimap -o~. This may take a while,
especially if you have thousands of emails. especially if you have thousands of emails.
*** mbsync *** mbsync
To use [[https://isync.sourceforge.io/][mbsync]], change ~+notmuch-sync-backend~: To use [[https://isync.sourceforge.io/][mbsync]], change ~+notmuch-sync-backend~:
#+begin_src emacs-lisp
#+BEGIN_SRC emacs-lisp
(setq +notmuch-sync-backend 'mbsync) (setq +notmuch-sync-backend 'mbsync)
;; Use `mbsync-xdg' if your mbsync config lives in $XDG_CONFIG_HOME/isync: ;; Use `mbsync-xdg' if your mbsync config lives in $XDG_CONFIG_HOME/isync:
(setq +notmuch-sync-backend 'mbsync-xdg) (setq +notmuch-sync-backend 'mbsync-xdg)
#+END_SRC #+end_src
The steps needed to set up =notmuch= with =mbsync= are similar to the ones for The steps needed to set up =notmuch= with =mbsync= are similar to the ones for
[[*offlineimap][offlineimap]]. [[*offlineimap][offlineimap]].
Start with writing a ~\~/.mbsyncrc~ to store your configuration. An example for Start with writing a =$HOME/.mbsyncrc= to store your configuration. An example
GMAIL can be found on the [[https://wiki.archlinux.org/index.php/isync#Configuring][ArchWiki]] which will also explain how its integration for GMAIL can be found on the [[https://wiki.archlinux.org/index.php/isync#Configuring][ArchWiki]] which will also explain how its
with notmuch for auto synchronization. A non-GMAIL example is available as a integration with notmuch for auto synchronization. A non-GMAIL example is
gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]]. available as a gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]].
Finally, download your email with ~mbsync --all~. This may take a while, but Finally, download your email with ~$ mbsync --all~. This may take a while, but
will be quicker than =offlineimap=. will be quicker than =offlineimap=.
*** Custom method *** Custom method
If you have a unique method for synchronizing your email, you can define your If you have a unique method for synchronizing your email, you can define your
own backend: own backend:
#+begin_src emacs-lisp
#+BEGIN_SRC emacs-lisp
(setq +notmuch-sync-backend 'custom (setq +notmuch-sync-backend 'custom
;; Set this to an arbitrary shell command ;; Set this to an arbitrary shell command
+notmuch-sync-command "my-notmuch-sync-cmd") +notmuch-sync-command "my-notmuch-sync-cmd")
#+END_SRC #+end_src
** Sending mail ** Sending mail
- [[https://notmuchmail.org/notmuch-emacs/#index6h2][notmuch docs: 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/#index11h2][notmuch docs: msmtp, message mode and multiple accounts]]
- [[https://notmuchmail.org/emacstips/#index12h2][notmuch docs: sending mail using smtpmail]] - [[https://notmuchmail.org/emacstips/#index12h2][notmuch docs: sending mail using smtpmail]]
** Customize =*notmuch-hello*= buffer ** Customize =*notmuch-hello*= buffer
It is possible to change the =*notmuch-hello*= buffer if you want to. It is possible to change the =*notmuch-hello*= buffer if you want to.
#+begin_src emacs-lisp
#+BEGIN_SRC emacs-lisp ;; add to $DOOMDIR/config.el
(after! notmuch (after! notmuch
(setq notmuch-show-log nil (setq notmuch-show-log nil
notmuch-hello-sections `(notmuch-hello-insert-saved-searches notmuch-hello-sections `(notmuch-hello-insert-saved-searches
notmuch-hello-insert-alltags) notmuch-hello-insert-alltags)
;; To hide headers while composing an email ;; To hide headers while composing an email
notmuch-message-headers-visible nil)) notmuch-message-headers-visible nil))
#+END_SRC #+end_src
** Changing the =notmuch= landing page ** Changing the =notmuch= landing page
You may want to forego the =*notmuch-hello*= buffer by having ~M-x =notmuch~ or 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. [[kbd:][<leader> o m]] take you straight to a search page.
When using ~SPC o m~ the =+notmuch-home-function= is called. By default it uses When using [[kbd:][<leader> o m]] the ~+notmuch-home-function~ is called. By default it
the =notmuch= function and so has the same familiar behavior of running a 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 vanilla install of notmuch-emacs. But, by overwriting this function you can run
a custom search as your landing page. a custom search as your landing page.
#+begin_src emacs-lisp
#+BEGIN_SRC emacs-lisp
(setq +notmuch-home-function (lambda () (notmuch-search "tag:inbox"))) (setq +notmuch-home-function (lambda () (notmuch-search "tag:inbox")))
#+END_SRC #+end_src
** Writing HTML Emails ** 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. 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: 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~.
- To convert an email to an HTML email use ~M-x org-mime-htmlize~ If you'd like to make configuration changes to =org-mime=, you may do so
- To compose email using an org-mode editor buffer, use ~M-x org-mime-edit-mail-in-org-mode~ 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
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. you're used to sending, so here's some example configuration that turns those
features off:
/config.el/
#+begin_src emacs-lisp #+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(after! org-mime (after! org-mime
(setq org-mime-export-options '(:section-numbers nil (setq org-mime-export-options '(:section-numbers nil
:with-author nil :with-author nil
:with-toc nil))) :with-toc nil)))
#+end_src #+end_src
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* TODO Troubleshooting * 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

56
modules/email/wanderlust/README.org Normal file
View file

@ -0,0 +1,56 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::email wanderlust][Issues]] ↖ [[doom-module-source:email/wanderlust][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :email wanderlust
#+SUBTITLE: To boldly go where no mail has gone before
#+CREATED: May 05, 2019
#+SINCE: 21.12.0
* Description :unfold:
#+begin_quote
🔨 This module has no description. [[doom-contrib-module:][Write one?]]
#+end_quote
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +gmail ::
Enable gmail-specific configuration for mail ~To~ or ~From~ a gmail address.
** Packages
- [[doom-package:][wanderlust]]
** 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 has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* 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