mirror of
https://github.com/djcb/mu.git
synced 2024-06-29 07:51:04 +02:00
4ce296d6b2
Texinfo is of the opinion that every hyperlink has to be prefixed by either "see" or "in". If neither of these words appears there, then it inserts "see" and it cannot be told not to do that. This turns a correct sentence like: > Mu4e lets you define custom actions for messages in the <Headers view>. into: > Mu4e lets you define custom actions for messages in the see <Headers view>. The best compromise is > Mu4e lets you define custom actions for messages in <Headers view>. which isn't correct but at least less messed up. Alternatively one could rephrase every sentence that contains a link to circumvent Texinfo's speech impairment. Or one could replace each link with a footnote and place the actual link in the footnote.
4649 lines
175 KiB
Plaintext
4649 lines
175 KiB
Plaintext
\input texinfo.tex @c -*-texinfo-*-
|
|
@documentencoding UTF-8
|
|
@include version.texi
|
|
@c %**start of header
|
|
@setfilename mu4e.info
|
|
@settitle Mu4e @value{VERSION} user manual
|
|
|
|
@c Use proper quote and backtick for code sections in PDF output
|
|
@c Cf. Texinfo manual 14.2
|
|
@set txicodequoteundirected
|
|
@set txicodequotebacktick
|
|
@c %**end of header
|
|
|
|
@copying
|
|
Copyright @copyright{} 2012-2020 Dirk-Jan C. Binnema
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
|
copy of the license is included in the section entitled ``GNU Free
|
|
Documentation License.''
|
|
@end quotation
|
|
@end copying
|
|
|
|
@titlepage
|
|
@title @t{Mu4e} --- an e-mail client for GNU Emacs
|
|
@subtitle version @value{VERSION}, @value{UPDATED}
|
|
@author Dirk-Jan C. Binnema
|
|
|
|
@c The following two commands start the copyright page.
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* Mu4e: (Mu4e). An email client for GNU Emacs.
|
|
@end direntry
|
|
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top mu4e manual
|
|
@end ifnottex
|
|
|
|
@iftex
|
|
@node Welcome to mu4e
|
|
@unnumbered Welcome to mu4e
|
|
@end iftex
|
|
|
|
Welcome to @t{mu4e} @value{VERSION}.
|
|
|
|
@t{mu4e} (@t{mu}-for-emacs) is an e-mail client for GNU Emacs version
|
|
24.4 or higher, built on top of the
|
|
@t{mu}@footnote{@url{https://www.djcbsoftware.nl/code/mu}} e-mail search
|
|
engine. @t{mu4e} is optimized for quickly processing large amounts of
|
|
e-mail.
|
|
|
|
Some of its highlights:
|
|
@itemize
|
|
@item Fully search-based: there are no folders@footnote{that is, instead of
|
|
folders, you use queries that match messages in a particular folder}, only
|
|
queries.
|
|
@item Fully documented, with example configurations
|
|
@item User-interface optimized for speed, with quick key strokes for common actions
|
|
@item Support for non-English languages (so ``angstrom'' matches ``Ångström'')
|
|
@item Asynchronous: heavy actions don't block @t{emacs}@footnote{currently,
|
|
the only exception to this is @emph{sending mail}; there are solutions
|
|
for that though --- see the @ref{FAQ}}
|
|
@item Support for cryptography --- signing, encrypting and decrypting
|
|
@item Address auto-completion based on the contacts in your messages
|
|
@item Extendable with your own snippets of elisp
|
|
@end itemize
|
|
|
|
In this manual, we go through the installation of @t{mu4e}, do some
|
|
basic configuration and explain its daily use. We also show you how you
|
|
can customize @t{mu4e} for your special needs.
|
|
|
|
At the end of the manual, there are some example configurations, to get
|
|
you up to speed quickly: @ref{Example configs}. There's also a
|
|
section with answers to frequenly asked questions, @ref{FAQ}.
|
|
|
|
@menu
|
|
* Introduction:: Where to begin
|
|
* Getting started:: Setting things up
|
|
* Main view:: The @t{mu4e} overview
|
|
* Headers view:: Lists of message headers
|
|
* Message view:: Viewing specific messages
|
|
* Editor view:: Creating / editing messages
|
|
* Searching:: Some more background on searching/queries
|
|
* Marking:: Marking messages and performing actions
|
|
* Contexts:: Defining contexts and switching between them
|
|
* Dynamic folders:: Folders that change based on circumstances
|
|
* Actions:: Defining and using custom actions
|
|
* Extending mu4e:: Writing code for @t{mu4e}
|
|
|
|
Appendices
|
|
* Other tools:: mu4e and the rest of the world
|
|
* Example configs:: Some examples to set you up quickly
|
|
* FAQ:: Common questions and answers
|
|
* Tips and Tricks:: Useful tips
|
|
* How it works:: Some notes about the implementation of @t{mu4e}
|
|
* Debugging:: How to debug problems in @t{mu4e}
|
|
|
|
* GNU Free Documentation License:: The license of this manual
|
|
@end menu
|
|
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
Let's get started!
|
|
|
|
@menu
|
|
* Why another e-mail client::Aren't there enough already
|
|
* Other mail clients::Where @t{mu4e} takes its inspiration from
|
|
* What mu4e does not do::Focus on the core-business, delegate the rest
|
|
* Becoming a mu4e user::Joining the club
|
|
@end menu
|
|
|
|
@node Why another e-mail client
|
|
@section Why another e-mail client?
|
|
|
|
I (the author) spend a @emph{lot} of time dealing with e-mail, both
|
|
professionally and privately. Having an efficient e-mail client is
|
|
essential. Since none of the existing ones worked the way I wanted, I
|
|
thought about creating my own.
|
|
|
|
@command{emacs} is an integral part of my workflow, so it made a lot of
|
|
sense to use it for e-mail as well. And as I had already written an
|
|
e-mail search engine (@t{mu}), it seemed only logical to use that as a
|
|
basis.
|
|
|
|
@node Other mail clients
|
|
@section Other mail clients
|
|
|
|
Under the hood, @t{mu4e} is fully search-based, similar to programs like
|
|
@t{notmuch}@footnote{@url{https://notmuchmail.org/}} and
|
|
@t{sup}@footnote{@url{https://sup-heliotrope.github.io/}}.
|
|
|
|
However, @t{mu4e}'s user-interface is quite different. @t{mu4e}'s mail
|
|
handling (deleting, moving etc.) is inspired by
|
|
Wanderlust@footnote{@url{http://www.gohome.org/wl/}} (another
|
|
@t{emacs}-based e-mail client),
|
|
@t{mutt}@footnote{@url{http://www.mutt.org/}} and the @t{dired}
|
|
file-manager for emacs.
|
|
|
|
@t{mu4e} tries to keep all the `state' in your maildirs, so you can easily
|
|
switch between clients, synchronize over @abbr{IMAP}, backup with @t{rsync}
|
|
and so on. If you delete the database, you won't lose any information.
|
|
|
|
@node What mu4e does not do
|
|
@section What @t{mu4e} does not do
|
|
|
|
There are a number of things that @t{mu4e} does @b{not} do, by design:
|
|
@itemize
|
|
@item @t{mu}/@t{mu4e} do @emph{not} get your e-mail messages from
|
|
a mail server. That task is delegated to other tools, such as
|
|
@t{offlineimap}@footnote{@url{https://www.offlineimap.org/}},
|
|
@t{isync/mbsync}@footnote{@url{http://isync.sourceforge.net/}} or
|
|
@t{fetchmail}@footnote{@url{http://www.fetchmail.info/}}. As long as the
|
|
messages end up in a maildir, @t{mu4e} and @t{mu} are happy to deal with
|
|
them.
|
|
@item @t{mu4e} also does @emph{not} implement sending of messages; instead, it
|
|
depends on @t{smtpmail} (@inforef{Top,,smtpmail}), which is part of
|
|
@command{emacs}. In addition, @t{mu4e} piggybacks on Gnus' message editor;
|
|
@inforef{Top,,message}.
|
|
@end itemize
|
|
|
|
Thus, many of the things an e-mail client traditionally needs to do, are
|
|
delegated to other tools. This leaves @t{mu4e} to concentrate on what it does
|
|
best: quickly finding the mails you are looking for, and handle them as
|
|
efficiently as possible.
|
|
|
|
@node Becoming a mu4e user
|
|
@section Becoming a @t{mu4e} user
|
|
|
|
If @t{mu4e} sounds like something for you, give it a shot! We're trying
|
|
hard to make it as easy as possible to set up and use; and while you can
|
|
use elisp in various places to augment @t{mu4e}, a lot of knowledge
|
|
about programming or elisp shouldn't be required. The idea is to provide
|
|
sensible defaults, and allow for customization.
|
|
|
|
When you take @t{mu4e} into use, it's a good idea to subscribe to the
|
|
@t{mu}/@t{mu4e}-mailing
|
|
list@footnote{@url{https://groups.google.com/group/mu-discuss}}.
|
|
|
|
Sometimes, you might encounter some unexpected behavior while using
|
|
@t{mu4e}. It could be a bug in @t{mu4e}, it could be an issue in other
|
|
software. Or it could just be a misunderstanding. In any case, if you
|
|
want to report this (either to the mailing list or to
|
|
@url{https://github.com/djcb/mu/issues}, the latter is preferred),
|
|
please always include the following information:
|
|
|
|
@itemize
|
|
@item what did you expect that should happen? what actually happened?
|
|
@item can you provide some exact steps to reproduce?
|
|
@item what version of @t{mu4e} and @t{emacs} were you using? What operating system?
|
|
@item can you reproduce it with @command{emacs -q} and only loading @t{mu4e}?
|
|
@item if the problem is related to some specific message, please include the raw message file (appropriately anonymized, of course)
|
|
@end itemize
|
|
|
|
@node Getting started
|
|
@chapter Getting started
|
|
|
|
In this chapter, we go through the installation of @t{mu4e} and its
|
|
basic setup. After we have succeeded in @ref{Getting mail}, and
|
|
@pxref{Indexing your messages}, we discuss the @ref{Basic
|
|
configuration}.
|
|
|
|
After these steps, @t{mu4e} should be ready to go!
|
|
|
|
@menu
|
|
* Requirements:: What is needed
|
|
* Installation:: How to install @t{mu} and @t{mu4e}
|
|
* Getting mail:: Getting mail from a server
|
|
* Initializing the message store:: Settings things up
|
|
* Indexing your messages:: Creating and maintaining the index
|
|
* Basic configuration:: Settings for @t{mu4e}
|
|
* Folders:: Setting up standard folders
|
|
* Retrieval and indexing:: Doing it from @t{mu4e}
|
|
* Sending mail:: How to send mail
|
|
* Running mu4e:: Overview of the @t{mu4e} views
|
|
|
|
@end menu
|
|
|
|
@node Requirements
|
|
@section Requirements
|
|
|
|
@t{mu}/@t{mu4e} are known to work on a wide variety of Unix- and
|
|
Unix-like systems, including many Linux distributions, OS X and
|
|
FreeBSD, and even on MS-Windows (with Cygwin). @command{emacs} 24 or
|
|
higher is required, as well as
|
|
Xapian@footnote{@url{https://xapian.org/}} and
|
|
GMime@footnote{@url{http://spruce.sourceforge.net/gmime/}}.
|
|
|
|
@t{mu} has optional support for the Guile 2.x (Scheme) programming
|
|
language. There are also some GUI-toys, which require GTK+ 3.x and
|
|
Webkit.
|
|
|
|
If you intend to compile @t{mu} yourself, you need to have the typical
|
|
development tools, such as C and C++ compilers (both @command{gcc} and
|
|
@command{clang} should work), GNU Autotools and @command{make}, and
|
|
the development packages for GMime 3.x, GLib and Xapian. Optionally,
|
|
you also need the development packages for GTK+, Webkit and Guile.
|
|
|
|
@node Installation
|
|
@section Installation
|
|
|
|
@t{mu4e} is part of @t{mu} --- by installing the latter, the former is
|
|
installed as well. Some Linux distributions provide packaged versions
|
|
of @t{mu}/@t{mu4e}; if you can use those, there is no need to compile
|
|
anything yourself. However, if there are no packages for your
|
|
distribution, if they are outdated, or if you want to use the latest
|
|
development versions, you can follow the steps below.
|
|
|
|
First, you need make sure you have the necessary dependencies; the
|
|
details depend on your distribution. If you're using another
|
|
distribution (or another OS), the below can at least be helpful in
|
|
identifying the packages to install.
|
|
|
|
We provide some instructions for Debian, Ubuntu and Fedora; if those do not
|
|
apply to you, you can follow either @ref{Building from a release tarball} or
|
|
@ref{Building from git}.
|
|
|
|
@subsection Dependencies for Debian/Ubuntu
|
|
|
|
@example
|
|
$ sudo apt-get install libgmime-3.0-dev libxapian-dev
|
|
|
|
# get emacs 25 or higher if you don't have it yet
|
|
$ sudo apt-get install emacs
|
|
|
|
# optional
|
|
$ sudo apt-get install guile-2.0-dev html2text xdg-utils
|
|
|
|
# optional: only needed for msg2pdf and mug (toy gtk+ frontend)
|
|
$ sudo apt-get install libwebkitgtk-3.0-dev
|
|
@end example
|
|
|
|
@subsection Dependencies for Fedora
|
|
|
|
@example
|
|
$ sudo yum install gmime30-devel xapian-core-devel
|
|
|
|
# get emacs 25 or higher if you don't have it yet
|
|
$ sudo yum install emacs
|
|
|
|
# optional
|
|
$ sudo yum install html2text xdg-utils
|
|
|
|
# optional: only needed for msg2pdf and mug (toy gtk+ frontend)
|
|
$ sudo yum install webkitgtk3-devel
|
|
@end example
|
|
|
|
@subsection Building from a release tarball
|
|
@anchor{Building from a release tarball}
|
|
|
|
Using a release-tarball (as available from
|
|
GitHub@footnote{@url{https://github.com/djcb/mu/releases}}),
|
|
installation follows the typical steps:
|
|
|
|
@example
|
|
$ tar xvfz mu-<version>.tar.gz # use the specific version
|
|
$ cd mu-<version>
|
|
# On the BSDs: use gmake instead of make
|
|
$ ./configure && make
|
|
$ sudo make install
|
|
@end example
|
|
|
|
Xapian, GMime and their dependencies must be installed.
|
|
|
|
@subsection Building from git
|
|
@anchor{Building from git}
|
|
|
|
Alternatively, if you build from the git repository or use a tarball
|
|
like the ones that @t{github} produces, the instructions are slightly
|
|
different, and require you to have autotools (@t{autoconf},
|
|
@t{automake}, @t{libtool}, @t{texinfo}) installed:
|
|
|
|
@example
|
|
# get from git (alternatively, use a github tarball)
|
|
$ git clone git://github.com/djcb/mu.git
|
|
|
|
$ cd mu
|
|
$ ./autogen.sh && ./configure && make
|
|
# On the BSDs: use gmake instead of make
|
|
$ sudo make install
|
|
@end example
|
|
|
|
(Xapian, GMime and their dependencies must be installed).
|
|
|
|
After this, @t{mu} and @t{mu4e} should be installed @footnote{there's a hard
|
|
dependency between versions of @t{mu4e} and @t{mu} --- you cannot combine
|
|
different versions} on your system, and be available from the command line
|
|
in @command{emacs}.
|
|
|
|
You may need to restart @command{emacs}, so it can find @t{mu4e} in its
|
|
@code{load-path}. If, even after restarting, @command{emacs} cannot find
|
|
@t{mu4e}, you may need to add it to your @code{load-path} explicitly; check
|
|
where @t{mu4e} is installed, and add something like the following to your
|
|
configuration before trying again:
|
|
@lisp
|
|
;; the exact path may differ --- check it
|
|
(add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e")
|
|
@end lisp
|
|
|
|
@subsection mu4e and emacs customization
|
|
|
|
There is some support for using the @command{emacs} customization system in
|
|
@t{mu4e}, but for now, we recommend setting the values manually. Please refer
|
|
to @ref{Example configs} for a couple of examples of this; here we go
|
|
through things step-by-step.
|
|
|
|
@node Getting mail
|
|
@section Getting mail
|
|
|
|
In order for @t{mu} (and, by extension, @t{mu4e}) to work, you need to
|
|
have your e-mail messages stored in a
|
|
@emph{maildir}@footnote{@url{https://en.wikipedia.org/wiki/Maildir};
|
|
in this manual we use the term `maildir' for both the standard and the
|
|
hierarchy of maildirs that store your messages} --- a specific
|
|
directory structure with one-file-per-message. If you are already
|
|
using a maildir, you are lucky. If not, some setup is required:
|
|
|
|
@itemize
|
|
@item @emph{Using an external IMAP or POP server} --- if you are using an
|
|
@abbr{IMAP} or @abbr{POP} server, you can use tools like @t{getmail},
|
|
@t{fetchmail}, @t{offlineimap} or @t{isync} to download your messages
|
|
into a maildir (@file{~/Maildir}, often). Because it is such a common
|
|
case, there is a full example of setting @t{mu4e} up with
|
|
@t{offlineimap} and Gmail; @pxref{Gmail configuration}.
|
|
@item @emph{Using a local mail server} --- if you are using a local mail-server
|
|
(such as @t{postfix} or @t{qmail}), you can teach them to deliver into
|
|
a maildir as well, maybe in combination with @t{procmail}. A bit of
|
|
googling should be able to provide you with the details.
|
|
@end itemize
|
|
|
|
@node Initializing the message store
|
|
@section Initializing the message store
|
|
|
|
The first time your run @t{mu}, you need to initialize its store
|
|
(database). The default location for that is @t{~/.cache/mu/xapian},
|
|
but you can change this using the @t{--muhome} option, and remember to
|
|
pass that to the other commands as well.
|
|
|
|
Assuming that your maildir is at @file{~/Maildir}, we issue the
|
|
following command:
|
|
@example
|
|
$ mu init --maildir=~/Maildir
|
|
@end example
|
|
|
|
Optionally, you can add some e-mail addresses, so @t{mu} recognizes
|
|
them as yours:
|
|
|
|
@example
|
|
$ mu init --maildir=~/Maildir --my-address=jim@@example.com --my-address=bob@@example.com
|
|
@end example
|
|
|
|
@t{mu} remembers the maildir and your addresses and uses them when
|
|
indexing messages. If you want to change them, you need to @t{init}
|
|
once again.
|
|
|
|
If you want to see the current values, you can use @t{mu info}.
|
|
|
|
@node Indexing your messages
|
|
@section Indexing your messages
|
|
|
|
After you have succeeded in @ref{Getting mail} and initialized the
|
|
message database, we need to @emph{index} the messages. That is --- we
|
|
need to scan the messages in the maildir and store the information
|
|
about them in a special database.
|
|
|
|
We can do that from @t{mu4e} --- @ref{Main view}, but the first time,
|
|
it is a good idea to run it from the command line, which makes it
|
|
easier to verify that everything works correctly.
|
|
|
|
Assuming that your maildir is at @file{~/Maildir}, we issue the following
|
|
command:
|
|
@example
|
|
$ mu index
|
|
@end example
|
|
|
|
This should scan your messages and fill the database, and give
|
|
progress information while doing so.
|
|
|
|
The indexing process may take a few minutes the first time you do it
|
|
(for thousands of e-mails); afterwards it is much faster, since @t{mu}
|
|
only scans messages that are new or have changed. Indexing is discussed
|
|
in full detail in the @t{mu-index} man-page.
|
|
|
|
After the indexing process has finished, you can quickly test if everything
|
|
worked, by trying some command-line searches, for example
|
|
@example
|
|
$ mu find hello
|
|
@end example
|
|
|
|
which lists all messages that match @t{hello}. For more examples of searches,
|
|
see @ref{Queries}, or check the @t{mu-find} and @t{mu-easy} man pages. If all
|
|
of this worked well, we are well on our way setting things up; the next step
|
|
is to do some basic configuration for @t{mu4e}.
|
|
|
|
@node Basic configuration
|
|
@section Basic configuration
|
|
|
|
Before we can start using @t{mu4e}, we need to tell @command{emacs} to load
|
|
it. So, add to your @file{~/.emacs} (or its moral equivalent, such as
|
|
@file{~/.emacs.d/init.el}) something like:
|
|
|
|
@lisp
|
|
(require 'mu4e)
|
|
@end lisp
|
|
|
|
If @command{emacs} complains that it cannot find @t{mu4e}, check your
|
|
@code{load-path} and make sure that @t{mu4e}'s installation directory is part
|
|
of it. If not, you can add it:
|
|
|
|
@lisp
|
|
(add-to-list 'load-path MU4E-PATH)
|
|
@end lisp
|
|
|
|
with @t{MU4E-PATH} replaced with the actual path.
|
|
|
|
@node Folders
|
|
@section Folders
|
|
|
|
The next step is to tell @t{mu4e} where it can find your Maildir, and
|
|
some special folders.
|
|
|
|
So, for example@footnote{Note that the folders (@t{mu4e-sent-folder},
|
|
@t{mu4e-drafts-folder}, @t{mu4e-trash-folder} and
|
|
@t{mu4e-refile-folder}) can also be @emph{functions} that are evaluated
|
|
at runtime. This allows for dynamically changing them depending on the
|
|
situation. See @ref{Dynamic folders} for details.}:
|
|
@lisp
|
|
;; these are actually the defaults
|
|
(setq
|
|
mu4e-sent-folder "/sent" ;; folder for sent messages
|
|
mu4e-drafts-folder "/drafts" ;; unfinished messages
|
|
mu4e-trash-folder "/trash" ;; trashed messages
|
|
mu4e-refile-folder "/archive") ;; saved messages
|
|
@end lisp
|
|
|
|
Note, the folder names are all relative to the root-maildir (see the
|
|
output of @t{mu info}). If you use @t{mu4e-context}, see @ref{Contexts
|
|
and special folders} for what that means for these special folders.
|
|
|
|
@node Retrieval and indexing
|
|
@section Retrieval and indexing with mu4e
|
|
|
|
As we have seen, we can do all of the mail retrieval @emph{outside} of
|
|
@command{emacs}/@t{mu4e}. However, you can also do it from within
|
|
@t{mu4e}.
|
|
|
|
@subsection Basics
|
|
|
|
To set up mail-retrieval from within @t{mu4e}, set the variable
|
|
@code{mu4e-get-mail-command} to the program or shell command you want to
|
|
use for retrieving mail. You can then get your e-mail using @kbd{M-x
|
|
mu4e-update-mail-and-index}, or @kbd{C-S-u} in all @t{mu4e}-views;
|
|
alternatively, you can use @kbd{C-c C-u}, which may be more convenient
|
|
if you use emacs in a terminal.
|
|
|
|
You can kill the (foreground) update process with @kbd{q}.
|
|
|
|
It is possible to update your mail and index periodically in the
|
|
background or foreground, by setting the variable
|
|
@code{mu4e-update-interval} to the number of seconds between these
|
|
updates. If set to @code{nil}, it won't update at all. After you make
|
|
changes to @code{mu4e-update-interval}, @t{mu4e} must be restarted
|
|
before the changes take effect. By default, this will run in
|
|
background and to change it to run in foreground, set
|
|
@code{mu4e-index-update-in-background} to @code{nil}.
|
|
|
|
@subsection Handling errors during mail retrieval
|
|
|
|
If the mail-retrieval process returns with a non-zero exit code,
|
|
@t{mu4e} shows a warning (unless @code{mu4e-index-update-error-warning}
|
|
is set to @code{nil}), but then try to index your maildirs anyway
|
|
(unless @code{mu4e-index-update-error-continue} is set to @code{nil}).
|
|
|
|
Reason for these defaults is that some of the mail-retrieval programs
|
|
may return non-zero, even when the updating process succeeded; however,
|
|
it is hard to tell such pseudo-errors from real ones like `login
|
|
failed'.
|
|
|
|
If you need more refinement, it may be useful to wrap the mail-retrieval
|
|
program in a shell-script, for example @t{fetchmail} returns 1 to
|
|
indicate `no mail'; we can handle that with:
|
|
@lisp
|
|
(setq mu4e-get-mail-command "fetchmail -v || [ $? -eq 1 ]")
|
|
@end lisp
|
|
A similar approach can be used with other mail retrieval programs,
|
|
although not all of them have their exit codes documented.
|
|
|
|
@subsection Implicit mail retrieval
|
|
|
|
If you don't have a specific command for getting mail, for example
|
|
because you are running your own mail-server, you can leave
|
|
@code{mu4e-get-mail-command} at @t{"true"} (the default), in which case
|
|
@t{mu4e} won't try to get new mail, but still re-index your messages.
|
|
|
|
@subsection Speeding up indexing
|
|
|
|
If you have a large number of e-mail messages in your store,
|
|
(re)indexing might take a while. The defaults for indexing are to
|
|
ensure that we always have correct, up-to-date information about your
|
|
messages, even if other programs have modified the Maildir.
|
|
|
|
The downside of this thoroughness (which is the default) is that it is
|
|
relatively slow, something that can be noticeable with large e-mail
|
|
corpa. For a faster approach, you can use the following:
|
|
|
|
@lisp
|
|
(setq
|
|
mu4e-index-cleanup nil ;; don't do a full cleanup check
|
|
mu4e-index-lazy-check t) ;; don't consider up-to-date dirs
|
|
@end lisp
|
|
|
|
In many cases, the mentioned thoroughness might not be needed, and these
|
|
settings give a very significant speed-up. Note that you can of course
|
|
occasionally run a thorough indexing round.
|
|
|
|
For further details, please refer to the @t{mu-index} manpage; in
|
|
particular, see @t{.noindex} and @t{.noupdate} which can help reducing
|
|
the indexing time.
|
|
|
|
@subsection Example setup
|
|
|
|
A simple setup could look something like:
|
|
|
|
@lisp
|
|
(setq
|
|
mu4e-get-mail-command "offlineimap" ;; or fetchmail, or ...
|
|
mu4e-update-interval 300) ;; update every 5 minutes
|
|
@end lisp
|
|
|
|
A hook @code{mu4e-update-pre-hook} is available which is run right
|
|
before starting the process. That can be useful, for example, to
|
|
influence, @code{mu4e-get-mail-command} based on the the current
|
|
situation (location, time of day, ...).
|
|
|
|
It is possible to get notifications when the indexing process does any
|
|
updates --- for example when receiving new mail. See
|
|
@code{mu4e-index-updated-hook} and some tips on its usage in the
|
|
@ref{FAQ}.
|
|
|
|
@node Sending mail
|
|
@section Sending mail
|
|
|
|
@t{mu4e} re-uses Gnus' @code{message-mode} (@inforef{Top,,message}) for
|
|
writing mail and inherits the setup for sending mail as well.
|
|
|
|
For sending mail using @abbr{SMTP}, @t{mu4e} uses @t{smtpmail}
|
|
(@inforef{Top,,smtpmail}). This package supports many different ways to
|
|
send mail; please refer to its documentation for the details.
|
|
|
|
Here, we only provide some simple examples --- for more, see
|
|
@ref{Example configs}.
|
|
|
|
A very minimal setup:
|
|
|
|
@lisp
|
|
;; tell message-mode how to send mail
|
|
(setq message-send-mail-function 'smtpmail-send-it)
|
|
;; if our mail server lives at smtp.example.org; if you have a local
|
|
;; mail-server, simply use 'localhost' here.
|
|
(setq smtpmail-smtp-server "smtp.example.org")
|
|
@end lisp
|
|
|
|
Since @t{mu4e} (re)uses the same @t{message mode} and @t{smtpmail} that Gnus
|
|
uses, many settings for those also apply to @t{mu4e}.
|
|
|
|
@subsection Dealing with sent messages
|
|
|
|
By default, @t{mu4e} puts a copy of messages you sent in the folder determined
|
|
by @code{mu4e-sent-folder}. In some cases, this may not be what you want -
|
|
for example, when using Gmail-over-@abbr{IMAP}, this interferes with Gmail's
|
|
handling of the sent messages folder, and you may end up with duplicate
|
|
messages.
|
|
|
|
You can use the variable @code{mu4e-sent-messages-behavior} to customize what
|
|
happens with sent messages. The default is the symbol @code{sent} which, as
|
|
mentioned, causes the message to be copied to your sent-messages folder. Other
|
|
possible values are the symbols @code{trash} (the sent message is moved to the
|
|
trash-folder (@code{mu4e-trash-folder}), and @code{delete} to simply discard
|
|
the sent message altogether (so Gmail can deal with it).
|
|
|
|
For Gmail-over-@abbr{IMAP}, you could add the following to your settings:
|
|
@verbatim
|
|
;; don't save messages to Sent Messages, Gmail/IMAP takes care of this
|
|
(setq mu4e-sent-messages-behavior 'delete)
|
|
@end verbatim
|
|
And that's it! We should now be ready to go.
|
|
|
|
For more complex needs, @code{mu4e-sent-messages-behavior} can also be
|
|
a parameter-less function that returns one of the mentioned symbols;
|
|
see the built-in documentation for the variable.
|
|
|
|
@node Running mu4e
|
|
@section Running mu4e
|
|
|
|
After following the steps in this chapter, we now (hopefully!) have a
|
|
working @t{mu4e} setup. Great! In the next chapters, we walk you
|
|
through the various views in @t{mu4e}.
|
|
|
|
For your orientation, the diagram below shows how the views relate to each
|
|
other, and the default key-bindings to navigate between them.
|
|
|
|
@cartouche
|
|
@verbatim
|
|
|
|
[C] +--------+ [RFCE]
|
|
--------> | editor | <--------
|
|
/ +--------+ \
|
|
/ [RFCE]^ \
|
|
/ | \
|
|
+-------+ [sjbB]+---------+ [RET] +---------+
|
|
| main | <---> | headers | <----> | message |
|
|
+-------+ [q] +---------+ [qbBjs] +---------+
|
|
[sjbB] ^
|
|
[.] | [q]
|
|
V
|
|
+-----+
|
|
| raw |
|
|
+-----+
|
|
|
|
Default bindings
|
|
----------------
|
|
R: Reply s: search .: raw view (toggle)
|
|
F: Forward j: jump-to-maildir q: quit
|
|
C: Compose b: bookmark-search
|
|
E: Edit B: edit bookmark-search
|
|
|
|
@end verbatim
|
|
@end cartouche
|
|
|
|
@node Main view
|
|
@chapter The main view
|
|
|
|
After you have installed @t{mu4e} (@pxref{Getting started}), you can start it
|
|
with @kbd{M-x mu4e}. @t{mu4e} does some checks to ensure everything is set up
|
|
correctly, and then shows you the @t{mu4e} main view. Its major mode is
|
|
@code{mu4e-main-mode}.
|
|
|
|
@menu
|
|
* Overview: MV Overview. What is the main view
|
|
* Basic actions::What can we do
|
|
* Bookmarks: MV Bookmarks. Jumping to other places
|
|
* Miscellaneous::Notes
|
|
@end menu
|
|
|
|
@node MV Overview
|
|
@section Overview
|
|
|
|
The main view looks something like the following:
|
|
|
|
@cartouche
|
|
@verbatim
|
|
* mu4e - mu for emacs version @value{VERSION}; (in store: 78379 messages)
|
|
|
|
Basics
|
|
|
|
* [j]ump to some maildir
|
|
* enter a [s]earch query
|
|
* [C]ompose a new message
|
|
|
|
Bookmarks
|
|
|
|
* [bu] Unread messages (26217/26217)
|
|
* [bt] Today's messages (2/8)
|
|
* [bw] Last 7 days (7/34)
|
|
* [bp] Messages with images (276/2315)
|
|
|
|
Misc
|
|
|
|
* [;]Switch context
|
|
* [U]pdate email & database
|
|
|
|
* [N]ews
|
|
* [A]bout mu4e
|
|
* [H]elp
|
|
* [q]uit
|
|
|
|
@end verbatim
|
|
@end cartouche
|
|
|
|
Let's walk through the menu.
|
|
|
|
@node Basic actions
|
|
@section Basic actions
|
|
|
|
First, the @emph{Basics}:
|
|
@itemize
|
|
@item @t{[j]ump to some maildir}: after pressing @key{j} (``jump''),
|
|
@t{mu4e} asks you for a maildir to visit. These are the maildirs you
|
|
set in @ref{Basic configuration} and any of your own. If you choose
|
|
@key{o} (``other'') or @key{/}, you can choose from all maildirs under
|
|
the root-maildir. After choosing a maildir, the messages in that
|
|
maildir are listed, in the @ref{Headers view}.
|
|
@item @t{enter a [s]earch query}: after pressing @key{s}, @t{mu4e} asks
|
|
you for a search query, and after entering one, shows the results in the
|
|
@ref{Headers view}.
|
|
@item @t{[C]ompose a new message}: after pressing @key{C}, you are dropped in
|
|
the @ref{Editor view} to write a new message.
|
|
@end itemize
|
|
|
|
@node MV Bookmarks
|
|
@section Bookmarks
|
|
|
|
The next item in the Main view is @emph{Bookmarks}.
|
|
|
|
Bookmarks are predefined queries with a descriptive name and a
|
|
shortcut --- in the example above, we see the default bookmarks. You
|
|
can view the list of messages matching a certain bookmark by pressing
|
|
@key{b} followed by the bookmark's shortcut. If you'd like to edit the
|
|
bookmarked query first before invoking it, use @key{B}.
|
|
|
|
Next to each bookmark there is the number of (unread/all) messages
|
|
that match.
|
|
|
|
Bookmarks are stored in the variable @code{mu4e-bookmarks}; you can add your
|
|
own and/or replace the default ones; @xref{Bookmarks}.
|
|
|
|
@node Miscellaneous
|
|
@section Miscellaneous
|
|
|
|
Finally, there are some @emph{Misc} (miscellaneous) actions:
|
|
@itemize
|
|
@item @t{[U]pdate email & database} executes the shell-command in the variable
|
|
@code{mu4e-get-mail-command}, and afterwards updates the @t{mu} database;
|
|
see @ref{Indexing your messages} and @ref{Getting mail} for details.
|
|
@item @t{toggle [m]ail sending mode (direct)} toggles between sending
|
|
mail directly, and queuing it first (for example, when you are offline), and
|
|
@t{[f]lush queued mail} flushes any queued mail. This item is visible only
|
|
if you have actually set up mail-queuing. @ref{Queuing mail}
|
|
@item @t{[A]bout mu4e} provides general information about the program
|
|
@item @t{[H]elp} shows help information for this view
|
|
@item Finally, @t{[q]uit mu4e} quits your @t{mu4e}-session
|
|
@end itemize
|
|
|
|
@node Headers view
|
|
@chapter The headers view
|
|
|
|
The headers view shows the results of a query. The header-line shows
|
|
the names of the fields. Below that, there is a line with those
|
|
fields, for each matching message, followed by a footer line. The
|
|
major-mode for the headers view is @code{mu4e-headers-mode}.
|
|
|
|
@menu
|
|
* Overview: HV Overview. What is the Header View
|
|
* Keybindings::Do things with your keyboard
|
|
* Marking: HV Marking. Selecting messages for doing things
|
|
* Sorting and threading::Influencing the display
|
|
* Custom headers: HV Custom headers. Adding your own headers
|
|
* Actions: HV Actions. Defining and using actions
|
|
* Split view::Seeing both headers and messages
|
|
@end menu
|
|
|
|
@node HV Overview
|
|
@section Overview
|
|
|
|
An example headers view:
|
|
@cartouche
|
|
@verbatim
|
|
Date V Flgs From/To List Subject
|
|
06:32 Nu To Edmund Dantès GstDev Gstreamer-V4L2SINK ...
|
|
15:08 Nu Abbé Busoni GstDev ├> ...
|
|
18:20 Nu Pierre Morrel GstDev │└> ...
|
|
07:48 Nu To Edmund Dantès GstDev └> ...
|
|
2013-03-18 S Jacopo EmacsUsr emacs server on win...
|
|
2013-03-18 S Mercédès EmacsUsr └> ...
|
|
2013-03-18 S Beachamp EmacsUsr Re: Copying a whole...
|
|
22:07 Nu Albert de Moncerf EmacsUsr └> ...
|
|
2013-03-18 S Gaspard Caderousse GstDev Issue with GESSimpl...
|
|
2013-03-18 Ss Baron Danglars GuileUsr Guile-SDL 0.4.2 ava...
|
|
End of search results
|
|
@end verbatim
|
|
@end cartouche
|
|
|
|
Some notes to explain what you see in the example:
|
|
|
|
@itemize
|
|
@item The fields shown in the headers view can be influenced by customizing
|
|
the variable @code{mu4e-headers-fields}; see @code{mu4e-header-info} for the
|
|
list of built-in fields. Apart from the built-in fields, you can also create
|
|
custom fields using @code{mu4e-header-info-custom}; see @ref{HV Custom
|
|
headers} for details.
|
|
@item By default, the date is shown with the @t{:human-date} field, which
|
|
shows the @emph{time} for today's messages, and the @emph{date} for older
|
|
messages. If you do not want to distinguish between `today' and `older', you can use
|
|
the @t{:date} field instead.
|
|
@item You can customize the date and time formats with the variable
|
|
@code{mu4e-headers-date-format} and @code{mu4e-headers-time-format},
|
|
respectively. In the example, we use @code{:human-date}, which shows the
|
|
time when the message was sent today, and the date otherwise.
|
|
@item By default, the subject is shown using the @t{:subject} field;
|
|
however, it is also possible to use @t{:thread-subject}, which shows
|
|
the subject of a thread only once, similar to the display of the
|
|
@t{mutt} e-mail client.
|
|
@item The header field used for sorting is indicated by ``@t{V}'' or
|
|
``@t{^}''@footnote{or you can use little graphical triangles; see
|
|
variable @code{mu4e-use-fancy-chars}}, corresponding to the sort order
|
|
(descending or ascending, respectively). You can influence this by a
|
|
mouse click, or @key{O}. Not all fields allow sorting.
|
|
@item Instead of showing the @t{From:} and @t{To:} fields separately, you
|
|
can use From/To (@t{:from-or-to} in @code{mu4e-headers-fields} as a more
|
|
compact way to convey the most important information: it shows @t{From:}
|
|
@emph{except} when the e-mail was sent by the user (i.e., you) --- in that case
|
|
it shows @t{To:} (prefixed by @t{To}@footnote{You can customize this by
|
|
changing the variable @code{mu4e-headers-from-or-to-prefix} (a cons cell)}, as
|
|
in the example above). To determine whether a message was sent by you,
|
|
@t{mu4e} uses the variable @code{mu4e-user-mail-address-list}, a list of
|
|
your e-mail addresses.
|
|
@item The `List' field shows the mailing-list a message is sent to;
|
|
@code{mu4e} tries to create a convenient shortcut for the mailing-list name;
|
|
the variable @code{mu4e-user-mailing-lists} can be used to add your
|
|
your own shortcuts. You can use @code{mu4e-mailing-list-patterns} to
|
|
to specify generic shortcuts, e.g. to shorten list names which contain
|
|
dots (@t{mu4e} defaults to shortening up to the first dot):
|
|
@lisp
|
|
(setq mu4e-mailing-list-patterns '(``\\([-_a-z0-9.]+\\)\.lists\.company\.com'')))
|
|
@end lisp
|
|
@item The letters in the `Flags' field correspond to the following: D=@emph{draft},
|
|
F=@emph{flagged} (i.e., `starred'), N=@emph{new}, P=@emph{passed} (i.e.,
|
|
forwarded), R=@emph{replied}, S=@emph{seen}, T=@emph{trashed},
|
|
a=@emph{has-attachment}, x=@emph{encrypted}, s=@emph{signed},
|
|
u=@emph{unread}. The tooltip for this field also contains this information.
|
|
@item The subject field also indicates the discussion threads @footnote{using
|
|
Jamie Zawinski's mail threading algorithm,
|
|
@url{https://www.jwz.org/doc/threading.html}}.
|
|
@item The headers view is @emph{automatically updated} if any changes are
|
|
found during the indexing process, and if there is no current
|
|
user-interaction. If you do not want such automatic updates, set
|
|
@code{mu4e-headers-auto-update} to @code{nil}.
|
|
@item Just before executing a search, a hook-function
|
|
@code{mu4e-headers-search-hook} is invoked, which receives the search
|
|
expression as its parameter.
|
|
@item Also, there is a hook-function @code{mu4e-headers-found-hook} available which
|
|
is invoked just after @t{mu4e} has completed showing the messages in the
|
|
headers-view.
|
|
@end itemize
|
|
|
|
@node Keybindings
|
|
@section Keybindings
|
|
|
|
Using the below key bindings, you can do various things with these messages;
|
|
these actions are also listed in the @t{Headers} menu in the @command{emacs}
|
|
menu bar.
|
|
|
|
@verbatim
|
|
key description
|
|
===========================================================
|
|
n,p view the next, previous message
|
|
],[ move to the next, previous unread message
|
|
y select the message view (if it's visible)
|
|
RET open the message at point in the message view
|
|
|
|
searching
|
|
---------
|
|
s search
|
|
S edit last query
|
|
/ narrow the search
|
|
b search bookmark
|
|
B edit bookmark before search
|
|
j jump to maildir
|
|
M-left,\ previous query
|
|
M-right next query
|
|
|
|
O change sort order
|
|
P toggle threading
|
|
Q toggle full-search
|
|
V toggle skip-duplicates
|
|
W toggle include-related
|
|
|
|
marking
|
|
-------
|
|
d mark for moving to the trash folder
|
|
= mark for removing trash flag ('untrash')
|
|
DEL,D mark for complete deletion
|
|
m mark for moving to another maildir folder
|
|
r mark for refiling
|
|
+,- mark for flagging/unflagging
|
|
?,! mark message as unread, read
|
|
|
|
u unmark message at point
|
|
U unmark *all* messages
|
|
|
|
% mark based on a regular expression
|
|
T,t mark whole thread, subthread
|
|
|
|
<insert>,* mark for 'something' (decide later)
|
|
# resolve deferred 'something' marks
|
|
|
|
x execute actions for the marked messages
|
|
|
|
composition
|
|
-----------
|
|
R,F,C reply/forward/compose
|
|
E edit (only allowed for draft messages)
|
|
|
|
|
|
misc
|
|
----
|
|
; switch context
|
|
a execute some custom action on a header
|
|
| pipe message through shell command
|
|
C-+,C-- increase / decrease the number of headers shown
|
|
H get help
|
|
C-S-u update mail & reindex
|
|
q leave the headers buffer
|
|
@end verbatim
|
|
|
|
|
|
@node HV Marking
|
|
@section Marking
|
|
|
|
You can @emph{mark} messages for a certain action, such as deletion or
|
|
move. After one or more messages are marked, you can then execute
|
|
(@code{mu4e-mark-execute-all}, @key{x}) these actions. This two-step
|
|
mark-execute sequence is similar to what e.g. @t{dired} does. It is how
|
|
@t{mu4e} tries to be as quick as possible, while avoiding accidents.
|
|
|
|
The mark/unmark commands support the @emph{region} (i.e., ``selection'') ---
|
|
so, for example, if you select some messages and press @key{DEL}, all messages
|
|
in the region are marked for deletion.
|
|
|
|
You can mark all messages that match a certain pattern with @key{%}. In
|
|
addition, you can mark all messages in the current thread (@key{T}) or
|
|
sub-thread (@key{t}).
|
|
|
|
When you do a new search or refresh the headers buffer while you still have
|
|
marked messages, you are asked what to do with those marks --- whether to
|
|
@emph{apply} them before leaving, or @emph{ignore} them. This behavior can be
|
|
influenced with the variable @code{mu4e-headers-leave-behavior}.
|
|
|
|
For more information about marking, see @ref{Marking}.
|
|
|
|
@node Sorting and threading
|
|
@section Sorting and threading
|
|
|
|
By default, @t{mu4e} sorts messages by date, in descending order: the most
|
|
recent messages are shown at the top. In addition, the messages are
|
|
@emph{threaded}, i.e., shown in the context of a discussion thread; this also
|
|
affects the sort order.
|
|
|
|
The header field used for sorting is indicated by ``@t{V}'' or
|
|
``@t{^}''@footnote{or you can use little graphical triangles; see variable
|
|
@code{mu4e-use-fancy-chars}}, indicating the sort order (descending or
|
|
ascending, respectively).
|
|
|
|
You can change the sort order by clicking the corresponding field with the
|
|
mouse, or with @kbd{M-x mu4e-headers-change-sorting} (@key{O}); note that not
|
|
all fields can be used for sorting. You can toggle threading on/off using
|
|
@kbd{M-x mu4e-headers-toggle-threading} or @key{P}. For both of these functions,
|
|
unless you provide a prefix argument (@key{C-u}), the current search is
|
|
updated immediately using the new parameters. You can toggle full-search
|
|
(@ref{Searching}) using @kbd{M-x mu4e-headers-toggle-full-search} or @key{Q}.
|
|
|
|
If you want to change the defaults for these settings, you can use the
|
|
variables @code{mu4e-headers-sort-field} and
|
|
@code{mu4e-headers-show-threads}, as well as
|
|
@code{mu4e-headers-change-sorting} to change the sorting of the current
|
|
search results.
|
|
|
|
@node HV Custom headers
|
|
@section Custom headers
|
|
|
|
Sometimes the normal headers that @t{mu4e} offers (Date, From, To, Subject
|
|
etc.) may not be enough. For these cases, @t{mu4e} offers @emph{custom
|
|
headers} in both the headers-view and the message-view.
|
|
|
|
You can do so by adding a description of your custom header to
|
|
@code{mu4e-header-info-custom}, which is a list of custom headers.
|
|
|
|
Let's look at an example --- suppose we want to add a custom header that
|
|
shows the number of recipients for a message, i.e., the sum of the
|
|
number of recipients in the @t{To:} and @t{Cc:} fields. Let's further
|
|
suppose that our function takes a message-plist as its argument
|
|
(@ref{Message functions}).
|
|
|
|
@lisp
|
|
(add-to-list 'mu4e-header-info-custom
|
|
'(:recipnum .
|
|
( :name "Number of recipients" ;; long name, as seen in the message-view
|
|
:shortname "Recip#" ;; short name, as seen in the headers view
|
|
:help "Number of recipients for this message" ;; tooltip
|
|
:function (lambda (msg)
|
|
(format "%d"
|
|
(+ (length (mu4e-message-field msg :to))
|
|
(length (mu4e-message-field msg :cc))))))))
|
|
@end lisp
|
|
|
|
Or, let's get the full mailing-list name:
|
|
@lisp
|
|
(add-to-list 'mu4e-header-info-custom
|
|
'(:full-mailing-list .
|
|
( :name "Mailing-list" ;; long name, as seen in the message-view
|
|
:shortname "ML" ;; short name, as seen in the headers view
|
|
:help "Full name for mailing list" ;; tooltip
|
|
:function (lambda (msg)
|
|
(or (mu4e-message-field msg :mailing-list) "")))))
|
|
@end lisp
|
|
|
|
You can then add the custom header to your @code{mu4e-headers-fields},
|
|
just like the built-in headers. After evaluation, your headers-view
|
|
should include a new header @t{Recip#} with the number of recipients,
|
|
and/or @t{ML} with the full mailing-list name.
|
|
|
|
This function can be used in both the headers-view and the message-view;
|
|
if you need something specific for one of these, you can check for the
|
|
mode in your function, or create separate functions.
|
|
|
|
@node HV Actions
|
|
@section Actions
|
|
|
|
@code{mu4e-headers-action} (@key{a}) lets you pick custom actions to perform
|
|
on the message at point. You can specify these actions using the variable
|
|
@code{mu4e-headers-actions}. See @ref{Actions} for the details.
|
|
|
|
@t{mu4e} defines some default actions. One of those is for @emph{capturing} a
|
|
message: @key{a c} `captures' the current message. Next, when you're editing
|
|
some message, you can include the previously captured message as an
|
|
attachment, using @code{mu4e-compose-attach-captured-message}. See
|
|
@file{mu4e-actions.el} in the @t{mu4e} source distribution for more example
|
|
actions.
|
|
|
|
@node Split view
|
|
@section Split view
|
|
|
|
Using the @emph{Split view}, we can see the @ref{Headers view} and the
|
|
@ref{Message view} next to each other, with the message selected in the
|
|
former, visible in the latter. You can influence the way the splitting is done
|
|
by customizing the variable @code{mu4e-split-view}. Possible values are:
|
|
|
|
@itemize
|
|
@item @t{horizontal} (this is the default): display the message view below the
|
|
header view. Use @code{mu4e-headers-visible-lines} the set the number of lines
|
|
shown (default: 8).
|
|
@item @t{vertical}: display the message view on the
|
|
right side of the header view. Use @code{mu4e-headers-visible-columns} to set
|
|
the number of visible columns (default: 30).
|
|
@item @t{single-window}: single window mode. Single-window mode tries to
|
|
minimize mu4e window operations (opening, killing, resizing, etc) and buffer
|
|
changes, while still retaining the view and headers buffers. In addition, it
|
|
replaces mu4e main view with a minibuffer prompt containing the same
|
|
information.
|
|
@item anything else: don't do any splitting
|
|
@end itemize
|
|
|
|
@noindent
|
|
Some useful key bindings in the split view:
|
|
@itemize
|
|
@item @key{C-+} and @key{C--}: interactively change the number of columns or
|
|
headers shown
|
|
@item You can change the selected window from the
|
|
headers-view to the message-view and vice-versa with
|
|
@code{mu4e-select-other-view}, bound to @key{y}
|
|
@end itemize
|
|
|
|
@node Message view
|
|
@chapter The message view
|
|
|
|
After selecting a message in the @ref{Headers view}, it appears in a message
|
|
view window, which shows the message headers, followed by the message
|
|
body. Its major mode is @code{mu4e-view-mode}.
|
|
|
|
Note, the current message view is to be replaced by a new one, based on
|
|
Gnus' article-mode. It is available now as a 'tech preview', which you
|
|
can try by setting @code{mu4e-view-use-gnus} to @code{t} before starting
|
|
@code{mu4e}.
|
|
|
|
@menu
|
|
* Overview: MSGV Overview. What is the Message View
|
|
* Keybindings: MSGV Keybindings. Do things with your keyboard
|
|
* Attachments:: Opening and saving them
|
|
* Viewing images inline::Images display inside emacs
|
|
* Displaying rich-text messages::Dealing with HTML mail
|
|
* Verifying signatures and decryption: MSGV Crypto. Support for cryptography
|
|
* Custom headers: MSGV Custom headers. Your own headers
|
|
* Actions: MSGV Actions. Defining and using actions.
|
|
@end menu
|
|
|
|
@node MSGV Overview
|
|
@section Overview
|
|
|
|
An example message view:
|
|
|
|
@cartouche
|
|
@verbatim
|
|
From: randy@epiphyte.com
|
|
To: julia@eruditorum.org
|
|
Subject: Re: some pics
|
|
Flags: (seen attach)
|
|
Date: Mon 19 Jan 2004 09:39:42 AM EET
|
|
Maildir: /inbox
|
|
Attachments(2): [1]DSCN4961.JPG(1.3M), [2]DSCN4962.JPG(1.4M)
|
|
|
|
Hi Julia,
|
|
|
|
Some pics from our trip to Cerin Amroth. Enjoy!
|
|
|
|
All the best,
|
|
Randy.
|
|
|
|
On Sun 21 Dec 2003 09:06:34 PM EET, Julia wrote:
|
|
|
|
[....]
|
|
@end verbatim
|
|
@end cartouche
|
|
|
|
Some notes:
|
|
@itemize
|
|
@item The variable @code{mu4e-view-fields} determines the header fields to be
|
|
shown; see @code{mu4e-header-info} for a list of built-in fields. Apart from
|
|
the built-in fields, you can also create custom fields using
|
|
@code{mu4e-header-info-custom}; see @ref{MSGV Custom headers}.
|
|
@item You can set the date format with the variable
|
|
@code{mu4e-date-format-long}.
|
|
@item By default, only the names of contacts in address fields are visible
|
|
(see @code{mu4e-view-show-addresses} to change this). You can view the e-mail
|
|
addresses by clicking on the name, or pressing @key{M-RET}.
|
|
@item You can compose a message for the contact at point by either clicking
|
|
@key{[mouse-2]} or pressing @key{C}.
|
|
@item The body text can be line-wrapped using @t{visual-line-mode}. @t{mu4e}
|
|
defines @key{w} to toggle between the wrapped and unwrapped state. If you want
|
|
to do this automatically when viewing a message, invoke @code{visual-line-mode}
|
|
in your @code{mu4e-view-mode-hook}.
|
|
@item For messages that support it, you can toggle between html and text versions using
|
|
@code{mu4e-view-toggle-html}, bound to @key{h};
|
|
@item You can hide cited parts
|
|
in messages (the parts starting with ``@t{>}'') using
|
|
@code{mu4e-view-hide-cited}, bound to @key{#}. If you want to do this
|
|
automatically for every message, invoke the function in your
|
|
@code{mu4e-view-mode-hook}.
|
|
@item For search-related operations, see @ref{Searching}.
|
|
@item You can scroll down the message using @key{SPC}; if you do this at the
|
|
end of a message,it automatically takes you to the next one. If you want to
|
|
prevent this behavior, set @code{mu4e-view-scroll-to-next} to @code{nil}.
|
|
@end itemize
|
|
|
|
@node MSGV Keybindings
|
|
@section Keybindings
|
|
|
|
You can find most things you can do with this message in the @emph{View} menu,
|
|
or by using the keyboard; the default bindings are:
|
|
|
|
@verbatim
|
|
key description
|
|
==============================================================
|
|
n,p view the next, previous message
|
|
],[ move to the next, previous unread message
|
|
y select the headers view (if it's visible)
|
|
|
|
RET scroll down
|
|
M-RET open URL at point / attachment at point
|
|
|
|
SPC scroll down, if at end, move to next message
|
|
S-SPC scroll up
|
|
|
|
searching
|
|
---------
|
|
s search
|
|
e edit last query
|
|
/ narrow the search
|
|
b search bookmark
|
|
B edit bookmark before search
|
|
j jump to maildir
|
|
|
|
M-left previous query
|
|
M-right next query
|
|
|
|
marking
|
|
-------
|
|
d mark for moving to the trash folder
|
|
= mark for removing trash flag ('untrash')
|
|
DEL,D mark for complete deletion
|
|
m mark for moving to another maildir folder
|
|
r mark for refiling
|
|
+,- mark for flagging/unflagging
|
|
|
|
u unmark message at point
|
|
U unmark *all* messages
|
|
|
|
% mark based on a regular expression
|
|
T,t mark whole thread, subthread
|
|
|
|
<insert>,* mark for 'something' (decide later)
|
|
# resolve deferred 'something' marks
|
|
|
|
x execute actions for the marked messages
|
|
|
|
composition
|
|
-----------
|
|
R,F,C reply/forward/compose
|
|
E edit (only allowed for draft messages)
|
|
|
|
actions
|
|
-------
|
|
g go to (visit) numbered URL (using `browse-url')
|
|
(or: <mouse-1> or M-RET with point on url)
|
|
C-u g visits multiple URLs
|
|
f fetch (download )the numbered URL.
|
|
C-u f fetches multiple URLs
|
|
k save the numbered URL in the kill-ring.
|
|
C-u k saves multiple URLs
|
|
|
|
e extract (save) one or more attachments (asks for numbers)
|
|
(or: <mouse-2> or S-RET with point on attachment)
|
|
o open attachment (asks for number)
|
|
(or: <mouse-1> or M-RET with point on attachment)
|
|
|
|
a execute some custom action on the message
|
|
A execute some custom action on an attachment
|
|
|
|
misc
|
|
----
|
|
; switch context
|
|
c copy address at point (with C-u copy long version)
|
|
|
|
h toggle between html/text (if available)
|
|
w toggle line wrapping
|
|
# toggle show/hide cited parts
|
|
|
|
v show details about the cryptographic signature
|
|
|
|
. show the raw message view. 'q' takes you back.
|
|
C-+,C-- increase / decrease the number of headers shown
|
|
H get help
|
|
C-S-u update mail & reindex
|
|
q leave the message view
|
|
@end verbatim
|
|
|
|
For the marking commands, please refer to @ref{Marking messages}.
|
|
|
|
@node Attachments
|
|
@section Attachments
|
|
|
|
By default, @t{mu4e} uses the @t{xdg-open}-program
|
|
@footnote{@url{https://www.freedesktop.org/wiki/Software/xdg-utils/}} or (on
|
|
OS X) the @t{open} program for opening attachments. If you want to use another
|
|
program, you do so by setting the @t{MU_PLAY_PROGRAM} environment variable to
|
|
the program to be used.
|
|
|
|
The default directory for extracting (saving) attachments is your home
|
|
directory (@file{~/}); you can change this using the variable
|
|
@code{mu4e-attachment-dir}, for example:
|
|
|
|
@lisp
|
|
(setq mu4e-attachment-dir "~/Downloads")
|
|
@end lisp
|
|
|
|
For more flexibility, @code{mu4e-attachment-dir} can also be a user-provided
|
|
function. This function receives two parameters: the file-name and the
|
|
mime-type as found in the e-mail message@footnote{sadly, often
|
|
@t{application/octet-stream} is used for the mime-type, even if a better type
|
|
is available} of the attachment, either or both of which can be @t{nil}. For
|
|
example:
|
|
|
|
@lisp
|
|
(setq mu4e-attachment-dir
|
|
(lambda (fname mtype)
|
|
(cond
|
|
;; docfiles go to ~/Desktop
|
|
((and fname (string-match "\\.doc$" fname)) "~/Desktop")
|
|
;; ... other cases ...
|
|
(t "~/Downloads")))) ;; everything else
|
|
@end lisp
|
|
|
|
You can extract multiple attachments at once by prefixing the extracting
|
|
command by @key{C-u}; so @kbd{C-u e} asks you for a range of attachments to
|
|
extract (for example, @kbd{1 3-6 8}). The range "@samp{a}" is a shortcut for
|
|
@emph{all} attachments.
|
|
|
|
@node Viewing images inline
|
|
@section Viewing images inline
|
|
|
|
It is possible to show images inline in the message view buffer if you run
|
|
@command{emacs} in GUI-mode. You can enable this by setting the variable
|
|
@code{mu4e-view-show-images} to @t{t}. Since @command{emacs} does not always
|
|
handle images correctly, this is not enabled by default. If you are using
|
|
@command{emacs} 24 with
|
|
@emph{ImageMagick}@footnote{@url{http://www.imagemagick.org/}} support, make
|
|
sure you call @code{imagemagick-register-types} in your configuration, so it
|
|
is used for images.
|
|
|
|
@lisp
|
|
;; enable inline images
|
|
(setq mu4e-view-show-images t)
|
|
;; use imagemagick, if available
|
|
(when (fboundp 'imagemagick-register-types)
|
|
(imagemagick-register-types))
|
|
@end lisp
|
|
|
|
@node Displaying rich-text messages
|
|
@section Displaying rich-text messages
|
|
|
|
@t{mu4e} normally prefers the plain-text version for messages that
|
|
consist of both a plain-text and html (rich-text) versions of the
|
|
body-text. You can change this by setting @code{mu4e-view-prefer-html}
|
|
to @t{t}. And you can toggle this value (globally) using @kbd{h} in the
|
|
message view; this also refreshes the message with the new setting.
|
|
|
|
Note, when using html-based rendering, you don't get the hyperlink
|
|
shortcuts the text-version provides.
|
|
|
|
If there is only an html-version, or if the plain-text version is too
|
|
short in comparison with the html part@footnote{this is e.g. for the
|
|
case where the text-part is only a short blurb telling you to use the
|
|
html-version; see @code{mu4e-view-html-plaintext-ratio-heuristic}},
|
|
@t{mu4e} tries to convert the html into plain-text for display.
|
|
|
|
With emacs 24.4 or newer, this defaults to @code{mu4e-shr2text}, which
|
|
uses the built-in @t{shr} renderer. For older emacs versions, this
|
|
defaults to the built-in @code{html2text} function. In practice, the
|
|
latter gives much better results.
|
|
|
|
If you use @code{mu4e-shr2text}, it might be useful to emulate some of
|
|
the @t{shr} key bindings, with something like:
|
|
@lisp
|
|
(add-hook 'mu4e-view-mode-hook
|
|
(lambda()
|
|
;; try to emulate some of the eww key-bindings
|
|
(local-set-key (kbd "<tab>") 'shr-next-link)
|
|
(local-set-key (kbd "<backtab>") 'shr-previous-link)))
|
|
@end lisp
|
|
|
|
If you're using a dark theme, and the messages are hard to read, it can
|
|
help to change the luminosity, e.g.:
|
|
@lisp
|
|
(setq shr-color-visible-luminance-min 80)
|
|
@end lisp
|
|
|
|
If your emacs does not have @t{shr} yet, it can be useful to use a
|
|
custom method. For that, you can set the variable
|
|
@code{mu4e-html2text-command} to either a shell command or a function
|
|
instead.
|
|
|
|
@subsection Html2text commands
|
|
|
|
If @code{mu4e-html2text-command} is a shell command, it is expected to
|
|
take html from standard input and write plain text in @t{UTF-8} encoding
|
|
on standard output.
|
|
|
|
An example of such a program is the program that is actually
|
|
@emph{called}
|
|
@t{html2text}@footnote{@url{http://www.mbayer.de/html2text/}}. After
|
|
installation, you can set it up with something like the following:
|
|
|
|
@lisp
|
|
(setq mu4e-html2text-command "html2text -utf8 -width 72")
|
|
@end lisp
|
|
|
|
An alternative to this is the Python @t{python-html2text} package; after
|
|
installing that, you can tell @t{mu4e} to use it with something like:
|
|
|
|
@lisp
|
|
(setq mu4e-html2text-command
|
|
"html2markdown | grep -v ' _place_holder;'")
|
|
@end lisp
|
|
|
|
On OS X, there is a program called @t{textutil} as yet another
|
|
alternative:
|
|
|
|
@lisp
|
|
(setq mu4e-html2text-command
|
|
"textutil -stdin -format html -convert txt -stdout")
|
|
@end lisp
|
|
|
|
@subsection Html2text functions
|
|
@anchor{Html2text functions}
|
|
|
|
If @code{mu4e-html2text-command} refers to an elisp function, the
|
|
function is expected to take a message plist as its input, and returns
|
|
the transformed data.
|
|
|
|
|
|
You can easily create your own function, for instance:
|
|
|
|
@lisp
|
|
(defun my-mu4e-html2text (msg)
|
|
"My html2text function; shows short message inline, show
|
|
long messages in some external browser (see `browse-url-generic-program')."
|
|
(let ((html (or (mu4e-message-field msg :body-html) "")))
|
|
(if (> (length html) 20000)
|
|
(progn
|
|
(mu4e-action-view-in-browser msg)
|
|
"[Viewing message in external browser]")
|
|
(mu4e-shr2text msg))))
|
|
|
|
(setq mu4e-html2text-command 'my-mu4e-html2text)
|
|
@end lisp
|
|
|
|
@subsection Privacy aspects
|
|
@anchor{Privacy aspects}
|
|
|
|
When opening your messages in a graphical browser, it may expose you
|
|
doing so to the sender, due to the presence of specially crafted image
|
|
URLs, or Javascript.
|
|
|
|
If that is an issue, it is recommended to use a browser (or browser
|
|
profile) that does not load images. The same applies to Javascript.
|
|
|
|
|
|
@node MSGV Crypto
|
|
@section Crypto
|
|
|
|
The @t{mu4e} message view supports@footnote{Crypto-support in @t{mu4e}
|
|
requires @t{mu} to have been build with crypto-support; see the
|
|
@ref{FAQ}} decryption of encrypted messages, as well as verification of
|
|
signatures. For signing/encrypting messages your outgoing messages, see
|
|
@ref{Signing and encrypting}.
|
|
|
|
Currently, only PGP/MIME is supported; PGP-inline and S/MIME are not.
|
|
|
|
For all of this to work, @command{gpg-agent} must be running, and it
|
|
must set the environment variable @t{GPG_AGENT_INFO}. You can check from
|
|
@command{emacs} with @key{M-x getenv GPG_AGENT_INFO}.
|
|
|
|
In many mainstream Linux/Unix desktop environments, everything works
|
|
out-of-the-box, but if your environment does not automatically start
|
|
@command{gpg-agent}, you can do so by hand:
|
|
@verbatim
|
|
$ eval $(gpg-agent --daemon)
|
|
@end verbatim
|
|
|
|
@noindent
|
|
This starts the daemon, and sets the environment variable.
|
|
|
|
@subsection Decryption
|
|
@anchor{Decryption}
|
|
|
|
If you receive messages that are encrypted (using PGP/MIME), @t{mu4e}
|
|
can try to decrypt them, base on the setting of
|
|
@code{mu4e-decryption-policy}. If you set it to @t{t}, @t{mu4e} attempts
|
|
to decrypt messages automatically; this is the default. If you set it to
|
|
@t{nil}, @t{mu4e} @emph{won't} attempt to decrypt anything. Finally, if
|
|
you set it to @t{'ask}, it asks you what to do, each time an encrypted
|
|
message is encountered.
|
|
|
|
When opening an encrypted message, @t{mu} consults @t{gpg-agent} to see
|
|
if it already has unlocked the key needed to decrypt the message; if
|
|
not, it prompts you for a password (typically with a separate top-level
|
|
window). This is only needed once per session.
|
|
|
|
@subsection Verifying signatures
|
|
@anchor{Verifying signatures}
|
|
|
|
Some e-mail messages are cryptographically signed, and @t{mu4e} can
|
|
check the validity of these signatures. If a message has one or more
|
|
signatures, the message view shows an extra header @t{Signature:}
|
|
(assuming it is part of your @code{mu4e-view-fields}), and one or more
|
|
`verdicts' of the signatures found; either @t{verified}, @t{unverified}
|
|
or @t{error}. For instance:
|
|
|
|
@verbatim
|
|
Signature: unverified (Details)
|
|
@end verbatim
|
|
or
|
|
@verbatim
|
|
Signature: verified Darrow Andromedus <darrow@rising.com> (Details)
|
|
@end verbatim
|
|
|
|
You can see the details of the signature verification by activating the
|
|
@t{Details} or pressing @key{v}. This pops up a little window with the
|
|
details of the signatures found and whether they could be verified or
|
|
not.
|
|
|
|
Note that @t{mu4e} does not check whether the signer is the same as the
|
|
sender of the message, since this would cause too many false negatives
|
|
for senders that use an address that is not part of their certificate.
|
|
Also, the From: address can easily be forged.
|
|
|
|
For more information, see the @command{mu-verify} manual page.
|
|
|
|
@node MSGV Custom headers
|
|
@section Custom headers
|
|
|
|
Sometimes the normal headers that @t{mu4e} offers (Date, From, To, Subject
|
|
etc.) may not be enough. For these cases, @t{mu4e} offers @emph{custom
|
|
headers} in both the headers-view and the message-view.
|
|
|
|
See @ref{HV Custom headers} for an example of this; the difference for the
|
|
message-view is that you should add your custom header to
|
|
@code{mu4e-view-fields} rather than @code{mu4e-headers-fields}.
|
|
|
|
@node MSGV Actions
|
|
@section Actions
|
|
|
|
You can perform custom functions (``actions'') on messages and their
|
|
attachments. For a general discussion on how to define your own, see
|
|
@ref{Actions}.
|
|
|
|
@subsection Message actions
|
|
@code{mu4e-view-action} (@key{a}) lets you pick some custom action to perform
|
|
on the current message. You can specify these actions using the variable
|
|
@code{mu4e-view-actions}; @t{mu4e} defines a number of example actions.
|
|
|
|
@subsection Attachment actions
|
|
Similarly, there is @code{mu4e-view-attachment-action} (@key{A}) for actions
|
|
on attachments, which you can specify with
|
|
@code{mu4e-view-attachment-actions}.
|
|
|
|
@t{mu4e} predefines a number of attachment-actions:
|
|
@itemize
|
|
@item @t{open-with} (@key{w}): open the attachment with some arbitrary
|
|
program. For example, suppose you have received a message with a picture
|
|
attachment; then, @kbd{A w 1 RET gimp RET} opens that attachment in @emph{The
|
|
Gimp}
|
|
@item @t{pipe} (@key{|}: process the attachment with some Unix shell-pipe and
|
|
see the results. Suppose you receive a patch file, and would like to get an
|
|
overview of the changes, using the @t{diffstat} program. You can use something
|
|
like: @kbd{A | 1 RET diffstat -b RET}.
|
|
@item @command{emacs} (@key{e}): open the attachment in your running @command{emacs}. For
|
|
example, if you receive some text file you'd like to open in @command{emacs}:
|
|
@kbd{A e 1 RET}.
|
|
@end itemize
|
|
|
|
These actions all work on a @emph{temporary copy} of the attachment.
|
|
|
|
@node Editor view
|
|
@chapter The editor view
|
|
|
|
Writing e-mail messages takes place in the Editor View. @t{mu4e}'s editor view
|
|
builds on top of Gnus' @t{message-mode}. Most of the @t{message-mode}
|
|
functionality is available, as well some @t{mu4e}-specifics. Its major mode is
|
|
@code{mu4e-compose-mode}.
|
|
|
|
@menu
|
|
* Overview: EV Overview. What is the Editor view
|
|
* Keybindings: EV Keybindings. Doing things with your keyboard
|
|
* Address autocompletion:: Quickly entering known addresses
|
|
* Compose hooks::Calling functions when composing
|
|
* Signing and encrypting:: Support for cryptography
|
|
* Queuing mail:: Sending mail when the time is ripe
|
|
* Message signatures:: Adding your personal footer to messages
|
|
* Other settings::Miscellanea
|
|
@end menu
|
|
|
|
@node EV Overview
|
|
@section Overview
|
|
|
|
@cartouche
|
|
@verbatim
|
|
From: Rupert the Monkey <rupert@example.com>
|
|
To: Wally the Walrus <wally@example.com>
|
|
Subject: Re: Eau-qui d'eau qui?
|
|
--text follows this line--
|
|
|
|
On Mon 16 Jan 2012 10:18:47 AM EET, Wally the Walrus wrote:
|
|
|
|
> Hi Rupert,
|
|
>
|
|
> Dude - how are things?
|
|
>
|
|
> Later -- wally.
|
|
@end verbatim
|
|
@end cartouche
|
|
|
|
|
|
@node EV Keybindings
|
|
@section Keybindings
|
|
|
|
@t{mu4e}'s editor view derives from Gnus' message editor and shares most of
|
|
its keybindings. Here are some of the more useful ones (you can use the menu
|
|
to find more):
|
|
|
|
@verbatim
|
|
key description
|
|
--- -----------
|
|
C-c C-c send message
|
|
C-c C-d save to drafts and leave
|
|
C-c C-k kill the message buffer (the message remains in the draft folder)
|
|
C-c C-a attach a file (pro-tip: drag & drop works as well)
|
|
|
|
(mu4e-specific)
|
|
C-S-u update mail & reindex
|
|
@end verbatim
|
|
|
|
@node Address autocompletion
|
|
@section Address autocompletion
|
|
|
|
@t{mu4e} supports@footnote{@command{emacs} 23.2 or higher is required}
|
|
autocompleting addresses when composing e-mail messages. @t{mu4e} uses the
|
|
e-mail addresses from the messages you sent or received as the source for
|
|
this. Address auto-completion is enabled by default; if you want to disable it
|
|
for some reason, set @t{mu4e-compose-complete-addresses} to @t{nil}.
|
|
|
|
Emacs 24 also supports cycling through the alternatives. When there are more
|
|
than @emph{5} matching addresses, they are shown in a @t{*Completions*}
|
|
buffer. Once the number of matches gets below this number, one is inserted in
|
|
the address field and you can cycle through the alternatives using @key{TAB}.
|
|
|
|
@subsection Limiting the number of addresses
|
|
|
|
If you have a lot of mail, especially from mailing lists and the like, there
|
|
can be a @emph{lot} of e-mail addresses, many of which may not be very useful
|
|
when auto-completing. For this reason, @t{mu4e} attempts to limit the number
|
|
of e-mail addresses in the completion pool by filtering out the ones that are
|
|
not likely to be relevant. The following variables are available for tuning
|
|
this:
|
|
|
|
@itemize
|
|
@item @code{mu4e-compose-complete-only-personal} --- when set to @t{t},
|
|
only consider addresses that were seen in @emph{personal} messages --- that is,
|
|
messages in which one of my e-mail addresses was seen in one of the address
|
|
fields. This is to exclude mailing list posts. You can define what is
|
|
considered `my e-mail address' using @code{mu4e-user-mail-address-list}, a
|
|
list of e-mail address (defaults to @code{user-mail-address}, and when
|
|
indexing from the command line, the @t{--my-address} parameter for @t{mu
|
|
index}.
|
|
@item @code{mu4e-compose-complete-only-after} --- only consider e-mail
|
|
addresses last seen after some date. Parameter is a string, parseable by
|
|
@code{org-parse-time-string}. This excludes old e-mail addresses. The default
|
|
is @t{"2010-01-01"}, i.e., only consider e-mail addresses seen since the start
|
|
of 2010.
|
|
@item @code{mu4e-compose-complete-ignore-address-regexp} --- a regular expression to
|
|
filter out other `junk' e-mail addresses; defaults to ``@t{no-?reply}''.
|
|
@end itemize
|
|
|
|
@node Compose hooks
|
|
@section Compose hooks
|
|
|
|
If you want to change some setting, or execute some custom action before
|
|
message composition starts, you can define a @emph{hook function}. @t{mu4e}
|
|
offers two hooks:
|
|
@itemize
|
|
@item @code{mu4e-compose-pre-hook}: this hook is run @emph{before} composition
|
|
starts; if you are composing a @emph{reply}, @emph{forward} a message, or
|
|
@emph{edit} an existing message, the variable
|
|
@code{mu4e-compose-parent-message} points to the message being replied to,
|
|
forwarded or edited, and you can use @code{mu4e-message-field} to get the
|
|
value of various properties (and see @ref{Message functions}).
|
|
@item @code{mu4e-compose-mode-hook}: this hook is run just before composition
|
|
starts, when the whole buffer has already been set up. This is a good place
|
|
for editing-related settings. @code{mu4e-compose-parent-message} (see above)
|
|
is also at your disposal.
|
|
@end itemize
|
|
|
|
@noindent
|
|
Let's look at some examples. First, suppose we want to set the
|
|
@t{From:}-address for a reply message based on the receiver of the original:
|
|
@lisp
|
|
;; 1) messages to me@@foo.example.com should be replied with From:me@@foo.example.com
|
|
;; 2) messages to me@@bar.example.com should be replied with From:me@@bar.example.com
|
|
;; 3) all other mail should use From:me@@cuux.example.com
|
|
(add-hook 'mu4e-compose-pre-hook
|
|
(defun my-set-from-address ()
|
|
"Set the From address based on the To address of the original."
|
|
(let ((msg mu4e-compose-parent-message)) ;; msg is shorter...
|
|
(when msg
|
|
(setq user-mail-address
|
|
(cond
|
|
((mu4e-message-contact-field-matches msg :to "me@@foo.example.com")
|
|
"me@@foo.example.com")
|
|
((mu4e-message-contact-field-matches msg :to "me@@bar.example.com")
|
|
"me@@bar.example.com")
|
|
(t "me@@cuux.example.com")))))))
|
|
@end lisp
|
|
|
|
Secondly, as mentioned, @code{mu4e-compose-mode-hook} is especially
|
|
useful for editing-related settings. For example:
|
|
@lisp
|
|
(add-hook 'mu4e-compose-mode-hook
|
|
(defun my-do-compose-stuff ()
|
|
"My settings for message composition."
|
|
(set-fill-column 72)
|
|
(flyspell-mode)))
|
|
@end lisp
|
|
|
|
This hook is also useful for adding headers or changing headers, since the
|
|
message is fully formed when this hook runs. For example, to add a
|
|
@t{Bcc:}-header, you could add something like the following, using
|
|
@code{message-add-header} from @code{message-mode}.
|
|
|
|
@lisp
|
|
(add-hook 'mu4e-compose-mode-hook
|
|
(defun my-add-bcc ()
|
|
"Add a Bcc: header."
|
|
(save-excursion (message-add-header "Bcc: me@@example.com\n"))))
|
|
@end lisp
|
|
|
|
Or to something context-specific:
|
|
|
|
@lisp
|
|
(add-hook 'mu4e-compose-mode-hook
|
|
(lambda()
|
|
(let* ((ctx (mu4e-context-current))
|
|
(name (if ctx (mu4e-context-name ctx))))
|
|
(when name
|
|
(cond
|
|
((string= name "account1")
|
|
(save-excursion (message-add-header "Bcc: account1@@example.com\n")))
|
|
((string= name "account2")
|
|
(save-excursion (message-add-header "Bcc: account2@@example.com\n"))))))))
|
|
@end lisp
|
|
|
|
@noindent
|
|
For a more general discussion about extending @t{mu4e}, see @ref{Extending
|
|
mu4e}.
|
|
|
|
@node Signing and encrypting
|
|
@section Signing and encrypting
|
|
|
|
Signing and encrypting of messages is possible using @t{emacs-mime}
|
|
(@inforef{Composing,,emacs-mime}), most easily accessed through the
|
|
@t{Attachments}-menu while composing a message, or with @kbd{M-x
|
|
mml-secure-message-encrypt-pgp}, @kbd{M-x mml-secure-message-sign-pgp}.
|
|
|
|
The support for encryption and signing is @emph{independent} of the support
|
|
for their counterparts, decrypting and signature verification (as discussed in
|
|
@ref{MSGV Crypto}). Even if your @t{mu4e} does not have support for the latter
|
|
two, you can still sign/encrypt messages.
|
|
|
|
Currently, decryption and signature verification only works for PGP/MIME;
|
|
inline-PGP and S/MIME are not supported.
|
|
|
|
Important note: the messages are encrypted when they are @emph{sent}:
|
|
this means that draft messages are @emph{not} encrypted. So if you are
|
|
using e.g. @t{offlineimap} or @t{mbsync} to synchronize with some remote
|
|
IMAP-service, make sure the drafts folder is @emph{not} in the set of
|
|
synchronized folders, for obvious reasons.
|
|
|
|
@node Queuing mail
|
|
@section Queuing mail
|
|
|
|
If you cannot send mail right now, for example because you are currently
|
|
offline, you can @emph{queue} the mail, and send it when you have restored
|
|
your internet connection. You can control this from the @ref{Main view}.
|
|
|
|
To allow for queuing, you need to tell @t{smtpmail} where you want to store
|
|
the queued messages. For example:
|
|
|
|
@lisp
|
|
(setq smtpmail-queue-mail t ;; start in queuing mode
|
|
smtpmail-queue-dir "~/Maildir/queue/cur")
|
|
@end lisp
|
|
|
|
For convenience, we put the queue directory somewhere in our normal
|
|
maildir. If you want to use queued mail, you should create this directory
|
|
before starting @t{mu4e}. The @command{mu mkdir} command may be useful here,
|
|
so for example:
|
|
|
|
@verbatim
|
|
$ mu mkdir ~/Maildir/queue
|
|
$ touch ~/Maildir/queue/.noindex
|
|
@end verbatim
|
|
|
|
The file created by the @command{touch} command tells @t{mu} to ignore this
|
|
directory for indexing, which makes sense since it contains @t{smtpmail}
|
|
meta-data rather than normal messages; see the @t{mu-mkdir} and @t{mu-index}
|
|
man-pages for details.
|
|
|
|
@emph{Warning}: when you switch on queued-mode, your messages @emph{won't}
|
|
reach their destination until you switch it off again; so, be careful not to
|
|
do this accidentally!
|
|
|
|
@node Message signatures
|
|
@section Message signatures
|
|
|
|
Message signatures are the standard footer blobs in e-mail messages where you
|
|
can put in information you want to include in every message. The text to
|
|
include is set with @code{mu4e-compose-signature}.
|
|
|
|
If you don't want to include this automatically with each message,
|
|
you can set @code{mu4e-compose-signature-auto-include} to @code{nil}; you can
|
|
then still include the signature manually, using the function
|
|
@code{message-insert-signature}, typically bound to @kbd{C-c C-w}.
|
|
|
|
@node Other settings
|
|
@section Other settings
|
|
|
|
@itemize
|
|
@item If you want use @t{mu4e} as @command{emacs}' default program for sending mail,
|
|
see @ref{Emacs default}.
|
|
@item Normally, @t{mu4e} @emph{buries} the message buffer after sending; if you want
|
|
to kill the buffer instead, add something like the following to your
|
|
configuration:
|
|
@lisp
|
|
(setq message-kill-buffer-on-exit t)
|
|
@end lisp
|
|
@item If you want to exclude your own e-mail address when ``replying to
|
|
all'', set @code{mu4e-compose-dont-reply-to-self} to @code{t}. In order
|
|
for this to work properly you need to properly set the
|
|
@code{user-mail-address} variable or in the case you use multiple e-mail
|
|
addresses you need to set the @code{mu4e-user-mail-address-list}
|
|
variable accordingly.
|
|
@end itemize
|
|
|
|
@node Searching
|
|
@chapter Searching
|
|
|
|
@t{mu4e} is fully search-based: even if you `jump to a folder', you are
|
|
executing a query for messages that happen to have the property of being in a
|
|
certain folder (maildir).
|
|
|
|
Normally, queries return up to @code{mu4e-headers-results-limit} (default:
|
|
500) results. That is usually more than enough, and makes things significantly
|
|
faster. Sometimes, however, you may want to show @emph{all} results; you can
|
|
enable this with @kbd{M-x mu4e-headers-toggle-full-search}, or by customizing
|
|
the variable @code{mu4e-headers-full-search}. This applies to all search
|
|
commands.
|
|
|
|
You can also influence the sort order and whether threads are shown or not;
|
|
see @ref{Sorting and threading}.
|
|
|
|
@menu
|
|
* Queries:: Searching for messages.
|
|
* Bookmarks:: Remembering queries.
|
|
* Maildir searches:: Queries for maildirs.
|
|
* Other search functionality:: Some more tricks.
|
|
@end menu
|
|
|
|
@node Queries
|
|
@section Queries
|
|
|
|
@t{mu4e} queries are the same as the ones that @t{mu find}
|
|
understands@footnote{with the caveat that command-line queries are
|
|
subject to the shell's interpretation before @t{mu} sees them}. Let's
|
|
look at some examples here; you can consult the @code{mu-query} man page
|
|
for the details.
|
|
|
|
@itemize
|
|
|
|
@item Get all messages regarding @emph{bananas}:
|
|
@verbatim
|
|
bananas
|
|
@end verbatim
|
|
|
|
@item Get all messages regarding @emph{bananas} from @emph{John} with an attachment:
|
|
@verbatim
|
|
from:john and flag:attach and bananas
|
|
@end verbatim
|
|
|
|
@item Get all messages with subject @emph{wombat} in June 2017
|
|
@verbatim
|
|
subject:wombat and date:20170601..20170630
|
|
@end verbatim
|
|
|
|
@item Get all messages with PDF attachments in the @t{/projects} folder
|
|
@verbatim
|
|
maildir:/projects and mime:application/pdf
|
|
@end verbatim
|
|
|
|
@item Get all messages about @emph{Rupert} in the @t{/Sent Items} folder. Note that
|
|
maildirs with spaces must be quoted.
|
|
@verbatim
|
|
"maildir:/Sent Items" and rupert
|
|
@end verbatim
|
|
|
|
@item Get all important messages which are signed:
|
|
@verbatim
|
|
flag:signed and prio:high
|
|
@end verbatim
|
|
|
|
@item Get all messages from @emph{Jim} without an attachment:
|
|
@verbatim
|
|
from:jim and not flag:attach
|
|
@end verbatim
|
|
|
|
@item Get all messages with Alice in one of the contacts-fields (@t{to}, @t{from},
|
|
@t{cc}, @t{bcc}):
|
|
@verbatim
|
|
contact:alice
|
|
@end verbatim
|
|
|
|
@item Get all unread messages where the subject mentions Ångström: (search is
|
|
case-insensitive and accent-insensitive, so this matches Ångström, angstrom,
|
|
aNGstrøM, ...)
|
|
@verbatim
|
|
subject:Ångström and flag:unread
|
|
@end verbatim
|
|
|
|
@item Get all unread messages between Mar-2012 and Aug-2013 about some bird:
|
|
@verbatim
|
|
date:20120301..20130831 and nightingale and flag:unread
|
|
@end verbatim
|
|
|
|
@item Get today's messages:
|
|
@verbatim
|
|
date:today..now
|
|
@end verbatim
|
|
|
|
@item Get all messages we got in the last two weeks regarding @emph{emacs}:
|
|
@verbatim
|
|
date:2w.. and emacs
|
|
@end verbatim
|
|
|
|
@item Get messages from the @emph{Mu} mailing list:
|
|
@verbatim
|
|
list:mu-discuss.googlegroups.com
|
|
@end verbatim
|
|
|
|
Note --- in the @ref{Headers view} you may see the `friendly name' for a
|
|
list; however, when searching you need the real name. You can see the
|
|
real name for a mailing list from the friendly name's tool-tip.
|
|
|
|
@item Get messages with a subject soccer, Socrates, society, ...; note that
|
|
the `*'-wildcard can only appear as a term's rightmost character:
|
|
@verbatim
|
|
subject:soc*
|
|
@end verbatim
|
|
|
|
@item Get all messages @emph{not} sent to a mailing-list:
|
|
@verbatim
|
|
NOT flag:list
|
|
@end verbatim
|
|
|
|
@item Get all mails with attachments with filenames starting with @emph{pic}; note
|
|
that the `*' wildcard can only appear as the term's rightmost character:
|
|
@verbatim
|
|
file:pic*
|
|
@end verbatim
|
|
|
|
@item Get all messages with PDF-attachments:
|
|
@verbatim
|
|
mime:application/pdf
|
|
@end verbatim
|
|
|
|
Get all messages with image attachments, and note that the `*' wildcard can
|
|
only appear as the term's rightmost character:
|
|
@verbatim
|
|
mime:image/*
|
|
@end verbatim
|
|
|
|
@end itemize
|
|
|
|
@node Bookmarks
|
|
@section Bookmarks
|
|
|
|
If you have queries that you use often, you may want to store them as
|
|
@emph{bookmarks}. Bookmark searches are available in the main view
|
|
(@pxref{Main view}), header view (@pxref{Headers view}), and message
|
|
view (@pxref{Message view}), using (by default) the key @key{b}
|
|
(@kbd{M-x mu4e-search-bookmark}), or @key{B} (@kbd{M-x
|
|
mu4e-search-bookmark-edit}) which lets you edit the bookmark first.
|
|
|
|
@subsection Setting up bookmarks
|
|
|
|
@t{mu4e} provides a number of default bookmarks. Their definition may
|
|
be instructive:
|
|
|
|
@lisp
|
|
(defcustom mu4e-bookmarks
|
|
'(( :name "Unread messages"
|
|
:query "flag:unread AND NOT flag:trashed"
|
|
:key ?u)
|
|
( :name "Today's messages"
|
|
:query "date:today..now"
|
|
:key ?t)
|
|
( :name "Last 7 days"
|
|
:query "date:7d..now"
|
|
:show-unread t
|
|
:key ?w)
|
|
( :name "Messages with images"
|
|
:query "mime:image/*"
|
|
:key ?p))
|
|
"List of pre-defined queries that are shown on the main screen.
|
|
|
|
Each of the list elements is a plist with at least:
|
|
:name - the name of the queryt
|
|
:query - the query expression
|
|
:key - the shortcut key.
|
|
|
|
Optionally, you add the following:
|
|
:hide - if t, bookmark is hdden from the main-view and speedbar.
|
|
:hide-unread - do not show the counts of unread/total number
|
|
of matches for the query. This can be useful if a bookmark uses
|
|
a very slow query. :hide-unread is implied from :hide.
|
|
"
|
|
:type '(repeat (plist))
|
|
:group 'mu4e)
|
|
@end lisp
|
|
|
|
You can replace these or add your own items, by putting in your
|
|
configuration (@file{~/.emacs}) something like:
|
|
@lisp
|
|
(add-to-list 'mu4e-bookmarks
|
|
'( :name "Big messages"
|
|
:query "size:5M..500M"
|
|
:key ?b))
|
|
@end lisp
|
|
|
|
This prepends your bookmark to the list, and assigns the key @key{b} to it. If
|
|
you want to @emph{append} your bookmark, you can use @code{t} as the third
|
|
argument to @code{add-to-list}.
|
|
|
|
In the various @t{mu4e} views, pressing @key{b} lists all the bookmarks
|
|
defined in the echo area, with the shortcut key highlighted. So, to invoke the
|
|
bookmark we just defined (to get the list of "Big Messages"), all you need to
|
|
type is @kbd{bb}.
|
|
|
|
@subsection Lisp expressions or functions as bookmarks
|
|
|
|
Instead of using strings, it is also possible to use Lisp expressions as
|
|
bookmarks. Either the expression evaluates to a query string or the expression
|
|
is a function taking no argument that returns a query string.
|
|
|
|
For example, to get all the messages that are at most a week old in your
|
|
inbox:
|
|
|
|
@lisp
|
|
(add-to-list 'mu4e-bookmarks
|
|
'( :name "Inbox messages in the last 7 days"
|
|
:query (lambda () (concat "maildir:/inbox AND date:"
|
|
(format-time-string "%Y%m%d"
|
|
(subtract-time (current-time) (days-to-time 7)))))
|
|
:key ?w) t)
|
|
@end lisp
|
|
|
|
Another example where the user is prompted how many days old messages should be
|
|
shown:
|
|
|
|
@lisp
|
|
(defun my/mu4e-bookmark-num-days-old-query (days-old)
|
|
(interactive (list (read-number "Show days old messages: " 7)))
|
|
(let ((start-date (subtract-time (current-time) (days-to-time days-old))))
|
|
(concat "maildir:/inbox AND date:"
|
|
(format-time-string "%Y%m%d" start-date))))
|
|
|
|
(add-to-list 'mu4e-bookmarks
|
|
`(:name "Inbox messages in the last 7 days"
|
|
:query ,(lambda () (call-interactively 'my/mu4e-bookmark-num-days-old-query))
|
|
:key ?o) t)
|
|
@end lisp
|
|
|
|
It is defining a function to make the code more readable.
|
|
|
|
@subsection Editing bookmarks before searching
|
|
|
|
There is also @kbd{M-x mu4e-headers-search-bookmark-edit} (key @key{B}), which
|
|
lets you edit the bookmarked query before invoking it. This can be useful if
|
|
you have many similar queries, but need to change some parameter. For example,
|
|
you could have a bookmark @samp{"date:today..now AND "}@footnote{Not a valid
|
|
search query by itself}, which limits any result to today's messages.
|
|
|
|
@node Maildir searches
|
|
@section Maildir searches
|
|
|
|
Maildir searches are quite similar to bookmark searches (see @ref{Bookmarks}),
|
|
with the difference being that the target is always a maildir --- maildir
|
|
queries provide a `traditional' folder-like interface to a search-based e-mail
|
|
client. By default, maildir searches are available in the @ref{Main view},
|
|
@ref{Headers view}, and @ref{Message view}, with the key @key{j}
|
|
(@code{mu4e-jump-to-maildir}).
|
|
|
|
@subsection Setting up maildir shortcuts
|
|
|
|
You can search for maildirs like any other message property
|
|
(e.g. with a query like @t{maildir:/myfolder}), but since it is so common,
|
|
@t{mu4e} offers a shortcut for this.
|
|
|
|
For this to work, you need to set the variable @code{mu4e-maildir-shortcuts}
|
|
to the list of maildirs you want to have quick access to, for example:
|
|
|
|
@lisp
|
|
(setq mu4e-maildir-shortcuts
|
|
'( ("/inbox" . ?i)
|
|
("/archive" . ?a)
|
|
("/lists" . ?l)
|
|
("/work" . ?w)
|
|
("/sent" . ?s)))
|
|
@end lisp
|
|
|
|
This sets @key{i} as a shortcut for the @t{/inbox} folder --- effectively a
|
|
query @t{maildir:/inbox}. There is a special shortcut @key{o} or @key{/} for
|
|
@emph{other} (so don't use those for your own shortcuts!), which allows you to
|
|
choose from @emph{all} maildirs that you have. There is support for
|
|
autocompletion; note that the list of maildirs is determined when @t{mu4e}
|
|
starts; if there are changes in the maildirs while @t{mu4e} is running, you
|
|
need to restart @t{mu4e}.
|
|
|
|
Each of the folder names is relative to your top-level maildir directory; so
|
|
if you keep your mail in @file{~/Maildir}, @file{/inbox} would refer to
|
|
@file{~/Maildir/inbox}. With these shortcuts, you can jump around your
|
|
maildirs (folders) very quickly --- for example, getting to the @t{/lists}
|
|
folder only requires you to type @kbd{jl}, then change to @t{/work} with
|
|
@kbd{jw}.
|
|
|
|
While in queries you need to quote folder names (maildirs) with spaces in
|
|
them, you should @emph{not} quote them when used in
|
|
@code{mu4e-maildir-shortcuts}, since @t{mu4e} does that automatically for you.
|
|
|
|
The very same shortcuts are used by @kbd{M-x mu4e-mark-for-move} (default
|
|
shortcut @key{m}); so, for example, if you want to move a message to the
|
|
@t{/archive} folder, you can do so by typing @kbd{ma}.
|
|
|
|
@node Other search functionality
|
|
@section Other search functionality
|
|
|
|
@subsection Navigating through search queries
|
|
You can navigate through previous/next queries using
|
|
@code{mu4e-headers-query-prev} and @code{mu4e-headers-query-next}, which are
|
|
bound to @key{M-left} and @key{M-right}, similar to what some web browsers do.
|
|
|
|
@t{mu4e} tries to be smart and not record duplicate queries. Also, the number
|
|
of queries remembered has a fixed limit, so @t{mu4e} won't use too much
|
|
memory, even if used for a long time. However, if you want to forget
|
|
previous/next queries, you can use @kbd{M-x mu4e-headers-forget-queries}.
|
|
|
|
@subsection Narrowing search results
|
|
|
|
It can be useful to narrow existing search results, that is, to add some
|
|
clauses to the current query to match fewer messages.
|
|
|
|
For example, suppose you're looking at some mailing list, perhaps by
|
|
jumping to a maildir (@kbd{M-x mu4e-headers-jump-to-maildir}, @key{j}) or
|
|
because you followed some bookmark (@kbd{M-x mu4e-headers-search-bookmark},
|
|
@key{b}). Now, you want to narrow things down to only those messages that have
|
|
attachments.
|
|
|
|
This is when @kbd{M-x mu4e-headers-search-narrow} (@key{/}) comes in handy. It
|
|
asks for an additional search pattern, which is appended to the current search
|
|
query, in effect getting you the subset of the currently shown headers that
|
|
also match this extra search pattern. @key{\} takes you back to the previous
|
|
query, so, effectively `widens' the search. Technically, narrowing the results
|
|
of query @t{x} with expression @t{y} implies doing a search @t{(x) AND (y)}.
|
|
|
|
Note that messages that were not in your original search results because
|
|
of @code{mu4e-headers-results-limit} may show up in the narrowed query.
|
|
|
|
@subsection Including related messages
|
|
@anchor{Including related messages}
|
|
|
|
It can be useful to not only show the messages that directly match a certain
|
|
query, but also include messages that are related to these messages. That is,
|
|
messages that belong to the same discussion threads are included in the
|
|
results, just like e.g. Gmail does it. You can enable this behavior by setting
|
|
@code{mu4e-headers-include-related} to @code{t}, and you can toggle between
|
|
including/not-including with @key{W}.
|
|
|
|
Be careful though when e.g. deleting ranges of messages from a certain
|
|
folder --- the list may now also include messages from @emph{other}
|
|
folders.
|
|
|
|
@subsection Skipping duplicates
|
|
@anchor{Skipping duplicates}
|
|
|
|
Another useful feature is skipping of @emph{duplicate messages}. When you have
|
|
copies of messages, there's usually little value in including more than one in
|
|
search results. A common reason for having multiple copies of messages is the
|
|
combination of Gmail and @t{offlineimap}, since that is the way the labels /
|
|
virtual folders in Gmail are represented. You can enable skipping duplicates
|
|
by setting @code{mu4e-headers-skip-duplicates} to @code{t}, and you can toggle
|
|
between the skipping/not skipping with @key{V}.
|
|
|
|
Note, messages are considered duplicates when they have the same
|
|
@t{Message-Id}.
|
|
|
|
@node Marking
|
|
@chapter Marking
|
|
|
|
In @t{mu4e}, the common way to do things with messages is a two-step process -
|
|
first you @emph{mark} them for a certain action, then you @emph{execute}
|
|
(@key{x}) those marks. This is similar to the way @t{dired} operates. Marking
|
|
can happen in both the @ref{Headers view} and the @ref{Message view}.
|
|
|
|
@menu
|
|
* Marking messages::Selecting message do something with them
|
|
* What to mark for::What can we do with them
|
|
* Executing the marks::Do it
|
|
* Trashing messages::Exceptions for mailboxes like Gmail
|
|
* Leaving the headers buffer::Handling marks automatically when leaving
|
|
* Built-in marking functions::Helper functions for dealing with them
|
|
* Custom mark functions::Define your own mark function
|
|
* Adding a new kind of mark::Adding your own marks
|
|
@end menu
|
|
|
|
@node Marking messages
|
|
@section Marking messages
|
|
|
|
There are multiple ways to mark messages:
|
|
@itemize
|
|
@item @emph{message at point}: you can put a mark on the message-at-point in
|
|
either the @ref{Headers view} or @ref{Message view}
|
|
@item @emph{region}: you can put a mark on all messages in the current region
|
|
(selection) in the @ref{Headers view}
|
|
@item @emph{pattern}: you can put a mark on all messages in the @ref{Headers
|
|
view} matching a certain pattern with @kbd{M-x mu4e-headers-mark-pattern}
|
|
(@key{%})
|
|
@item @emph{thread/subthread}: You can put a mark on all the messages in the
|
|
thread/subthread at point with @kbd{M-x mu4e-headers-mark-thread} and @kbd{M-x
|
|
mu4e-headers-mark-subthread}, respectively
|
|
@end itemize
|
|
|
|
@node What to mark for
|
|
@section What to mark for
|
|
|
|
@t{mu4e} supports a number of marks:
|
|
|
|
@cartouche
|
|
@verbatim
|
|
mark for/as | keybinding | description
|
|
-------------+-------------+------------------------------
|
|
'something' | *, <insert> | mark now, decide later
|
|
delete | D, <delete> | delete
|
|
flag | + | mark as 'flagged' ('starred')
|
|
move | m | move to some maildir
|
|
read | ! | mark as read
|
|
refile | r | mark for refiling
|
|
trash | d | move to the trash folder
|
|
untrash | = | remove 'trash' flag
|
|
unflag | - | remove 'flagged' mark
|
|
unmark | u | remove mark at point
|
|
unmark all | U | remove all marks
|
|
unread | ? | marks as unread
|
|
action | a | apply some action
|
|
@end verbatim
|
|
@end cartouche
|
|
|
|
After marking a message, the left-most columns in the headers view indicate
|
|
the kind of mark. This is informative, but if you mark many (say, thousands)
|
|
messages, this slows things down significantly@footnote{this uses an
|
|
@command{emacs} feature called @emph{overlays}, which are slow when used a lot
|
|
in a buffer}. For this reason, you can disable this by setting
|
|
@code{mu4e-headers-show-target} to @code{nil}.
|
|
|
|
@t{something} is a special kind of mark; you can use it to mark messages
|
|
for `something', and then decide later what the `something' should
|
|
be@footnote{This kind of `deferred marking' is similar to the facility
|
|
in @t{dired}, @t{midnight commander}
|
|
(@url{https://www.midnight-commander.org/}) and the like, and uses the
|
|
same key binding (@key{insert}).} Later, you can set the actual mark
|
|
using @kbd{M-x mu4e-mark-resolve-deferred-marks}
|
|
(@key{#}). Alternatively, @t{mu4e} will ask you when you try to execute
|
|
the marks (@key{x}).
|
|
|
|
@node Executing the marks
|
|
@section Executing the marks
|
|
|
|
After you have marked some messages, you can execute them with @key{x}
|
|
(@kbd{M-x mu4e-mark-execute-all}).
|
|
|
|
A hook, @code{mu4e-mark-execute-pre-hook}, is available which is run
|
|
right before execution of each mark. The hook is called with two
|
|
arguments, the mark and the message itself.
|
|
|
|
@node Trashing messages
|
|
@section Trashing messages
|
|
|
|
For regular mailboxes, trashing works like other marks: when executed,
|
|
the message is flagged as trashed. Depending on your mailbox provider,
|
|
the trash flag is used to automatically move the message to the trash
|
|
folder (@code{mu4e-trash-folder}) for instance.
|
|
|
|
Some mailboxes behave differently however and they don't interpret the
|
|
trash flag. In cases like Gmail, the message must be @emph{moved} to
|
|
the trash folder and the trash flag must not be used.
|
|
|
|
@code{mu4e} has provisions for non-standard mailboxes: if a message
|
|
maildir matches a regular expression in
|
|
@code{mu4e-move-to-trash-patterns} then the message is moved instead of
|
|
being flagged. When a context is created with
|
|
@code{make-mu4e-context-account} (see @ref{Account setup helper}), the
|
|
pattern is automatically added for you.
|
|
|
|
This should work fine for Gmail and similar mailboxes. Note that in the
|
|
case of Gmail, you might have to configure your mailbox ``expunge''
|
|
settings.
|
|
|
|
@node Leaving the headers buffer
|
|
@section Leaving the headers buffer
|
|
|
|
When you quit or update a headers buffer that has marked messages (for
|
|
example, by doing a new search), @t{mu4e} asks you what to do with them,
|
|
depending on the value of the variable @code{mu4e-headers-leave-behavior} ---
|
|
see its documentation.
|
|
|
|
@node Built-in marking functions
|
|
@section Built-in marking functions
|
|
|
|
Some examples of @t{mu4e}'s built-in marking functions.
|
|
|
|
@itemize
|
|
@item @emph{Mark the message at point for trashing}: press @key{d}
|
|
@item @emph{Mark all messages in the buffer as unread}: press @kbd{C-x h o}
|
|
@item @emph{Delete the messages in the current thread}: press @kbd{T D}
|
|
@item @emph{Mark messages with a subject matching ``hello'' for flagging}:
|
|
press @kbd{% s hello RET}.
|
|
@end itemize
|
|
|
|
@node Custom mark functions
|
|
@section Custom mark functions
|
|
|
|
Sometimes, the built-in functions to mark messages may not be sufficient for
|
|
your needs. For this, @t{mu4e} offers an easy way to define your own custom
|
|
mark functions. You can choose one of the custom marker functions by pressing
|
|
@key{&} in the @ref{Headers view} and @ref{Message view}.
|
|
|
|
Custom mark functions are to be appended to the list
|
|
@code{mu4e-headers-custom-markers}. Each of the elements of this list
|
|
('markers') is a list with two or three elements:
|
|
@enumerate
|
|
@item The name of the marker --- a short string describing this marker. The
|
|
first character of this string determines its shortcut, so these should be
|
|
unique. If necessary, simply prefix the name with a unique character.
|
|
@item a predicate function, taking two arguments @var{msg} and @var{param}.
|
|
@var{msg} is the message plist (see @ref{Message functions}) and @var{param} is
|
|
a parameter provided by the third of the marker elements (see the next
|
|
item). The predicate function should return non-@t{nil} if the message
|
|
matches.
|
|
@item (optionally) a function that is evaluated once, and the result is passed as a
|
|
parameter to the predicate function. This is useful when user-input is needed.
|
|
@end enumerate
|
|
|
|
Let's look at an example: suppose we want to match all messages that have more
|
|
than @emph{n} recipients --- we could do this with the following recipe:
|
|
|
|
@lisp
|
|
(add-to-list 'mu4e-headers-custom-markers
|
|
'("More than n recipients"
|
|
(lambda (msg n)
|
|
(> (+ (length (mu4e-message-field msg :to))
|
|
(length (mu4e-message-field msg :cc))) n))
|
|
(lambda ()
|
|
(read-number "Match messages with more recipients than: "))) t)
|
|
@end lisp
|
|
|
|
After evaluating this expression, you can use it by pressing @key{&} in
|
|
the headers buffer to select a custom marker function, and then @key{M}
|
|
to choose this particular one (@t{M} because it is the first character
|
|
of the description).
|
|
|
|
As you can see, it's not very hard to define simple functions to match
|
|
messages. There are more examples in the defaults for
|
|
@code{mu4e-headers-custom-markers}; see @file{mu4e-headers.el} and see
|
|
@ref{Extending mu4e} for general information about writing your own functions.
|
|
|
|
|
|
@node Adding a new kind of mark
|
|
@section Adding a new kind of mark
|
|
|
|
It is possible to configure new marks. To do so, one can add entries
|
|
in the list @code{mu4e-marks}. Such an element must have the following form:
|
|
|
|
@lisp
|
|
(SYMBOL
|
|
:char STRING
|
|
:prompt STRING
|
|
:ask-target (lambda () TARGET)
|
|
:dyn-target (lambda (TARGET MSG) DYN-TARGET)
|
|
:show-target (lambda (DYN-TARGET) STRING)
|
|
:action (lambda (DOCID MSG DYN-TARGET) nil))
|
|
@end lisp
|
|
|
|
The symbol can be any symbol, except for @code{'unmark} and
|
|
@code{'something}, which are reserved. The rest is a plist with the
|
|
following elements:
|
|
|
|
@itemize
|
|
@item @code{:char} --- the character to display in the headers view.
|
|
@item @code{:prompt} --- the prompt to use when asking for marks
|
|
(used for example when marking a whole thread).
|
|
@item @code{:ask-target} --- a function run once per bulk-operation, and thus suitable for
|
|
querying the user about a target for move-like marks. If @t{nil}, the
|
|
@t{TARGET} passed to @code{:dyn-target} is @t{nil}.
|
|
@item @code{:dyn-target} --- a function run once per message
|
|
(The message is passed as @t{MSG} to the function). This function allows
|
|
to compute a per-message target, for refile-like marks. If @t{nil}, the
|
|
@t{DYN-TARGET} passed to the @code{:action} is the @t{TARGET} obtained as above.
|
|
@item @code{:show-target} --- how to display the target in the headers view.
|
|
If @code{:show-target} is @t{nil} the @t{DYN-TARGET} is shown (and
|
|
@t{DYN-TARGET} must be a string).
|
|
@item @code{:action} --- the action to apply on the message when the mark is executed.
|
|
@end itemize
|
|
|
|
As an example, suppose we would like to add a mark for tagging
|
|
messages (GMail-style), then we can run the following code (after
|
|
loading @t{mu4e}):
|
|
|
|
@lisp
|
|
(add-to-list 'mu4e-marks
|
|
'(tag
|
|
:char "g"
|
|
:prompt "gtag"
|
|
:ask-target (lambda () (read-string "What tag do you want to add?"))
|
|
:action (lambda (docid msg target)
|
|
(mu4e-action-retag-message msg (concat "+" target)))))
|
|
@end lisp
|
|
|
|
As another example, suppose we would like to ``archive and mark read''
|
|
a message (GMail-style), then we can run the following code (after
|
|
loading @t{mu4e}):
|
|
|
|
@lisp
|
|
(add-to-list 'mu4e-marks
|
|
'(archive
|
|
:char "A"
|
|
:prompt "Archive"
|
|
:show-target (lambda (target) "archive")
|
|
:action (lambda (docid msg target)
|
|
;; must come before proc-move since retag runs
|
|
;; 'sed' on the file
|
|
(mu4e-action-retag-message msg "-\\Inbox")
|
|
(mu4e~proc-move docid nil "+S-u-N"))))
|
|
@end lisp
|
|
|
|
Adding to @code{mu4e-marks} list allows to use the mark in bulk operations
|
|
(for example when tagging a whole thread), but does not bind the mark
|
|
to a key to use at the top-level. This must be done separately. In our
|
|
example:
|
|
|
|
@lisp
|
|
(mu4e~headers-defun-mark-for tag)
|
|
(mu4e~headers-defun-mark-for archive)
|
|
(define-key mu4e-headers-mode-map (kbd "g") 'mu4e-headers-mark-for-tag)
|
|
(define-key mu4e-headers-mode-map (kbd "A") 'mu4e-headers-mark-for-archive)
|
|
@end lisp
|
|
|
|
@node Contexts
|
|
@chapter Contexts
|
|
|
|
@menu
|
|
* What are contexts::Defining the concept
|
|
* Context policies::How to determine the current context
|
|
* Contexts and special folders::Using context variables to determine them
|
|
* Contexts example::How to define contexts
|
|
* Account setup helper::Easy context creation with sane defaults
|
|
* Some context tricks::Other thing to do with contexts
|
|
@end menu
|
|
|
|
It can be useful to switch between different sets of settings in
|
|
@t{mu4e}; a typical example is the case where you have different e-mail
|
|
accounts for private and work email, each with their own values for
|
|
folders, e-mail addresses, mailservers and so on.
|
|
|
|
The @code{mu4e-context} system is a @t{mu4e}-specific mechanism to allow
|
|
for that; users can define different @i{contexts} corresponding with
|
|
groups of setting and either manually switch between them, or let
|
|
@t{mu4e} determine the right context based on some user-provided
|
|
function.
|
|
|
|
Note that there are a number of existing ways to switch accounts in
|
|
@t{mu4e}, for example using the method described in the @ref{Tips and
|
|
Tricks} section of this manual. Those still work --- but the new mechanism
|
|
has the benefit of being a core part of @code{mu4e}, thus allowing for
|
|
deeper integration.
|
|
|
|
@node What are contexts
|
|
@section What are contexts
|
|
|
|
Let's see what's contained in a context. Most of it is optional.
|
|
|
|
A @code{mu4e-context} is Lisp object with the following members:
|
|
@itemize
|
|
@item @t{name}: the name of the context, e.g. @t{work} or @t{private}
|
|
@item @t{vars}:
|
|
an association-list (alist) of variable settings for this account.
|
|
@item @t{enter-func}:
|
|
an (optional) function that takes no parameter and is invoked when entering
|
|
the context. You can use this for extra setup etc.
|
|
@item @t{leave-func}:
|
|
an (optional) function that takes no parameter and is invoked when leaving
|
|
the context. You can use this for clearing things up.
|
|
@item @t{match-func}:
|
|
an (optional) function that takes an @t{MSG} message plist as argument,
|
|
and returns non-@t{nil} if this context matches the situation. @t{mu4e}
|
|
uses the first context that matches, in a couple of situations:
|
|
@itemize
|
|
@item when starting @t{mu4e} to determine the
|
|
starting context; in this case, @t{MSG} is nil. You can use e.g. the
|
|
host you're running or the time of day to determine which context
|
|
matches.
|
|
@item before replying to or forwarding a
|
|
message with the given message plist as parameter, or @t{nil} when
|
|
composing a brand new message. The function should return @t{t} when
|
|
this context is the right one for this message, or @t{nil} otherwise.
|
|
@item when determining the target folders for deleting, refiling etc;
|
|
see @ref{Contexts and special folders}.
|
|
@end itemize
|
|
@end itemize
|
|
|
|
@t{mu4e} uses a variable @code{mu4e-contexts}, which is a list of such
|
|
objects.
|
|
|
|
@node Context policies
|
|
@section Context policies
|
|
|
|
When you have defined contexts and you start @t{mu4e} it decides which
|
|
context to use based on the variable @code{mu4e-context-policy};
|
|
similarly, when you compose a new message, the context is determined
|
|
using @code{mu4e-compose-context-policy}.
|
|
|
|
For both of these, you can choose one of the following policies:
|
|
@itemize
|
|
@item a symbol @code{always-ask}: unconditionally ask the user what context to pick.
|
|
@end itemize
|
|
|
|
The other choices @b{only apply if none of the contexts match} (i.e.,
|
|
none of the contexts' match-functions returns @code{t}). We have the
|
|
following options:
|
|
|
|
@itemize
|
|
@item a symbol @code{ask}: ask the user if @t{mu4e} can't figure
|
|
things out the context by itself (through the match-function). This is a
|
|
good policy if there are no match functions, or if the match functions
|
|
don't cover all cases.
|
|
@item a symbol @code{ask-if-none}: if there's already a context, don't change it; otherwise,
|
|
ask the user.
|
|
@item a symbol @code{pick-first}: pick the first (default) context. This is a good choice if
|
|
you want to specify context for special case, and fall back to the first
|
|
one if none match.
|
|
@item @code{nil}: don't change the context; this is useful if you don't change
|
|
contexts very often, and e.g. manually changes contexts with @kbd{M-x
|
|
mu4e-context-switch}.
|
|
@end itemize
|
|
|
|
@node Contexts and special folders
|
|
@section Contexts and special folders
|
|
|
|
As we discussed in @ref{Folders} and @ref{Dynamic folders}, @t{mu4e}
|
|
recognizes a number of special folders: @code{mu4e-sent-folder},
|
|
@code{mu4e-drafts-folder}, @code{mu4e-trash-folder} and
|
|
@code{mu4e-refile-folder}.
|
|
|
|
When you have a headers-buffer with messages that belong to different
|
|
contexts (say, a few different accounts), it is desirable for each of
|
|
them to use the specific folders for their own context --- so, for
|
|
instance, if you trash a message, it needs to go to the trash-folder for
|
|
the account it belongs to, which is not necessarily the current context.
|
|
|
|
To make this easy to do, whenever @t{mu4e} needs to know the value for
|
|
such a special folder for a given message, it tries to determine the
|
|
appropriate context using @code{mu4e-context-determine} (and policy
|
|
@t{nil}; see @ref{Context policies}). If it finds a matching context, it
|
|
let-binds the @code{vars} for that account, and then determines the
|
|
value for the folder. It does not, however, call the @code{enter-func}
|
|
or @code{leave-func}, since we are not really switching contexts.
|
|
|
|
In practice, this means that as long as each of the accounts has a good
|
|
@t{match-func}, all message operations automatically find the
|
|
appropriate folders.
|
|
|
|
@node Contexts example
|
|
@section Example
|
|
|
|
Let's explain how contexts work by looking at an example. We define two
|
|
contexts, `Private' and `Work' for a fictional user @emph{Alice
|
|
Derleth}.
|
|
|
|
Note that in this case, we automatically switch to the first context
|
|
when starting; see the discussion in the previous section.
|
|
|
|
@lisp
|
|
|
|
(setq mu4e-contexts
|
|
`( ,(make-mu4e-context
|
|
:name "Private"
|
|
:enter-func (lambda () (mu4e-message "Entering Private context"))
|
|
:leave-func (lambda () (mu4e-message "Leaving Private context"))
|
|
;; we match based on the contact-fields of the message
|
|
:match-func (lambda (msg)
|
|
(when msg
|
|
(mu4e-message-contact-field-matches msg
|
|
:to "aliced@@home.example.com")))
|
|
:vars '( ( user-mail-address . "aliced@@home.example.com" )
|
|
( user-full-name . "Alice Derleth" )
|
|
( mu4e-compose-signature .
|
|
(concat
|
|
"Alice Derleth\n"
|
|
"Lauttasaari, Finland\n"))))
|
|
,(make-mu4e-context
|
|
:name "Work"
|
|
:enter-func (lambda () (mu4e-message "Switch to the Work context"))
|
|
;; no leave-func
|
|
;; we match based on the maildir of the message
|
|
;; this matches maildir /Arkham and its sub-directories
|
|
:match-func (lambda (msg)
|
|
(when msg
|
|
(string-match-p "^/Arkham" (mu4e-message-field msg :maildir))))
|
|
:vars '( ( user-mail-address . "aderleth@@miskatonic.example.com" )
|
|
( user-full-name . "Alice Derleth" )
|
|
( mu4e-compose-signature .
|
|
(concat
|
|
"Prof. Alice Derleth\n"
|
|
"Miskatonic University, Dept. of Occult Sciences\n"))))
|
|
|
|
,(make-mu4e-context
|
|
:name "Cycling"
|
|
:enter-func (lambda () (mu4e-message "Switch to the Cycling context"))
|
|
;; no leave-func
|
|
;; we match based on the maildir of the message; assume all
|
|
;; cycling-related messages go into the /cycling maildir
|
|
:match-func (lambda (msg)
|
|
(when msg
|
|
(string= (mu4e-message-field msg :maildir) "/cycling")))
|
|
:vars '( ( user-mail-address . "aderleth@@example.com" )
|
|
( user-full-name . "AliceD" )
|
|
( mu4e-compose-signature . nil)))))
|
|
|
|
;; set `mu4e-context-policy` and `mu4e-compose-policy` to tweak when mu4e should
|
|
;; guess or ask the correct context, e.g.
|
|
|
|
;; start with the first (default) context;
|
|
;; default is to ask-if-none (ask when there's no context yet, and none match)
|
|
;; (setq mu4e-context-policy 'pick-first)
|
|
|
|
;; compose with the current context is no context matches;
|
|
;; default is to ask
|
|
;; (setq mu4e-compose-context-policy nil)
|
|
@end lisp
|
|
|
|
A couple of notes about this example:
|
|
@itemize
|
|
@item You can manually switch the context use @code{M-x mu4e-context-switch},
|
|
by default bound to @kbd{;} in headers, view and main mode.
|
|
The current context appears in the mode-line.
|
|
@item Normally, @code{M-x mu4e-context-switch} does not call the enter or
|
|
leave functions if the 'new' context is the same as the old one.
|
|
However, with a prefix-argument (@kbd{C-u}), you can force @t{mu4e} to
|
|
invoke those function even in that case.
|
|
@item The function @code{mu4e-context-current} returns the current-context;
|
|
the current context is also visible in the mode-line when in
|
|
headers, view or main mode.
|
|
@item You can set any kind of variable; including settings for mail servers etc.
|
|
However, settings such as @code{mu4e-mu-home} are not changeable after
|
|
they have been set without quitting @t{mu4e} first.
|
|
@item @code{leave-func} (if defined) for the context we are leaving, is invoked
|
|
before the @code{enter-func} (if defined) of the
|
|
context we are entering.
|
|
@item @code{enter-func} (if defined) is invoked before setting the variables.
|
|
@item @code{match-func} (if defined) is invoked just before @code{mu4e-compose-pre-hook}.
|
|
@item See the variables @code{mu4e-context-policy} and
|
|
@code{mu4e-compose-context-policy} to tweak what @t{mu4e} should do when
|
|
no context matches (or if you always want to be asked).
|
|
@item Finally, be careful to get the quotations right --- backticks, single quotes
|
|
and commas and note the '.' between variable name and its value.
|
|
@end itemize
|
|
|
|
@node Account setup helper
|
|
@section Account setup helper
|
|
|
|
Contexts can be cumbersome to set up. Thankfully @code{mu4e} provides a
|
|
helper function @code{make-mu4e-context-account} to easily get started.
|
|
The function helps initializing the context plus a couple of variables
|
|
with sane defaults.
|
|
Everything should work out of the box in most cases.
|
|
|
|
A short example for two contexts:
|
|
|
|
@lisp
|
|
(let ((gandi-smtp-vars '((smtpmail-smtp-server . "mail.gandi.net")
|
|
(smtpmail-stream-type . starttls)
|
|
(smtpmail-smtp-service . 587))))
|
|
(make-mu4e-context-account
|
|
:name "personal"
|
|
:user-mail-address "john@@doe.xyz"
|
|
:sent-folder "Sent"
|
|
:vars gandi-smtp-vars)
|
|
(make-mu4e-context-account
|
|
:name "work"
|
|
:user-mail-address "john@@work.org"
|
|
:sent-folder "Sent"
|
|
:predicate (lambda (msg)
|
|
(mu4e-message-contact-field-matches
|
|
msg '(:from :to) "boss@@work.org"))
|
|
:vars gandi-smtp-vars))
|
|
@end lisp
|
|
|
|
A couple of things to note:
|
|
|
|
@itemize
|
|
@item Only the @code{name} slot is mandatory.
|
|
@item The maildir default to the context name.
|
|
@item Folders only need to be given a name, not a relative path.
|
|
They will be automatically stored under the maildir.
|
|
@item When the @code{match-func} is not provided, the context is matched
|
|
against @code{predicate} if provided or the maildir of the current
|
|
message otherwise.
|
|
@end itemize
|
|
|
|
If the context created by @code{make-mu4e-context-account} is not
|
|
enough, you can display the generated context with e.g. @code{M-x
|
|
describe-variable mu4e-contexts} and tweak the result as needed.
|
|
|
|
@node Some context tricks
|
|
@section Some context tricks
|
|
|
|
It is possible to automatically fill @code{mu4e-user-address-list} by
|
|
concatenating the @code{user-mail-address} fields of all contexts:
|
|
|
|
@lisp
|
|
;; This sets `mu4e-user-mail-address-list' to the concatenation of all
|
|
;; `user-mail-address' values for all contexts. If you have other mail
|
|
;; addresses as well, you'll need to add those manually.
|
|
(setq mu4e-user-mail-address-list
|
|
(delq nil
|
|
(mapcar (lambda (context)
|
|
(when (mu4e-context-vars context)
|
|
(cdr (assq 'user-mail-address (mu4e-context-vars context)))))
|
|
mu4e-contexts)))
|
|
@end lisp
|
|
|
|
|
|
@node Dynamic folders
|
|
@chapter Dynamic folders
|
|
|
|
In @ref{Folders}, we explained how you can set up @t{mu4e}'s special
|
|
folders:
|
|
@lisp
|
|
(setq
|
|
mu4e-sent-folder "/sent" ;; sent messages
|
|
mu4e-drafts-folder "/drafts" ;; unfinished messages
|
|
mu4e-trash-folder "/trash" ;; trashed messages
|
|
mu4e-refile-folder "/archive") ;; saved messages01
|
|
@end lisp
|
|
|
|
In some cases, having such static folders may not suffice --- perhaps you want
|
|
to change the folders depending on the context. For example, the folder for
|
|
refiling could vary, based on the sender of the message.
|
|
|
|
To make this possible, instead of setting the standard folders to a string,
|
|
you can set them to be a @emph{function} that takes a message as its
|
|
parameter, and returns the desired folder name. This chapter shows you how to
|
|
do that. For a more general discussion of how to extend @t{mu4e} and writing
|
|
your own functions, see @ref{Extending mu4e}.
|
|
|
|
If you use @t{mu4e-context}, see @ref{Contexts and special folders} for
|
|
what that means for these special folders.
|
|
|
|
@menu
|
|
* Smart refiling:: Automatically choose the target folder
|
|
* Other dynamic folders:: Flexible folders for sent, trash, drafts
|
|
@end menu
|
|
|
|
|
|
@node Smart refiling
|
|
@section Smart refiling
|
|
|
|
When refiling messages, perhaps to archive them, it can be useful to have
|
|
different target folders for different messages, based on some property of
|
|
those message --- smart refiling.
|
|
|
|
To accomplish this, we can set the refiling folder (@code{mu4e-refile-folder})
|
|
to a function that returns the actual refiling folder for the particular
|
|
message. An example should clarify this:
|
|
|
|
@lisp
|
|
(setq mu4e-refile-folder
|
|
(lambda (msg)
|
|
(cond
|
|
;; messages to the mu mailing list go to the /mu folder
|
|
((mu4e-message-contact-field-matches msg :to
|
|
"mu-discuss@@googlegroups.com")
|
|
"/mu")
|
|
;; messages sent directly to me go to /archive
|
|
;; also `mu4e-user-mail-address-p' can be used
|
|
((mu4e-message-contact-field-matches msg :to "me@@example.com")
|
|
"/private")
|
|
;; messages with football or soccer in the subject go to /football
|
|
((string-match "football\\|soccer"
|
|
(mu4e-message-field msg :subject))
|
|
"/football")
|
|
;; messages sent by me go to the sent folder
|
|
((find-if
|
|
(lambda (addr)
|
|
(mu4e-message-contact-field-matches msg :from addr))
|
|
mu4e-user-mail-address-list)
|
|
mu4e-sent-folder)
|
|
;; everything else goes to /archive
|
|
;; important to have a catch-all at the end!
|
|
(t "/archive"))))
|
|
@end lisp
|
|
|
|
@noindent
|
|
This can be very powerful; you can select some messages in the headers view,
|
|
then press @key{r}, and have them all marked for refiling to their particular
|
|
folders.
|
|
|
|
Some notes:
|
|
@itemize
|
|
@item We set @code{mu4e-refile-folder} to an anonymous (@t{lambda}) function. This
|
|
function takes one argument, a message plist@footnote{a property list
|
|
describing a message}. The plist corresponds to the message at point. See
|
|
@ref{Message functions} for a discussion on how to deal with them.
|
|
@item In our function, we use a @t{cond} control structure; the function
|
|
returns the first of the clauses that matches. It's important to make the last
|
|
clause a catch-all, so we always return @emph{some} folder.
|
|
@item We use
|
|
the convenience function @code{mu4e-message-contact-field-matches},
|
|
which evaluates to @code{t} if any of the names or e-mail addresses in a
|
|
contact field (in this case, the @t{To:}-field) matches the regular
|
|
expression. With @t{mu4e} version 0.9.16 or newer, the contact field can
|
|
in fact be a list instead of a single value, such as @code{'(:to :cc)'}.
|
|
@end itemize
|
|
|
|
@node Other dynamic folders
|
|
@section Other dynamic folders
|
|
|
|
Using the same mechanism, you can create dynamic sent-, trash-, and
|
|
drafts-folders. The message-parameter you receive for the sent and drafts
|
|
folder is the @emph{original} message, that is, the message you reply to, or
|
|
forward, or edit. If there is no such message (for example when composing a
|
|
brand new message) the message parameter is @t{nil}.
|
|
|
|
Let's look at an example. Suppose you want a different trash folder for
|
|
work-email. You can achieve this with something like:
|
|
|
|
@lisp
|
|
(setq mu4e-trash-folder
|
|
(lambda (msg)
|
|
;; the 'and msg' is to handle the case where msg is nil
|
|
(if (and msg
|
|
(mu4e-message-contact-field-matches msg :to "me@@work.example.com"))
|
|
"/trash-work"
|
|
"/trash")))
|
|
@end lisp
|
|
|
|
@noindent
|
|
Good to remember:
|
|
@itemize
|
|
@item The @var{msg} parameter you receive in the function refers to the
|
|
@emph{original message}, that is, the message being replied to or
|
|
forwarded. When re-editing a message, it refers to the message being
|
|
edited. When you compose a totally new message, the @var{msg} parameter is
|
|
@code{nil}.
|
|
@item When re-editing messages, the value of @code{mu4e-drafts-folder} is ignored.
|
|
@end itemize
|
|
|
|
|
|
@node Actions
|
|
@chapter Actions
|
|
|
|
@t{mu4e} lets you define custom actions for messages in @ref{Headers view}
|
|
and for both messages and attachments in @ref{Message view}. Custom
|
|
actions allow you to easily extend @t{mu4e} for specific needs --- for example,
|
|
marking messages as spam in a spam filter or applying an attachment with a
|
|
source code patch.
|
|
|
|
You can invoke the actions with key @key{a} for actions on messages, and key
|
|
@key{A} for actions on attachments.
|
|
|
|
For general information extending @t{mu4e} and writing your own functions, see
|
|
@ref{Extending mu4e}.
|
|
|
|
@menu
|
|
* Defining actions::How to create an action
|
|
* Headers view actions::Doing things with message headers
|
|
* Message view actions::Doing things with messages
|
|
* Attachment actions::Doing things with attachments
|
|
* Example actions::Some more examples
|
|
@end menu
|
|
|
|
@node Defining actions
|
|
@section Defining actions
|
|
|
|
Defining a new custom action comes down to writing an elisp-function to do the
|
|
work. Functions that operate on messages receive a @var{msg} parameter, which
|
|
corresponds to the message at point. Something like:
|
|
@lisp
|
|
(defun my-action-func (msg)
|
|
"Describe my message function."
|
|
;; do stuff
|
|
)
|
|
@end lisp
|
|
|
|
@noindent
|
|
Functions that operate on attachments receive a @var{msg} parameter, which
|
|
corresponds to the message at point, and an @var{attachment-num}, which is the
|
|
number of the attachment as seen in the message view. An attachment function
|
|
looks like:
|
|
@lisp
|
|
(defun my-attachment-action-func (msg attachment-num)
|
|
"Describe my attachment function."
|
|
;; do stuff
|
|
)
|
|
@end lisp
|
|
|
|
@noindent
|
|
After you have defined your function, you can add it to the list of
|
|
actions@footnote{Instead of defining the functions separately, you can
|
|
obviously also add a @code{lambda}-function directly to the list; however,
|
|
separate functions are easier to change}, either @code{mu4e-headers-actions},
|
|
@code{mu4e-view-actions} or @code{mu4e-view-attachment-actions}. The
|
|
format@footnote{Note, the format of the actions has changed since version
|
|
0.9.8.4, and you must change your configuration to use the new format;
|
|
@t{mu4e} warns you when you are using the old format.} of each action is a
|
|
cons-cell, @code{(DESCRIPTION . VALUE)}; see below for some examples. If your
|
|
shortcut is not also the first character of the description, simply prefix the
|
|
description with that character.
|
|
|
|
Let's look at some examples.
|
|
|
|
@node Headers view actions
|
|
@section Headers view actions
|
|
|
|
Suppose we want to inspect the number of recipients for a message in the
|
|
@ref{Headers view}. We add the following to our configuration:
|
|
|
|
@lisp
|
|
(defun show-number-of-recipients (msg)
|
|
"Display the number of recipients for the message at point."
|
|
(message "Number of recipients: %d"
|
|
(+ (length (mu4e-message-field msg :to))
|
|
(length (mu4e-message-field msg :cc)))))
|
|
|
|
;; define 'N' (the first letter of the description) as the shortcut
|
|
;; the 't' argument to add-to-list puts it at the end of the list
|
|
(add-to-list 'mu4e-headers-actions
|
|
'("Number of recipients" . show-number-of-recipients) t)
|
|
@end lisp
|
|
|
|
After evaluating this, @kbd{a N} in the headers view shows the number of
|
|
recipients for the message at point.
|
|
|
|
@node Message view actions
|
|
@section Message view actions
|
|
|
|
As another example, suppose we would like to search for messages by the sender
|
|
of the message at point:
|
|
|
|
@lisp
|
|
(defun search-for-sender (msg)
|
|
"Search for messages sent by the sender of the message at point."
|
|
(mu4e-headers-search
|
|
(concat "from:" (cdar (mu4e-message-field msg :from)))))
|
|
|
|
;; define 'x' as the shortcut
|
|
(add-to-list 'mu4e-view-actions
|
|
'("xsearch for sender" . search-for-sender) t)
|
|
@end lisp
|
|
|
|
@indent
|
|
If you wonder why we use @code{cdar}, remember that the @t{From:}-field is a
|
|
list of @code{(NAME . EMAIL)} cells; thus, @code{cdar} gets us the e-mail
|
|
address of the first in the list. @t{From:}-fields rarely contain multiple
|
|
cells.
|
|
|
|
@node Attachment actions
|
|
@section Attachment actions
|
|
|
|
Finally, let's define an attachment action. As mentioned, attachment-action
|
|
functions receive @emph{2} arguments, the message and the attachment number to
|
|
use.
|
|
|
|
The following example action counts the number of lines in an attachment, and
|
|
defines @key{n} as its shortcut key (the @key{n} is prefixed to the
|
|
description).
|
|
|
|
@lisp
|
|
(defun count-lines-in-attachment (msg attachnum)
|
|
"Count the number of lines in an attachment."
|
|
(mu4e-view-pipe-attachment msg attachnum "wc -l"))
|
|
|
|
;; defining 'n' as the shortcut
|
|
(add-to-list 'mu4e-view-attachment-actions
|
|
'("ncount lines" . count-lines-in-attachment) t)
|
|
@end lisp
|
|
|
|
@node Example actions
|
|
@section Example actions
|
|
|
|
@t{mu4e} includes a number of example actions in the file
|
|
@file{mu4e-actions.el} in the source distribution (see @kbd{C-h f
|
|
mu4e-action-TAB}). For example, for viewing messages in an external web
|
|
browser, or listening to a message's body-text using text-to-speech.
|
|
|
|
@node Extending mu4e
|
|
@chapter Extending mu4e
|
|
|
|
@t{mu4e} is designed to be easily extendible --- that is, write your own
|
|
emacs-lisp to make @t{mu4e} behave exactly as you want. Here, we provide some
|
|
guidelines for doing so.
|
|
|
|
@menu
|
|
* Extension points::Where to hook into @t{mu4e}
|
|
* Available functions::General helper functions
|
|
* Message functions::Working with messages
|
|
* Contact functions::Working with contacts
|
|
* Utility functions::Miscellaneous helpers
|
|
@end menu
|
|
|
|
@node Extension points
|
|
@section Extension points
|
|
|
|
There are a number of places where @t{mu4e} lets you plug in your own
|
|
functions:
|
|
@itemize
|
|
@item Custom functions for message headers in the message-view and
|
|
headers-view --- see @ref{HV Custom headers}, @ref{MSGV Custom headers}
|
|
@item Using message-specific folders for drafts, trash, sent messages and
|
|
refiling, based on a function --- see @ref{Dynamic folders}
|
|
@item Using an attachment-specific download-directory --- see the
|
|
variable @code{mu4e-attachment-dir}.
|
|
@item Apply a function to a message in the headers view -
|
|
see @ref{Headers view actions}
|
|
@item Apply a function to a message in the message view --- see @ref{Message view actions}
|
|
@item Add a new kind of mark for use in the headers view
|
|
- see @ref{Adding a new kind of mark}
|
|
@item Apply a function to an attachment --- see @ref{Attachment actions}
|
|
@item Custom function to mark certain messages --- see @ref{Custom mark functions}
|
|
@item Using various @emph{mode}-hooks, @code{mu4e-compose-pre-hook} (see
|
|
@ref{Compose hooks}), @code{mu4e-index-updated-hook} (see @ref{FAQ})
|
|
@end itemize
|
|
|
|
@noindent
|
|
You can also write your own functions without using the above. If you
|
|
want to do so, key useful functions are @code{mu4e-message-at-point}
|
|
(see below), @code{mu4e-headers-for-each} (to iterate over all
|
|
headers, see its docstring) and @code{mu4e-view-for-each-part} (to
|
|
iterate over all parts/attachments, see its docstring). There is also
|
|
@code{mu4e-view-for-each-uri} to iterate of all the URIs in the
|
|
current message.
|
|
|
|
Another useful function is
|
|
@code{mu4e-headers-find-if} which searches for a message matching a
|
|
certain pattern; again, see its docstring.
|
|
|
|
@node Available functions
|
|
@section Available functions
|
|
|
|
The whole of @t{mu4e} consists of hundreds of elisp functions. However, the
|
|
majority of those are for @emph{internal} use only; you can recognize them
|
|
easily, because they all start with @code{mu4e~}. These functions make all
|
|
kinds of assumptions, and they are subject to change, and should therefore
|
|
@emph{not} be used. The same is true for @emph{variables} that start with
|
|
@code{mu4e~}; don't touch them. Let me repeat that:
|
|
@verbatim
|
|
Do not use mu4e~... functions or variables!
|
|
@end verbatim
|
|
|
|
@noindent
|
|
In addition, you should use functions in the right context; functions
|
|
that start with @t{mu4e-view-} are only applicable to the message view,
|
|
while functions starting with @t{mu4e-headers-} are only applicable to
|
|
the headers view. Functions without such prefixes are applicable
|
|
everywhere.
|
|
|
|
@node Message functions
|
|
@section Message functions
|
|
|
|
Many functions in @t{mu4e} deal with message plists (property
|
|
lists). They contain information about messages, such as sender and
|
|
recipient, subject, date and so on. To deal with these plists, there are
|
|
a number of @code{mu4e-message-} functions (in @file{mu4e-message.el}),
|
|
such as @code{mu4e-message-field} and @code{mu4e-message-at-point}, and
|
|
a shortcut to combine the two, @code{mu4e-message-field-at-point}.
|
|
|
|
For example, to get the subject of the message at point, in either the headers
|
|
view or the message view, you could write:
|
|
@lisp
|
|
(mu4e-message-field (mu4e-message-at-point) :subject)
|
|
@end lisp
|
|
@noindent
|
|
Note that:
|
|
@itemize
|
|
@item The contact fields (To, From, Cc, Bcc) are lists of cons-pairs
|
|
@code{(name . email)}; @code{name} may be @code{nil}. So, for example:
|
|
@lisp
|
|
(mu4e-message-field some-msg :to)
|
|
;; => (("Jack" . "jack@@example.com") (nil . "foo@@example.com"))
|
|
@end lisp
|
|
|
|
If you are only looking for a match in this list (e.g., ``Is Jack one of the
|
|
recipients of the message?''), there is a convenience function
|
|
@code{mu4e-message-contact-field-matches} to make this easy.
|
|
@item The message body is only available in the message view, not in the
|
|
headers view.
|
|
@end itemize
|
|
|
|
Note that in headers-mode, you only have access to a reduced message
|
|
plist, without the information about the message-body or mime-parts;
|
|
@t{mu4e} does this for performance reasons. And even in view-mode, you
|
|
do not have access to arbitrary message-headers.
|
|
|
|
However, it is possible to get the information indirectly, using the
|
|
raw-message and some third-party tool like @t{procmail}'s @t{formail}:
|
|
|
|
@lisp
|
|
(defun my-mu4e-any-message-field-at-point (hdr)
|
|
"Quick & dirty way to get an arbitrary header HDR at
|
|
point. Requires the 'formail' tool from procmail."
|
|
(replace-regexp-in-string "\n$" ""
|
|
(shell-command-to-string
|
|
(concat "formail -x " hdr " -c < "
|
|
(shell-quote-argument (mu4e-message-field-at-point :path))))))
|
|
@end lisp
|
|
|
|
@subsection Rewriting the message body
|
|
|
|
Message body rewriting allows you to modify the message text that is
|
|
presented in the message view. This can be useful if the message needs
|
|
special processing, for instance for special filling or cleaning up
|
|
encoding artifacts (this is what @t{mu4e} uses this for internally).
|
|
|
|
To enable this, you can append your rewrite-function to
|
|
@code{mu4e-message-body-rewrite-functions}; your function is expected to
|
|
take two parameters @code{MSG} and @code{TXT}, which are the
|
|
message-plist and the body-text, which could be the result of earlier
|
|
transformations, including html->text conversion as per
|
|
@code{mu4e-html2-text-command}. The function is expected to return the
|
|
transformed text.
|
|
|
|
As a fairly useless example, suppose we insist on reading @t{mu4e} as
|
|
@t{MU4E}:
|
|
@lisp
|
|
(defun mu4e-to-MU4E-rewrite (msg txt)
|
|
(replace-regexp-in-string "mu4e" "MU4E" txt))
|
|
|
|
(add-to-list 'mu4e-message-body-rewrite-functions 'mu4e-to-MU4E-rewrite t)
|
|
@end lisp
|
|
|
|
|
|
@node Contact functions
|
|
@section Contact functions
|
|
|
|
It can sometimes be useful to discard or rewrite the contact
|
|
information that @t{mu4e} provides, for example to fix spelling
|
|
errors, or omit unwanted contacts.
|
|
|
|
To handle this, @t{mu4e} provides
|
|
@code{mu4e-contact-process-function}, which, if defined, is applied to
|
|
each contact. If the result is @t{nil}, the contact is discarded,
|
|
otherwise the (modified or not) contact information is used.
|
|
|
|
Each contact is a full e-mail address as you would see in a
|
|
contact-field of an e-mail message, e.g.,
|
|
@verbatim
|
|
"Foo Bar" <foo.bar@example.com>
|
|
@end verbatim
|
|
or
|
|
@verbatim
|
|
cuux@example.com
|
|
@end verbatim
|
|
|
|
An example @code{mu4e-contact-process-function} might look like:
|
|
|
|
@lisp
|
|
(defun my-contact-processor (contact)
|
|
(cond
|
|
;; remove unwanted
|
|
((string-match-p "evilspammer@@example.com" contact) nil)
|
|
((string-match-p "noreply" contact) nil)
|
|
;;
|
|
;; jonh smiht --> John Smith
|
|
((string-match "jonh smiht" contact)
|
|
(replace-regexp-in-string "jonh smiht" "John Smith" contact))
|
|
(t contact)))
|
|
|
|
(setq mu4e-contact-process-function 'my-contact-processor)
|
|
@end lisp
|
|
|
|
|
|
@node Utility functions
|
|
@section Utility functions
|
|
|
|
@file{mu4e-utils} contains a number of utility functions; we list a few here.
|
|
See their docstrings for details:
|
|
@itemize
|
|
@item @code{mu4e-read-option}: read one option from a list. For example:
|
|
@lisp
|
|
(mu4e-read-option "Choose an animal: "
|
|
'(("Monkey" . monkey) ("Gnu" . gnu) ("xMoose" . moose)))
|
|
@end lisp
|
|
The user is presented with:
|
|
@example
|
|
Choose an animal: [M]onkey, [G]nu, [x]Moose
|
|
@end example
|
|
@item @code{mu4e-ask-maildir}: ask for a maildir; try one of the
|
|
shortcuts (@code{mu4e-maildir-shortcuts}), or the full set of available
|
|
maildirs.
|
|
@item @code{mu4e-running-p}: return @code{t} if the @t{mu4e} process is
|
|
running, @code{nil} otherwise.
|
|
@item @code{(mu4e-user-mail-address-p addr)}: return @code{t} if @var{addr} is
|
|
one of the user's e-mail addresses (as per @code{mu4e-user-mail-address-list}).
|
|
@item @code{mu4e-log} logs to the @t{mu4e} debugging log if it is enabled;
|
|
see @code{mu4e-toggle-logging}.
|
|
@item @code{mu4e-message}, @code{mu4e-warning}, @code{mu4e-error} are the
|
|
@t{mu4e} equivalents of the normal elisp @code{message},
|
|
@code{user-error}@footnote{@code{user-error} only appears in @command{emacs}
|
|
24.2 and later; in older versions it falls back to @code{error}} and
|
|
@code{error} functions.
|
|
@end itemize
|
|
|
|
|
|
@node Other tools
|
|
@appendix Other tools
|
|
|
|
In this chapter, we discuss some ways in which @t{mu4e} can cooperate
|
|
with other tools.
|
|
|
|
@menu
|
|
* Emacs default::Making mu4e the default emacs e-mail program
|
|
* Org-mode links::Adding mu4e to your organized life
|
|
* Org-contacts::Hooking up with org-contacts
|
|
* BBDB::Hooking up with the Insidious Big Brother Database
|
|
* Sauron::Getting new mail notifications with Sauron
|
|
* Speedbar::A special frame with your folders
|
|
* Mu-cite:: Fancy citation engine
|
|
* Dired:: Attaching files using @t{dired}
|
|
* Hydra:: Custom shortcut menus
|
|
@end menu
|
|
|
|
@node Emacs default
|
|
@section Emacs default
|
|
|
|
@command{emacs} allows you to select an e-mail program as the default
|
|
program it uses when you press @key{C-x m} (@code{compose-mail}), call
|
|
@code{report-emacs-bug} and so on. If you want to use @t{mu4e} for this,
|
|
you can do so by adding the following to your configuration:
|
|
|
|
@lisp
|
|
(setq mail-user-agent 'mu4e-user-agent)
|
|
@end lisp
|
|
|
|
@node Org-mode links
|
|
@section Org-mode links
|
|
|
|
It can be useful to include links to e-mail messages or even search
|
|
queries in your org-mode files. @t{mu4e} supports this by default,
|
|
unless you set @t{mu4e-support-org} to @code{nil}.
|
|
|
|
You can use the normal @t{org-mode} mechanisms to store links:
|
|
@kbd{M-x org-store-link} stores a link to a particular message when
|
|
you are in @ref{Message view}. When you are in @ref{Headers view},
|
|
@kbd{M-x org-store-link} links to the @emph{query} if
|
|
@code{mu4e-org-link-query-in-headers-mode} is non-@code{nil}, and to
|
|
the particular message otherwise (which is the default).
|
|
|
|
You can insert this link later with @kbd{M-x org-insert-link}. From
|
|
@t{org-mode}, you can go to the query or message the link points to with
|
|
either @kbd{M-x org-agenda-open-link} in agenda buffers, or @kbd{M-x
|
|
org-open-at-point} elsewhere --- both typically bound to @kbd{C-c C-o}.
|
|
|
|
You can also directly @emph{capture} such links --- for example, to
|
|
add e-mail messages to your todo-list. For that, @t{org-mu4e} has a
|
|
function @code{mu4e-org-store-and-capture}. This captures the
|
|
message-at-point (or header --- see the discussion on
|
|
@code{mu4e-org-link-query-in-headers-mode} above), then calls
|
|
@t{org-mode}'s capture functionality.
|
|
|
|
You can add some specific capture-template for this: for example, to add
|
|
a message to your todo-list, and set a deadline for processing it within
|
|
two days, you could add this to @code{org-capture-templates}:
|
|
|
|
@lisp
|
|
("P" "process-soon" entry (file+headline "todo.org" "Todo")
|
|
"* TODO %a %?\nDEADLINE: %(org-insert-time-stamp (org-read-date nil t \"+2d\"))")
|
|
@end lisp
|
|
|
|
If you use the functionality a lot, you may want to define key-bindings
|
|
for that in headers and view mode:
|
|
|
|
@lisp
|
|
(define-key mu4e-headers-mode-map (kbd "C-c c") 'org-mu4e-store-and-capture)
|
|
(define-key mu4e-view-mode-map (kbd "C-c c") 'org-mu4e-store-and-capture)
|
|
@end lisp
|
|
|
|
@node Org-contacts
|
|
@section Org-contacts
|
|
|
|
Note, @t{mu4e} supports built-in address autocompletion; @ref{Address
|
|
autocompletion}, and that is the recommended way to do this. However, it
|
|
is also possible to manage your addresses with @t{org-mode}, using
|
|
@t{org-contacts}@footnote{@url{https://julien.danjou.info/projects/emacs-packages#org-contacts}}.
|
|
|
|
@t{mu4e-actions} defines a useful action (@ref{Actions}) for adding a contact
|
|
based on the @t{From:}-address in the message at point. To enable this, add to
|
|
your configuration something like:
|
|
|
|
@lisp
|
|
(setq mu4e-org-contacts-file <full-path-to-your-org-contacts-file>)
|
|
(add-to-list 'mu4e-headers-actions
|
|
'("org-contact-add" . mu4e-action-add-org-contact) t)
|
|
(add-to-list 'mu4e-view-actions
|
|
'("org-contact-add" . mu4e-action-add-org-contact) t)
|
|
@end lisp
|
|
|
|
@noindent
|
|
After this, you should be able to add contacts using @key{a o} in the headers
|
|
view and the message view, using the @t{org-capture} mechanism. Note, the
|
|
shortcut character @key{o} is due to the first character of
|
|
@t{org-contact-add}.
|
|
|
|
@node BBDB
|
|
@section BBDB
|
|
|
|
Note, @t{mu4e} supports built-in address autocompletion; @ref{Address
|
|
autocompletion}, and that is the recommended way to do this. However, it
|
|
is also possible to manage your addresses with the current (2015-06-23)
|
|
development release of @t{BBDB}, or releases of @t{BBDB} after
|
|
3.1.2.@footnote{@url{https://savannah.nongnu.org/projects/bbdb/}}.
|
|
|
|
To enable BBDB, add to your @file{~/.emacs} (or its moral equivalent,
|
|
such as @file{~/.emacs.d/init.el}) the following @emph{after} the
|
|
@code{(require 'mu4e)} line:
|
|
|
|
@lisp
|
|
;; Load BBDB (Method 1)
|
|
(require 'bbdb-loaddefs)
|
|
;; OR (Method 2)
|
|
;; (require 'bbdb-loaddefs "/path/to/bbdb/lisp/bbdb-loaddefs.el")
|
|
;; OR (Method 3)
|
|
;; (autoload 'bbdb-insinuate-mu4e "bbdb-mu4e")
|
|
;; (bbdb-initialize 'message 'mu4e)
|
|
|
|
(setq bbdb-mail-user-agent 'mu4e-user-agent)
|
|
(setq mu4e-view-mode-hook 'bbdb-mua-auto-update)
|
|
(setq mu4e-compose-complete-addresses nil)
|
|
(setq bbdb-mua-pop-up t)
|
|
(setq bbdb-mua-pop-up-window-size 5)
|
|
(setq mu4e-view-show-addresses t)
|
|
@end lisp
|
|
|
|
@noindent
|
|
After this, you should be able to:
|
|
@itemize
|
|
@item In mu4e-view mode, add the sender of the email to BBDB with @key{C-u :}
|
|
@item Tab-complete addresses from BBDB when composing emails
|
|
@item View the BBDB contact while viewing a message
|
|
@end itemize
|
|
|
|
@node Sauron
|
|
@section Sauron
|
|
|
|
The @command{emacs} package @t{sauron}@footnote{Sauron can be found at
|
|
@url{https://github.com/djcb/sauron}, or in the Marmalade package repository
|
|
at @url{https://marmalade-repo.org/}} (by the same author) can be used
|
|
to get notifications about new mails. If you run something like the below
|
|
script from your @t{crontab} (or have some other way of having it execute
|
|
every @emph{n} minutes), you receive notifications in the @t{sauron}-buffer
|
|
when new messages arrive.
|
|
|
|
@verbatim
|
|
#!/bin/sh
|
|
|
|
# the mu binary
|
|
MU=mu
|
|
|
|
# put the path to your Inbox folder here
|
|
CHECKDIR="/home/$LOGNAME/Maildir/Inbox"
|
|
|
|
sauron_msg () {
|
|
DBUS_COOKIE="/home/$LOGNAME/.sauron-dbus"
|
|
if test "x$DBUS_SESSION_BUS_ADDRESS" = "x"; then
|
|
if test -e $DBUS_COOKIE; then
|
|
export DBUS_SESSION_BUS_ADDRESS="`cat $DBUS_COOKIE`"
|
|
fi
|
|
fi
|
|
if test -n "x$DBUS_SESSION_BUS_ADDRESS"; then
|
|
dbus-send --session \
|
|
--dest="org.gnu.Emacs" \
|
|
--type=method_call \
|
|
"/org/gnu/Emacs/Sauron" \
|
|
"org.gnu.Emacs.Sauron.AddMsgEvent" \
|
|
string:shell uint32:3 string:"$1"
|
|
fi
|
|
}
|
|
|
|
#
|
|
# -mmin -5: consider only messages that were created / changed in the
|
|
# the last 5 minutes
|
|
#
|
|
for f in `find $CHECKDIR -mmin -5 -a -type f`; do
|
|
subject=`$MU view $f | grep '^Subject:' | sed 's/^Subject://'`
|
|
sauron_msg "mail: $subject"
|
|
done
|
|
@end verbatim
|
|
|
|
@noindent
|
|
You might want to put:
|
|
@lisp
|
|
(setq sauron-dbus-cookie t)
|
|
@end lisp
|
|
@noindent
|
|
in your setup, to allow the script to find the D-Bus session bus, even when
|
|
running outside its session.
|
|
|
|
@node Speedbar
|
|
@section Speedbar
|
|
|
|
@code{speedbar} is an @command{emacs}-extension that shows navigational information for
|
|
an @command{emacs} buffer in a separate frame. Using @code{mu4e-speedbar}, @t{mu4e}
|
|
lists your bookmarks and maildir folders and allows for one-click access to
|
|
them.
|
|
|
|
@t{mu4e} loads @t{mu4e-speedbar} automatically; all you need to do to activate
|
|
it is @kbd{M-x speedbar}. Then, when then switching to the @ref{Main view},
|
|
the speedbar-frame is updated with your bookmarks and maildirs. For speed
|
|
reasons, the list of maildirs is determined when @t{mu4e} starts; if the list
|
|
of maildirs changes while @t{mu4e} is running, you need to restart @t{mu4e} to
|
|
have those changes reflected in the speedbar and in other places that use this
|
|
list, such as auto-completion when jumping to a maildir.
|
|
|
|
@code{mu4e-speedbar} was contributed by @emph{Antono Vasiljev}.
|
|
|
|
@node Mu-cite
|
|
@section Mu-cite
|
|
|
|
@t{mu-cite}@footnote{Note, despite its name, @t{mu-cite} is a project
|
|
unconnected to @t{mu}/@t{mu4e}} is a package to control the way message
|
|
citations look like (i.e., the message you responded to when you reply to them
|
|
or forward them), with its latest version available at
|
|
@url{https://www.jpl.org/elips/mu/}.
|
|
|
|
After installing @t{mu-cite}, you can use something like the following to make
|
|
it work with @t{mu4e}:
|
|
|
|
@lisp
|
|
(require 'mu-cite)
|
|
(setq mu4e-compose-cite-function 'mu-cite-original)
|
|
(setq mu-cite-top-format '("On " date ", " from " wrote:\n\n"))
|
|
(setq mu-cite-prefix-format '(" > "))
|
|
@end lisp
|
|
|
|
@node Dired
|
|
@section Dired
|
|
|
|
It is possible to attach files to @t{mu4e} messages using @t{dired}
|
|
(@inforef{Dired,,emacs}), using the following steps (based on a post on the
|
|
@t{mu-discuss} mailing list by @emph{Stephen Eglen}).
|
|
|
|
To prepare for this, you need a special version of the
|
|
@code{gnus-dired-mail-buffers} function so it understands @t{mu4e} buffers as
|
|
well; so put in your configuration:
|
|
|
|
@lisp
|
|
(require 'gnus-dired)
|
|
;; make the `gnus-dired-mail-buffers' function also work on
|
|
;; message-mode derived modes, such as mu4e-compose-mode
|
|
(defun gnus-dired-mail-buffers ()
|
|
"Return a list of active message buffers."
|
|
(let (buffers)
|
|
(save-current-buffer
|
|
(dolist (buffer (buffer-list t))
|
|
(set-buffer buffer)
|
|
(when (and (derived-mode-p 'message-mode)
|
|
(null message-sent-message-via))
|
|
(push (buffer-name buffer) buffers))))
|
|
(nreverse buffers)))
|
|
|
|
(setq gnus-dired-mail-mode 'mu4e-user-agent)
|
|
(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode)
|
|
@end lisp
|
|
|
|
Then, mark the file(s) in @t{dired} you would like to attach and press @t{C-c
|
|
RET C-a}, and you'll be asked whether to attach them to an existing message,
|
|
or create a new one.
|
|
|
|
@node Hydra
|
|
@section Hydra
|
|
|
|
People sometimes ask about having multi-character shortcuts for
|
|
bookmarks; and easy way to achieve this, is by using anm emacs package
|
|
called Hydra@footnote{@url{https://github.com/abo-abo/hydra}}.
|
|
|
|
With Hydra installed, we can add multi-character shortcuts, for instance:
|
|
@lisp
|
|
(defhydra my-mu4e-bookmarks-work (:color blue)
|
|
"work bookmarks"
|
|
("b" (mu4e-headers-search "banana AND maildir:/work") "banana")
|
|
("u" (mu4e-headers-search "flag:unread AND maildir:/work") "unread"))
|
|
|
|
(defhydra my-mu4e-bookmarks-personal (:color blue)
|
|
"personal bookmarks"
|
|
("c" (mu4e-headers-search "capybara AND maildir:/personal") "capybara")
|
|
("u" (mu4e-headers-search "flag:unread AND maildir:/personal") "unread"))
|
|
|
|
(defhydra my-mu4e-bookmarks (:color blue)
|
|
"mu4e bookmarks"
|
|
("p" (my-mu4e-bookmarks-personal/body) "Personal")
|
|
("w" (my-mu4e-bookmarks-work/body) "Work"))
|
|
|
|
Now, you can bind a convenient key to my-mu4e-bookmarks/body.
|
|
@end lisp
|
|
|
|
@node Example configs
|
|
@appendix Example configs
|
|
|
|
In this chapter, we show some example configurations. While it is very useful
|
|
to see some working settings, we'd like to warn against blindly copying such
|
|
things.
|
|
|
|
@menu
|
|
* Minimal configuration::Simplest configuration to get you going
|
|
* Longer configuration::A more extensive setup
|
|
* Gmail configuration::GMail-specific setup
|
|
* Other settings:CONF Other settings. Some other useful configuration
|
|
|
|
@end menu
|
|
|
|
@node Minimal configuration
|
|
@section Minimal configuration
|
|
|
|
An (almost) minimal configuration for @t{mu4e} might look like this --- as you
|
|
see, most of it is commented-out.
|
|
|
|
@lisp
|
|
;; example configuration for mu4e
|
|
|
|
;; make sure mu4e is in your load-path
|
|
(require 'mu4e)
|
|
|
|
;; use mu4e for e-mail in emacs
|
|
(setq mail-user-agent 'mu4e-user-agent)
|
|
|
|
;; these must start with a "/", and must exist
|
|
;; (i.e.. /home/user/Maildir/sent must exist)
|
|
;; you use e.g. 'mu mkdir' to make the Maildirs if they don't
|
|
;; already exist
|
|
|
|
;; below are the defaults; if they do not exist yet, mu4e offers to
|
|
;; create them. they can also functions; see their docstrings.
|
|
;; (setq mu4e-sent-folder "/sent")
|
|
;; (setq mu4e-drafts-folder "/drafts")
|
|
;; (setq mu4e-trash-folder "/trash")
|
|
|
|
;; smtp mail setting; these are the same that `gnus' uses.
|
|
(setq
|
|
message-send-mail-function 'smtpmail-send-it
|
|
smtpmail-default-smtp-server "smtp.example.com"
|
|
smtpmail-smtp-server "smtp.example.com"
|
|
smtpmail-local-domain "example.com")
|
|
@end lisp
|
|
|
|
|
|
@node Longer configuration
|
|
@section Longer configuration
|
|
|
|
A somewhat longer configuration, showing some more things that you can
|
|
customize.
|
|
|
|
@lisp
|
|
;; example configuration for mu4e
|
|
(require 'mu4e)
|
|
|
|
;; use mu4e for e-mail in emacs
|
|
(setq mail-user-agent 'mu4e-user-agent)
|
|
|
|
;; the next are relative to the root maildir
|
|
;; (see `mu info`).
|
|
;; instead of strings, they can be functions too, see
|
|
;; their docstring or the chapter 'Dynamic folders'
|
|
(setq mu4e-sent-folder "/sent"
|
|
mu4e-drafts-folder "/drafts"
|
|
mu4e-trash-folder "/trash")
|
|
|
|
;; the maildirs you use frequently; access them with 'j' ('jump')
|
|
(setq mu4e-maildir-shortcuts
|
|
'(("/archive" . ?a)
|
|
("/inbox" . ?i)
|
|
("/work" . ?w)
|
|
("/sent" . ?s)))
|
|
|
|
;; a list of user's e-mail addresses
|
|
(setq mu4e-user-mail-address-list '("foo@@bar.example.com" "cuux@@example.com")
|
|
|
|
;; the headers to show in the headers list -- a pair of a field
|
|
;; and its width, with `nil' meaning 'unlimited'
|
|
;; (better only use that for the last field.
|
|
;; These are the defaults:
|
|
(setq mu4e-headers-fields
|
|
'( (:date . 25) ;; alternatively, use :human-date
|
|
(:flags . 6)
|
|
(:from . 22)
|
|
(:subject . nil))) ;; alternatively, use :thread-subject
|
|
|
|
;; program to get mail; alternatives are 'fetchmail', 'getmail'
|
|
;; isync or your own shellscript. called when 'U' is pressed in
|
|
;; main view.
|
|
|
|
;; If you get your mail without an explicit command,
|
|
;; use "true" for the command (this is the default)
|
|
(setq mu4e-get-mail-command "offlineimap")
|
|
|
|
;; general emacs mail settings; used when composing e-mail
|
|
;; the non-mu4e-* stuff is inherited from emacs/message-mode
|
|
(setq mu4e-compose-reply-to-address "foo@@bar.example.com"
|
|
user-mail-address "foo@@bar.example.com"
|
|
user-full-name "Foo X. Bar")
|
|
(setq mu4e-compose-signature
|
|
"Foo X. Bar\nhttp://www.example.com\n")
|
|
|
|
;; smtp mail setting
|
|
(setq
|
|
message-send-mail-function 'smtpmail-send-it
|
|
smtpmail-default-smtp-server "smtp.example.com"
|
|
smtpmail-smtp-server "smtp.example.com"
|
|
smtpmail-local-domain "example.com"
|
|
|
|
;; if you need offline mode, set these -- and create the queue dir
|
|
;; with 'mu mkdir', i.e.. mu mkdir /home/user/Maildir/queue
|
|
smtpmail-queue-mail nil
|
|
smtpmail-queue-dir "/home/user/Maildir/queue/cur")
|
|
|
|
;; don't keep message buffers around
|
|
(setq message-kill-buffer-on-exit t)
|
|
@end lisp
|
|
|
|
|
|
@node Gmail configuration
|
|
@section Gmail configuration
|
|
|
|
@emph{Gmail} is a popular e-mail provider; let's see how we can make it work
|
|
with @t{mu4e}. Since we are using @abbr{IMAP}, you must enable that in the
|
|
Gmail web interface (in the settings, under the ``Forwarding and
|
|
POP/IMAP''-tab).
|
|
|
|
Gmail users may also be interested in @ref{Including related messages},
|
|
and in @ref{Skipping duplicates}.
|
|
|
|
@subsection Setting up offlineimap
|
|
|
|
First of all, we need a program to get the e-mail from Gmail to our local
|
|
machine; for this we use @t{offlineimap}; on Debian (and derivatives like
|
|
Ubuntu), this is as easy as:
|
|
|
|
@verbatim
|
|
$ sudo apt-get install offlineimap
|
|
@end verbatim
|
|
|
|
while on Fedora (and similar) you need:
|
|
@verbatim
|
|
$ sudo yum install offlineimap
|
|
@end verbatim
|
|
|
|
Then, we can configure @t{offlineimap} by editing @file{~/.offlineimaprc}:
|
|
|
|
@verbatim
|
|
[general]
|
|
accounts = Gmail
|
|
maxsyncaccounts = 3
|
|
|
|
[Account Gmail]
|
|
localrepository = Local
|
|
remoterepository = Remote
|
|
|
|
[Repository Local]
|
|
type = Maildir
|
|
localfolders = ~/Maildir
|
|
|
|
[Repository Remote]
|
|
type = IMAP
|
|
remotehost = imap.gmail.com
|
|
remoteuser = USERNAME@gmail.com
|
|
remotepass = PASSWORD
|
|
ssl = yes
|
|
maxconnections = 1
|
|
@end verbatim
|
|
|
|
Obviously, you need to replace @t{USERNAME} and @t{PASSWORD} with your actual
|
|
Gmail username and password. After this, you should be able to download your
|
|
mail:
|
|
|
|
@verbatim
|
|
$ offlineimap
|
|
OfflineIMAP 6.3.4
|
|
Copyright 2002-2011 John Goerzen & contributors.
|
|
Licensed under the GNU GPL v2+ (v2 or any later version).
|
|
|
|
Account sync Gmail:
|
|
***** Processing account Gmail
|
|
Copying folder structure from IMAP to Maildir
|
|
Establishing connection to imap.gmail.com:993.
|
|
Folder sync [Gmail]:
|
|
Syncing INBOX: IMAP -> Maildir
|
|
Syncing [Gmail]/All Mail: IMAP -> Maildir
|
|
Syncing [Gmail]/Drafts: IMAP -> Maildir
|
|
Syncing [Gmail]/Sent Mail: IMAP -> Maildir
|
|
Syncing [Gmail]/Spam: IMAP -> Maildir
|
|
Syncing [Gmail]/Starred: IMAP -> Maildir
|
|
Syncing [Gmail]/Trash: IMAP -> Maildir
|
|
Account sync Gmail:
|
|
***** Finished processing account Gmail
|
|
@end verbatim
|
|
|
|
We can now run @command{mu} to make sure things work:
|
|
|
|
@verbatim
|
|
$ mu index
|
|
mu: indexing messages under /home/foo/Maildir [/home/foo/.mu/xapian]
|
|
| processing mail; processed: 520; updated/new: 520, cleaned-up: 0
|
|
mu: elapsed: 3 second(s), ~ 173 msg/s
|
|
mu: cleaning up messages [/home/foo/.mu/xapian]
|
|
/ processing mail; processed: 520; updated/new: 0, cleaned-up: 0
|
|
mu: elapsed: 0 second(s)
|
|
@end verbatim
|
|
|
|
We can run both the @t{offlineimap} and the @t{mu index} from within
|
|
@t{mu4e}, but running it from the command line makes it a bit easier to
|
|
troubleshoot as we are setting things up.
|
|
|
|
Note: when using encryption, you probably do @emph{not} want to
|
|
synchronize your Drafts-folder, since it contains the unencrypted
|
|
messages. You can use OfflineIMAP's @t{folderfilter} for that.
|
|
|
|
@subsection Settings
|
|
|
|
Next step: let's make a @t{mu4e} configuration for this:
|
|
|
|
@lisp
|
|
(require 'mu4e)
|
|
|
|
;; use mu4e for e-mail in emacs
|
|
(setq mail-user-agent 'mu4e-user-agent)
|
|
|
|
(setq mu4e-drafts-folder "/[Gmail].Drafts")
|
|
(setq mu4e-sent-folder "/[Gmail].Sent Mail")
|
|
(setq mu4e-trash-folder "/[Gmail].Trash")
|
|
|
|
;; don't save message to Sent Messages, Gmail/IMAP takes care of this
|
|
(setq mu4e-sent-messages-behavior 'delete)
|
|
|
|
;; (See the documentation for `mu4e-sent-messages-behavior' if you have
|
|
;; additional non-Gmail addresses and want assign them different
|
|
;; behavior.)
|
|
|
|
;; setup some handy shortcuts
|
|
;; you can quickly switch to your Inbox -- press ``ji''
|
|
;; then, when you want archive some messages, move them to
|
|
;; the 'All Mail' folder by pressing ``ma''.
|
|
|
|
(setq mu4e-maildir-shortcuts
|
|
'( ("/INBOX" . ?i)
|
|
("/[Gmail].Sent Mail" . ?s)
|
|
("/[Gmail].Trash" . ?t)
|
|
("/[Gmail].All Mail" . ?a)))
|
|
|
|
;; allow for updating mail using 'U' in the main view:
|
|
(setq mu4e-get-mail-command "offlineimap")
|
|
|
|
;; something about ourselves
|
|
(setq
|
|
user-mail-address "USERNAME@@gmail.com"
|
|
user-full-name "Foo X. Bar"
|
|
mu4e-compose-signature
|
|
(concat
|
|
"Foo X. Bar\n"
|
|
"http://www.example.com\n"))
|
|
|
|
;; sending mail -- replace USERNAME with your gmail username
|
|
;; also, make sure the gnutls command line utils are installed
|
|
;; package 'gnutls-bin' in Debian/Ubuntu
|
|
|
|
(require 'smtpmail)
|
|
(setq message-send-mail-function 'smtpmail-send-it
|
|
starttls-use-gnutls t
|
|
smtpmail-starttls-credentials '(("smtp.gmail.com" 587 nil nil))
|
|
smtpmail-auth-credentials
|
|
'(("smtp.gmail.com" 587 "USERNAME@@gmail.com" nil))
|
|
smtpmail-default-smtp-server "smtp.gmail.com"
|
|
smtpmail-smtp-server "smtp.gmail.com"
|
|
smtpmail-smtp-service 587)
|
|
|
|
;; alternatively, for emacs-24 you can use:
|
|
;;(setq message-send-mail-function 'smtpmail-send-it
|
|
;; smtpmail-stream-type 'starttls
|
|
;; smtpmail-default-smtp-server "smtp.gmail.com"
|
|
;; smtpmail-smtp-server "smtp.gmail.com"
|
|
;; smtpmail-smtp-service 587)
|
|
|
|
;; don't keep message buffers around
|
|
(setq message-kill-buffer-on-exit t)
|
|
@end lisp
|
|
|
|
And that's it --- put the above in your @file{~/.emacs}, change @t{USERNAME}
|
|
etc. to your own, and restart @command{emacs}, and run @kbd{M-x mu4e}.
|
|
|
|
@node CONF Other settings
|
|
@section Other settings
|
|
|
|
Finally, here are some more settings that are useful, but not enabled by
|
|
default for various reasons.
|
|
|
|
@lisp
|
|
;; use 'fancy' non-ascii characters in various places in mu4e
|
|
(setq mu4e-use-fancy-chars t)
|
|
|
|
;; save attachment to my desktop (this can also be a function)
|
|
(setq mu4e-attachment-dir "~/Desktop")
|
|
|
|
;; attempt to show images when viewing messages
|
|
(setq mu4e-view-show-images t)
|
|
@end lisp
|
|
|
|
@node FAQ
|
|
@appendix FAQ --- Frequently Asked Questions
|
|
|
|
In this chapter we list a number of actual and anticipated questions and their
|
|
answers.
|
|
|
|
@menu
|
|
* General::General questions and answers about @t{mu4e}
|
|
* Retrieving mail::Getting mail and indexing
|
|
* Reading messages::Dealing with incoming messages
|
|
* Writing messages::Dealing with outgoing messages
|
|
* Known issues::Limitations we know about
|
|
@end menu
|
|
|
|
@node General
|
|
@section General
|
|
|
|
@enumerate
|
|
@item @emph{Does @t{mu4e} provide context-sensitive help information?} Yes --- pressing @key{H}
|
|
should take you to the right section in this manual.
|
|
@item @emph{How can I quickly delete/move/trash a lot of messages?} You can
|
|
select ('mark' in @command{emacs}-speak) the messages like you would select
|
|
text in a buffer; the actions you then take (e.g., @key{DEL} for delete,
|
|
@key{m} for move and @key{t} for trash) apply to all selected messages. You
|
|
can also use functions like @code{mu4e-headers-mark-thread} (@key{T}),
|
|
@code{mu4e-headers-mark-subthread} (@key{t}) to mark whole threads at the same
|
|
time, and @code{mu4e-headers-mark-pattern} (@key{%}) to mark all messages
|
|
matching a certain regular expression.
|
|
@item @emph{@t{mu4e} seems to return a subset of all matches --- how can I
|
|
get them all?} For speed reasons, @t{mu4e} returns only up to the value
|
|
of the variable @code{mu4e-search-result-limit} (default: 500)
|
|
matches. To show @emph{all}, use @kbd{M-x
|
|
mu4e-headers-toggle-full-search} (@key{Q}), or customize the variable
|
|
@code{mu4e-headers-full-search}. This applies to all search commands.
|
|
@item @emph{Can I automatically apply the marks on messages when
|
|
leaving the headers buffer?} Yes you can --- see the documentation for the
|
|
variable @t{mu4e-headers-leave-behavior}.
|
|
@item @emph{How can I set @t{mu4e} as the default e-mail client in @command{emacs}?}
|
|
See @ref{Emacs default}.
|
|
@item @emph{Can @t{mu4e} use some fancy Unicode characters instead of these
|
|
boring plain-ASCII ones?} Glad you asked! Yes, if you set
|
|
@code{mu4e-use-fancy-chars} to @t{t}, @t{mu4e} uses such fancy
|
|
characters in a number of places. Since not all fonts include all
|
|
characters, you may want to install the @t{unifont} and/or @t{symbola}
|
|
fonts on your system.
|
|
@item @emph{Can I start @t{mu4e} in the background?} Yes --- if you provide a
|
|
prefix-argument (@key{C-u}), @t{mu4e} starts, but does not show the
|
|
main-window.
|
|
@item @emph{Does @t{mu4e} support searching for CJK (Chinese-Japanese-Korean) characters?}
|
|
Yes, if you have @t{Xapian} 1.2.8 or newer, and set the environment
|
|
variable @t{XAPIAN_CJK_NGRAM} to non-empty before indexing, both when
|
|
using @t{mu} from the command-line and from @t{mu4e}.
|
|
@item @emph{How can I customize the function to select a folder?}
|
|
The @t{mu4e-completing-read-function} variable can be customized to select a
|
|
folder in any way. The variable can be set to a function that receives
|
|
five arguments, following @t{completing-read}. The default value is
|
|
@code{ido-completing-read}; to use emacs's default behavior, set the
|
|
variable to @code{completing-read}. Helm users can use the same value,
|
|
and by enabling @code{helm-mode} use helm-style completion.
|
|
@item @emph{I have a lot of Maildir folders, so regenerating them each time makes
|
|
things slow. What can I do?}
|
|
Set @code{mu4e-cache-maildir-list} to @code{t} (but make sure to read
|
|
its docstring).
|
|
@item @emph{How can I hide certain message from the search results?}
|
|
See the variable @code{mu4e-headers-hide-predicate}.
|
|
@item @emph{I'm getting an error 'Variable binding depth exceeds max-specpdl-size'
|
|
when using mu4e -- what can I do about it?} The error occurs because
|
|
@t{mu4e} is binding more variables than @t{emacs} allows for, by
|
|
default. You can avoid this by setting a higher value, e.g. by adding the
|
|
following to your configuration:
|
|
@lisp
|
|
(setq max-specpdl-size 5000)
|
|
@end lisp
|
|
@end enumerate
|
|
|
|
@node Retrieving mail
|
|
@section Retrieving mail
|
|
|
|
@enumerate
|
|
@item @emph{How can I get notifications when receiving mail?} There is
|
|
@code{mu4e-index-updated-hook}, which gets triggered when the indexing
|
|
process triggered sees an update (not just new mail though). To use this
|
|
hook, put something like the following in your setup (assuming you have
|
|
@t{aplay} and some soundfile, change as needed):
|
|
@lisp
|
|
(add-hook 'mu4e-index-updated-hook
|
|
(defun new-mail-sound ()
|
|
(shell-command "aplay ~/Sounds/boing.wav&")))
|
|
@end lisp
|
|
@item @emph{It seems my headers-buffer is automatically updated when new
|
|
messages are found during the indexing process --- can I disable this
|
|
somehow?} Yes --- set @code{mu4e-headers-auto-update} to @code{nil}.
|
|
@item @emph{I don't use @t{offlineimap}, @t{fetchmail} etc., I get my mail
|
|
through my own mailserver. What should I use for
|
|
@code{mu4e-get-mail-command}}? Use the literal string @t{"true"} (or
|
|
don't do anything, it's the default) which then uses @t{/bin/true} (a
|
|
command that does nothing and always succeeds). This makes getting mail
|
|
a no-op, but the messages are still re-indexed.
|
|
@item @emph{How can I re-index my messages without getting new mail?}
|
|
Use @kbd{M-x mu4e-update-index}
|
|
@item @emph{When I try to run @t{mu index} while @t{mu4e} is running I get
|
|
errors like:}
|
|
@verbatim
|
|
mu: mu_store_new_writable: xapian error
|
|
'Unable to get write lock on ~/.cache/mu/xapian: already locked
|
|
@end verbatim
|
|
@emph{What to do about this?} You get this error because the underlying
|
|
Xapian database is locked by some other process; it can be opened only once in
|
|
read-write mode. There is not much @t{mu4e} can do about this, but if is
|
|
another @command{mu} instance that is holding the lock, you can ask it to
|
|
(gracefully) terminate:
|
|
@verbatim
|
|
pkill -2 -u $UID mu # send SIGINT
|
|
sleep 1
|
|
mu index
|
|
@end verbatim
|
|
@t{mu4e} automatically restarts @t{mu} when it needs it. In practice, this
|
|
seems to work quite well.
|
|
@item @emph{I don't like the @t{Indexing...} messages that the indexing process
|
|
gives me. Can I turn them off?}. Yes: set the variable
|
|
@code{mu4e-hide-index-messages} to non-@t{nil}.
|
|
@item @emph{Some IMAP-synchronization programs such as @t{mbsync} (but not
|
|
@t{offlineimap}) don't like it when message files do not change their names
|
|
when they are moved to different folders. Can @t{mu4e} somehow accommodate
|
|
this?} Yes --- you can set the variable @code{mu4e-change-filenames-when-moving}
|
|
to non-@t{nil}.
|
|
@item @emph{@command{offlineimap} uses IMAP's UTF-7 for encoding
|
|
non-ascii folder names, while @t{mu} expects UTF-8 (so, e.g. @t{/まりも
|
|
えお}@footnote{some Japanese characters} becomes
|
|
@t{/&MH4wijCCMEgwSg-}). How can I make @t{mu4e} display such folders
|
|
correctly?} This is best solved by telling @command{offlineimap} to use
|
|
UTF-8 instead --- see
|
|
@url{https://github.com/djcb/mu/issues/68#issuecomment-8598652}.
|
|
@item @emph{@t{mbsync} or @t{offlineimap} do not sync properly with my web-mail
|
|
provider (such as gmail) -- what can I do about it?} Unfortunately,
|
|
@t{mbsync} and/or @t{offlineimap} do not always agree with @t{mu} about
|
|
the meaning of various Maildir-flags. If you encounter unexpected
|
|
behavior, it is recommended you check before and after a sync-operation.
|
|
|
|
If the problem only shows up @emph{after} sync'ing, the problem is with
|
|
the sync-program, and it's most productive to complain there. Otherwise,
|
|
there have been quite a few related queries on the mailing-list;
|
|
worthwhile to check out.
|
|
@end enumerate
|
|
|
|
@node Reading messages
|
|
@section Reading messages
|
|
|
|
@enumerate
|
|
@item @emph{How can I view attached images in my message view buffers?} See
|
|
@ref{Viewing images inline}.
|
|
@item @emph{How can I word-wrap long lines in when viewing a
|
|
message?} You can toggle between wrapped and non-wrapped states using
|
|
@key{w}. If you want to do this automatically, invoke @code{visual-line-mode} in
|
|
your @code{mu4e-view-mode-hook}.
|
|
@item @emph{How can I perform custom actions on messages and attachments?} See
|
|
@ref{Actions}.
|
|
@item @emph{Does @t{mu4e} support crypto (i.e., decrypting messages and
|
|
verifying signatures)?} Yes --- if @t{mu} was built with @t{GMime} 2.6
|
|
or later, it is possible to do both (note, only PGP/MIME is
|
|
supported). In the @ref{Main view} the support is indicated by a big
|
|
letter @t{C} on the right hand side of the @t{mu4e} version. See
|
|
@ref{Decryption} and @ref{Verifying signatures}. For encryption and
|
|
signing messages, see @ref{Writing messages}.
|
|
@item @emph{How can I prevent @t{mu4e} from automatically marking messages as `read' when I read them?}
|
|
Set @code{mu4e-view-auto-mark-as-read} to @code{nil}.
|
|
@item @emph{Does @t{mu4e} support including all related messages in a thread,
|
|
like Gmail does?} Yes --- see @ref{Including related messages}.
|
|
@item @emph{There seems to be a lot of duplicate messages --- how can I get rid
|
|
of them?} See @ref{Skipping duplicates}.
|
|
@item @emph{How can I use the @t{eww} browser to view rich-text messages?}
|
|
With a new enough emacs, this happens automatically. See @ref{Html2text
|
|
functions} for some details.
|
|
@item @emph{Some messages are almost unreadable in emacs --- can I view them in
|
|
an external web browser?} Indeed, airlines often send messages that
|
|
heavily depend on html and are hard to digest inside emacs. Fortunately,
|
|
there's an @emph{action} (@ref{Message view actions})
|
|
defined for this. Simply add to your configuration:
|
|
@lisp
|
|
(add-to-list 'mu4e-view-actions
|
|
'("ViewInBrowser" . mu4e-action-view-in-browser) t)
|
|
@end lisp
|
|
Now, when viewing such a difficult message, type @kbd{aV}, and the message
|
|
opens inside a webbrowser. You can influence the browser with
|
|
@code{browse-url-generic-program}; and see @ref{Privacy aspects}.
|
|
@item @emph{How can I read encrypted messages that I sent?}. Since you do not own the
|
|
recipient's key you typically cannot read those mails --- so the trick is
|
|
to encrypt outgoing mails with your key, too. This can be automated by
|
|
adding the following snippet to your configuration (courtesy of user
|
|
@t{kpachnis}):
|
|
@lisp
|
|
(require 'epg-config)
|
|
(setq mml2015-use 'epg
|
|
epg-user-id "gpg_key_id"
|
|
mml2015-encrypt-to-self t
|
|
mml2015-sign-with-sender t)
|
|
@end lisp
|
|
@item @emph{view-as-pdf seems to hang for some e-mails --- what can I do about that?}
|
|
Short answer: install @t{nspluginwrapper}. Longer answer: @t{mu} comes
|
|
with @t{msg2pdf}, which is a program used to convert the messages to
|
|
pdf, and which depends on WebKit, which in some cases needs
|
|
@t{nspluginwrapper} and it waits for a long time if it's not there. So,
|
|
installing @t{nspluginwrapper} prevents that.
|
|
@item @emph{Can I `bounce' or `resend' messages?}
|
|
Yes --- it is possible to edit a (copy of) an existing message and then
|
|
send it, using @code{M-x mu4e-compose-resend}. This gives you a raw copy
|
|
of the message, including all headers, encoded parts and so on. Reason
|
|
for this is that for resending, it is important not to change anything
|
|
(except perhaps for the @t{To:} address when bouncing); since we cannot
|
|
losslessly decode an existing message, you get the raw version.
|
|
|
|
@end enumerate
|
|
|
|
@node Writing messages
|
|
@section Writing messages
|
|
|
|
@enumerate
|
|
@item @emph{What's the deal with replies to messages I wrote myself?} Like
|
|
many other mail-clients, @t{mu4e} treats replies to messages you wrote
|
|
yourself as special --- these messages keep the same @t{To:} and @t{Cc:}
|
|
as the original message. This is to ease the common case of following up
|
|
to a message you wrote earlier.
|
|
@item @emph{How can I automatically set the @t{From:}-address for a
|
|
reply-message, based on some field in the original?} See @ref{Compose hooks}.
|
|
@item @emph{And what about customizable folders for draft messages, sent
|
|
messages, trashed messages, based on e.g. the @t{From:} header?} See
|
|
@ref{Dynamic folders}.
|
|
@item @emph{Can I define aliases for (groups of) e-mail addresses?} Sure -
|
|
see @ref{(emacs) Mail Aliases}.
|
|
@item @emph{How can I automatically add some header to an outgoing message?}
|
|
Once more, see @ref{Compose hooks}.
|
|
@item @emph{How can I influence the way the original message looks when
|
|
replying or inline forwarding?} Since @code{mu4e-compose-mode} derives from
|
|
@code{message-mode}, you can re-use many of its facilities.
|
|
@inforef{Insertion Variables,,message}.
|
|
@item @emph{How can I easily include attachments in the messages I write?}
|
|
You can drag-and-drop from your desktop; alternatively, you can use @t{dired}
|
|
--- see @ref{Dired}.
|
|
@item @emph{@t{mu4e} seems to remove myself from the @t{Cc:}-list; how can I
|
|
prevent that?} Set @code{mu4e-compose-keep-self-cc} to @t{t} in your
|
|
configuration.
|
|
@item @emph{How can I start a new message-thread from a reply?} Remove the @t{In-Reply-To} header,
|
|
and @t{mu4e} automatically removes the (hidden) @t{References} header as
|
|
well when sending it. This makes the message show up as a top-level
|
|
message rather than as a response.
|
|
@item @emph{How can I attach an existing message?} Use @code{mu4e-action-capture-message}
|
|
(i.e., @kbd{a c} in the headers view) to `capture' the to-be-attached
|
|
message, then when editing the message, use @kbd{M-x
|
|
mu4e-compose-attach-captured-message}.
|
|
@item @emph{How can I sign or encrypt messages?} You can do so using @command{emacs}'
|
|
MIME-support --- check the @t{Attachments}-menu while composing a
|
|
message. Also see @ref{Signing and encrypting}.
|
|
@item @emph{Can I use @t{BBDB} with @t{mu4e}?} Yes, with the current
|
|
(2015-06-23) development release of BBDB
|
|
@url{https://savannah.nongnu.org/projects/bbdb/}, or releases of BBDB
|
|
after 3.1.2.
|
|
@ref{BBDB}.
|
|
@item @emph{After sending some messages, it seems the buffer for these
|
|
messages stay around. How can I get rid of those?}
|
|
@lisp
|
|
(setq message-kill-buffer-on-exit t)
|
|
@end lisp
|
|
@item @emph{Sending big messages is slow and blocks emacs --- what can I do
|
|
about it?} For this, there's @url{https://github.com/jwiegley/emacs-async}
|
|
(also available from the Emacs package repository); add the following snippet
|
|
to your configuration:
|
|
@lisp
|
|
(require 'smtpmail-async)
|
|
(setq
|
|
send-mail-function 'async-smtpmail-send-it
|
|
message-send-mail-function 'async-smtpmail-send-it)
|
|
@end lisp
|
|
With this, messages are sent using a background Emacs instance.
|
|
|
|
A word of warning though, this tends to not be as reliable as sending
|
|
the message in the normal, synchronous fashion, and people have reported
|
|
silent failures, where mail sending fails for some reason without any
|
|
indication of that.
|
|
|
|
You can check the progress of the background by checking the
|
|
@t{*Messages*}-buffer, which should show something like:
|
|
@verbatim
|
|
Delivering message to "William Shakespeare" <will@example.com>...
|
|
Mark set
|
|
Saving file /home/djcb/Maildir/sent/cur/20130706-044350-darklady:2,S...
|
|
Wrote /home/djcb/Maildir/sent/cur/20130706-044350-darklady:2,S
|
|
Sending...done
|
|
@end verbatim
|
|
The first and final messages are the most important, and there may be
|
|
considerable time between them, depending on the size of the message.
|
|
@item @emph{Is it possible to compose messages in a separate frame?}
|
|
Yes --- set the variable @code{mu4e-compose-in-new-frame} to @code{t}.
|
|
@item @emph{How can I apply format=flowed to my outgoing messages, enabling
|
|
receiving clients that support this feature to reflow my paragraphs?}
|
|
Plain text emails with @t{Content-Type: text/plain; format=flowed} can
|
|
be reflowed (i.e. line endings removed, paragraphs refilled) by
|
|
receiving clients that support this standard. Clients that don't support
|
|
this, show them as is, which means this feature is truly non-invasive.
|
|
|
|
Here's an explanatory blog post which also shows why this is a desirable
|
|
feature: @url{https://mathiasbynens.be/notes/gmail-plain-text} (if you
|
|
don't have it, your mails mostly look quite bad especially on mobile
|
|
devices) and here's the RFC with all the details:
|
|
@url{https://www.ietf.org/rfc/rfc2646.txt}.
|
|
|
|
Since version 0.9.17, @t{mu4e} send emails with @t{format=flowed} by
|
|
setting
|
|
|
|
@lisp
|
|
(setq mu4e-compose-format-flowed t)
|
|
@end lisp
|
|
|
|
@noindent
|
|
in your Emacs init file (@file{~/.emacs} or @file{~/.emacs.d/init.el}).
|
|
The transformation of your message into the proper format is
|
|
done at the time of sending. For this to happen properly, you should
|
|
write each paragraph of your message of as a long line (i.e. without
|
|
carriage return). If you introduce unwanted newlines in your paragraph,
|
|
use @kbd{M-q} to reformat it as a single line.
|
|
|
|
If you want to send the message with paragraphs on single lines but
|
|
without @t{format=flowed} (because, say, the receiver does not
|
|
understand the latter as it is the case for Google or Github), use
|
|
@kbd{M-x use-hard-newlines} (to turn @code{use-hard-newlines} off) or
|
|
uncheck the box @t{format=flowed} in the @t{Text} menu when composing a
|
|
message.
|
|
@item @emph{How can force images to be shown at the end of my messages,
|
|
regardless of where I insert them?}
|
|
User Marcin Borkowski has a solution:
|
|
@lisp
|
|
(defun mml-attach-file--go-to-eob (orig-fun &rest args)
|
|
"Go to the end of buffer before attaching files."
|
|
(save-excursion
|
|
(save-restriction
|
|
(widen)
|
|
(goto-char (point-max))
|
|
(apply orig-fun args))))
|
|
|
|
(advice-add 'mml-attach-file :around #'mml-attach-file--go-to-eob)
|
|
@end lisp
|
|
|
|
@item @emph{How can I avoid Outlook display issues?}
|
|
|
|
Limited testing shows that certain Outlook clients do not work well
|
|
with inline replies, and the entire message including-and-below the
|
|
first quoted section is collapsed. This means recipients may not even
|
|
notice important inline text, especially if there is some top-posted
|
|
content. This has been observed on OS X, Windows, and Web-based
|
|
Outlook clients accessing Office 365.
|
|
|
|
It appears the bug is triggered by the standard reply regex "On ...
|
|
wrote:". Changing "On", or removing the trailing ":" appears to fix
|
|
the bug (in limited testing). Therefore, a simple work-around is to
|
|
set `message-citation-line-format` to something slightly non-standard,
|
|
such as:
|
|
@lisp
|
|
(setq message-citation-line-format "On %Y-%m-%d at %R %Z, %f wrote...")
|
|
@end lisp
|
|
@end enumerate
|
|
|
|
@node Known issues
|
|
@section Known issues
|
|
|
|
Although they are not really @emph{questions}, we end this chapter with
|
|
a list of known issues and/or missing features in @t{mu4e}. Thus, users
|
|
won't have to search in vain for things that are not there (yet), and
|
|
the author can use it as a todo-list.
|
|
|
|
@itemize
|
|
@item @emph{mu4e does not work well if the @command{emacs} language environment is not
|
|
UTF-8}; so, if you encounter problems with encodings, be sure to have
|
|
@code{(set-language-environment "UTF-8")} in your @file{~/.emacs}.
|
|
@item @emph{Thread handling is incomplete.} While threads are calculated and are
|
|
visible in the headers buffer, you cannot collapse/open them.
|
|
@item @emph{The key-bindings are @emph{somewhat} hard-coded.} That is, the main
|
|
menu assumes the default key-bindings, as do the clicks-on-bookmarks.
|
|
@item @emph{The @t{emacs} front-end of the @t{notmuch} e-mail indexer
|
|
conflicts with @t{mu4e}}. @t{notmuch} running in parallel with
|
|
@t{mu4e} leads to
|
|
@verbatim
|
|
error in process filter: mu4e-error-handler: Error 70: cannot read
|
|
~/Maildir/...
|
|
@end verbatim
|
|
when sending a reply to some e-mail. This seems to be caused by
|
|
@t{notmuch} changing the name of the original message file while
|
|
@t{mu4e} is working on it. To prevent this, deactivate @t{notmuch} in
|
|
your Emacs setup.
|
|
@item @emph{The PDF-version of the manual does not show any of the non-ASCII
|
|
characters} --- this is because the @t{texi2pdf} documentation system does
|
|
not support those. There is not much we can do about that.
|
|
@item @emph{@t{mu4e} can get very slow when using Aquamacs' default theme (May 2018} --
|
|
it's not clear what the root-cause for this is, but if you suffer from
|
|
this, you can try to put
|
|
@verbatim
|
|
(aquamacs-autoface-mode 0)
|
|
@end verbatim
|
|
in @t{site-start.el}.
|
|
@end itemize
|
|
|
|
For a more complete list, please refer to the issues-list in the
|
|
github-repository.
|
|
|
|
@node Tips and Tricks
|
|
@appendix Tips and Tricks
|
|
|
|
@menu
|
|
* Fancy characters:: Non-ascii characters in the UI
|
|
* Refiling messages:: Moving message to some archive folder
|
|
* Saving outgoing messages:: Automatically save sent messages
|
|
* Confirmation before sending:: Check messages before sending
|
|
@end menu
|
|
|
|
@node Fancy characters
|
|
@section Fancy characters
|
|
|
|
When using `fancy characters' (@code{mu4e-use-fancy-chars}) with the
|
|
@emph{Inconsolata}-font (and likely others as well), the display may be
|
|
slightly off; the reason for this issue is that Inconsolata does not
|
|
contain the glyphs for the `fancy' arrows and the glyphs that are used
|
|
as replacements are too high.
|
|
|
|
To fix this, you can use something like the following workaround (in
|
|
your @t{.emacs}-file):
|
|
@lisp
|
|
(if (equal window-system 'x)
|
|
(progn
|
|
(set-fontset-font "fontset-default" 'unicode "Dejavu Sans Mono")
|
|
(set-face-font 'default "Inconsolata-10")))
|
|
@end lisp
|
|
|
|
Other fonts with good support for Unicode are @t{unifont} and
|
|
@t{symbola}.
|
|
|
|
For a more complete solution, but with greater overhead, you can also
|
|
try the @emph{unicode-fonts} package:
|
|
@lisp
|
|
(require 'unicode-fonts)
|
|
(require 'persistent-soft) ; To cache the fonts and reduce load time
|
|
(unicode-fonts-setup)
|
|
@end lisp
|
|
|
|
@node Refiling messages
|
|
@section Refiling messages
|
|
|
|
By setting @code{mu4e-refile-folder} to a function, you can dynamically
|
|
determine where messages are to be refiled. If you want to do this based
|
|
on the subject of a message, you can use a function that matches the
|
|
subject against a list of regexes in the following way. First, set up a
|
|
variable @code{my-mu4e-subject-alist} containing regexes plus associated
|
|
mail folders:
|
|
|
|
@lisp
|
|
(defvar my-mu4e-subject-alist '(("kolloqui\\(um\\|a\\)" . "/Kolloquium")
|
|
("Calls" . "/Calls")
|
|
("Lehr" . "/Lehre")
|
|
("webseite\\|homepage\\|website" . "/Webseite"))
|
|
"List of subjects and their respective refile folders.")
|
|
@end lisp
|
|
|
|
Now you can use the following function to automatically refile messages
|
|
based on their subject line:
|
|
|
|
@lisp
|
|
(defun my-mu4e-refile-folder-function (msg)
|
|
"Set the refile folder for MSG."
|
|
(let ((subject (mu4e-message-field msg :subject))
|
|
(folder (or (cdar (member* subject my-mu4e-subject-alist
|
|
:test #'(lambda (x y)
|
|
(string-match (car y) x))))
|
|
"/General")))
|
|
folder))
|
|
@end lisp
|
|
|
|
Note the @t{"/General"} folder: it is the default folder in case the
|
|
subject does not match any of the regexes in
|
|
@code{my-mu4e-subject-alist}.
|
|
|
|
In order to make this work, you'll of course need to set
|
|
@code{mu4e-refile-folder} to this function:
|
|
|
|
@lisp
|
|
(setq mu4e-refile-folder 'my-mu4e-refile-folder-function)
|
|
@end lisp
|
|
|
|
If you have multiple accounts, you can accommodate them as well:
|
|
|
|
@lisp
|
|
(defun my-mu4e-refile-folder-function (msg)
|
|
"Set the refile folder for MSG."
|
|
(let ((maildir (mu4e-message-field msg :maildir))
|
|
(subject (mu4e-message-field msg :subject))
|
|
folder)
|
|
(cond
|
|
((string-match "Account1" maildir)
|
|
(setq folder (or (catch 'found
|
|
(dolist (mailing-list my-mu4e-mailing-lists)
|
|
(if (mu4e-message-contact-field-matches
|
|
msg :to (car mailing-list))
|
|
(throw 'found (cdr mailing-list)))))
|
|
"/Account1/General")))
|
|
((string-match "Gmail" maildir)
|
|
(setq folder "/Gmail/All Mail"))
|
|
((string-match "Account2" maildir)
|
|
(setq folder (or (cdar (member* subject my-mu4e-subject-alist
|
|
:test #'(lambda (x y)
|
|
(string-match
|
|
(car y) x))))
|
|
"/Account2/General"))))
|
|
folder))
|
|
@end lisp
|
|
|
|
This function actually uses different methods to determine the refile
|
|
folder, depending on the account: for @emph{Account2}, it uses
|
|
@code{my-mu4e-subject-alist}, for the @emph{Gmail} account it simply uses the
|
|
folder ``All Mail''. For Account1, it uses another method: it files the
|
|
message based on the mailing list to which it was sent. This requires
|
|
another variable:
|
|
|
|
@lisp
|
|
(defvar my-mu4e-mailing-lists
|
|
'(("mu-discuss@@googlegroups.com" . "/Account1/mu4e")
|
|
("pandoc-discuss@@googlegroups.com" . "/Account1/Pandoc")
|
|
("auctex@@gnu.org" . "/Account1/AUCTeX"))
|
|
"List of mailing list addresses and folders where
|
|
their messages are saved.")
|
|
@end lisp
|
|
|
|
@node Saving outgoing messages
|
|
@section Saving outgoing messages
|
|
|
|
Like @code{mu4e-refile-folder}, the variable @code{mu4e-sent-folder} can also
|
|
be set to a function, in order to dynamically determine the save folder. One
|
|
might, for example, wish to automatically put messages going to mailing lists
|
|
into the trash (because you'll receive them back from the list anyway). If you
|
|
have set up the variable @code{my-mu4e-mailing-lists} as mentioned, you can
|
|
use the following function to determine a save folder:
|
|
|
|
@lisp
|
|
(defun my-mu4e-sent-folder-function (msg)
|
|
"Set the sent folder for the current message."
|
|
(let ((from-address (message-field-value "From"))
|
|
(to-address (message-field-value "To")))
|
|
(cond
|
|
((string-match "my.address@@account1.example.com" from-address)
|
|
(if (member* to-address my-mu4e-mailing-lists
|
|
:test #'(lambda (x y)
|
|
(string-match (car y) x)))
|
|
"/Trash"
|
|
"/Account1/Sent"))
|
|
((string-match "my.address@@gmail.com" from-address)
|
|
"/Gmail/Sent Mail")
|
|
(t (mu4e-ask-maildir-check-exists "Save message to maildir: ")))))
|
|
@end lisp
|
|
|
|
Note that this function doesn't use @code{(mu4e-message-field msg
|
|
:maildir)} to determine which account the message is being sent from.
|
|
The reason is that the function in @code{mu4e-sent-folder} is
|
|
called when you send the message, but before @t{mu4e} has created the
|
|
message struct from the compose buffer, so that
|
|
@code{mu4e-message-field} cannot be used. Instead, the function uses
|
|
@code{message-field-value}, which extracts the values of the headers in
|
|
the compose buffer. This means that it is not possible to extract the
|
|
account name from the message's maildir, so instead the from address is
|
|
used to determine the account.
|
|
|
|
Again, the function shows three different possibilities: for the first
|
|
account (@t{my.address@@account1.example.com}) it uses
|
|
@code{my-mu4e-mailing-lists} again to determine if the message goes to a
|
|
mailing list. If so, the message is put in the trash folder, if not, it
|
|
is saved in @t{/Account1/Sent}. For the second (Gmail) account, sent
|
|
mail is simply saved in the Sent Mail folder.
|
|
|
|
If the from address is not associated with Account1 or with the Gmail
|
|
account, the function uses @code{mu4e-ask-maildir-check-exists} to ask
|
|
the user for a maildir to save the message in.
|
|
|
|
@node Confirmation before sending
|
|
@section Confirmation before sending
|
|
|
|
To protect yourself from sending messages too hastily, you can add a
|
|
final confirmation, which you can of course make as elaborate as you
|
|
wish.
|
|
|
|
@lisp
|
|
(add-hook 'message-send-hook
|
|
(lambda ()
|
|
(unless (yes-or-no-p "Sure you want to send this?")
|
|
(signal 'quit nil))))
|
|
@end lisp
|
|
|
|
Another option is to simply set @code{message-confirm-send} to
|
|
non-@t{nil} so the question ``Send message?'' is asked for confirmation.
|
|
|
|
@node How it works
|
|
@appendix How it works
|
|
|
|
While perhaps not interesting for all users of @t{mu4e}, some curious
|
|
souls may want to know how @t{mu4e} does its job.
|
|
|
|
@menu
|
|
* High-level overview::How the pieces fit together
|
|
* mu server::The mu process running in the background
|
|
* Reading from the server::Processing responses from the server
|
|
* The message s-expression::What messages look like from the inside
|
|
@end menu
|
|
|
|
@node High-level overview
|
|
@section High-level overview
|
|
|
|
At a high level, we can summarize the structure of the @t{mu4e} system using
|
|
some ascii-art:
|
|
|
|
@cartouche
|
|
@example
|
|
+---------+
|
|
| emacs |
|
|
| +------+
|
|
+----| mu4e | --> send mail (smtpmail)
|
|
+------+
|
|
| A
|
|
V | ---/ search, view, move mail
|
|
+---------+ \
|
|
| mu |
|
|
+---------+
|
|
| A
|
|
V |
|
|
+---------+
|
|
| Maildir | <--- receive mail (fetchmail,
|
|
+---------+ offlineimap, ...)
|
|
@end example
|
|
@end cartouche
|
|
|
|
In words:
|
|
@itemize
|
|
@item Your e-mail messages are stored in a Maildir-directory
|
|
(typically, @file{~/Maildir} and its subdirectories), and new mail comes in
|
|
using tools like @t{fetchmail}, @t{offlineimap}, or through a local mail
|
|
server.
|
|
@item @t{mu} indexes these messages periodically, so you can quickly search for
|
|
them. @t{mu} can run in a special @t{server}-mode, where it provides services
|
|
to client software.
|
|
@item @t{mu4e}, which runs inside @command{emacs} is
|
|
such a client; it communicates with @command{mu} (in its @t{server}-mode) to
|
|
search for messages, and manipulate them.
|
|
@item @t{mu4e} uses the facilities
|
|
offered by @command{emacs} (the Gnus message editor and @t{smtpmail}) to send
|
|
messages.
|
|
@end itemize
|
|
|
|
@node mu server
|
|
@section @t{mu server}
|
|
|
|
@t{mu4e} is based on the @t{mu} e-mail searching/indexer. The latter
|
|
is a C++-program; there are different ways to communicate with a
|
|
client that is emacs-based.
|
|
|
|
One way to implement this, would be to call the @t{mu} command-line
|
|
tool with some parameters and then parse the output. In fact, that was
|
|
the first approach --- @t{mu4e} would invoke e.g., @t{mu find} and
|
|
process the output in @command{emacs}.
|
|
|
|
However, with this approach, we need to load the entire e-mail
|
|
@emph{Xapian} database (in which the message is stored) for each
|
|
invocation. Wouldn't it be nicer to keep a running @t{mu} instance
|
|
around? Indeed, it would --- and thus, the @t{mu server} sub-command
|
|
was born. Running @t{mu server} starts a simple shell, in which you
|
|
can give commands to @command{mu}, which then spits out the
|
|
results/errors. @command{mu server} is not meant for humans, but it
|
|
can be used manually, which is great for debugging.
|
|
|
|
@node Reading from the server
|
|
@section Reading from the server
|
|
|
|
In the design, the next question was what format @t{mu} should use for its
|
|
output for @t{mu4e} (@command{emacs}) to process. Some other programs use
|
|
@abbr{JSON} here, but it seemed easier (and possibly, more efficient) just to
|
|
talk to @command{emacs} in its native language: @emph{s-expressions}, and
|
|
interpret those using the @command{emacs}-function
|
|
@code{read-from-string}. See @ref{The message s-expression} for details on the
|
|
format.
|
|
|
|
So, now let's look at how we process the data from @t{mu server} in
|
|
@command{emacs}. We'll leave out a lot of details, @t{mu4e}-specifics, and look
|
|
at a bit more generic approach.
|
|
|
|
The first thing to do is to create a process (for example, with
|
|
@code{start-process}), and then register a filter function for it, which is
|
|
invoked whenever the process has some data for us. Something like:
|
|
|
|
@lisp
|
|
(let ((proc (start-process <arguments>)))
|
|
(set-process-filter proc 'my-process-filter)
|
|
(set-process-sentinel proc 'my-process-sentinel))
|
|
@end lisp
|
|
|
|
Note, the process sentinel is invoked when the process is terminated
|
|
--- so there you can clean things up. The function
|
|
@code{my-process-filter} is a user-defined function that takes the
|
|
process and the chunk of output as arguments; in @t{mu4e} it looks
|
|
something like (pseudo-lisp):
|
|
|
|
@lisp
|
|
(defun my-process-filter (proc str)
|
|
;; mu4e-buf: a global string variable to which data gets appended
|
|
;; as we receive it
|
|
(setq mu4e-buf (concat mu4e-buf str))
|
|
(when <we-have-received-a-full-expression>
|
|
<eat-expression-from mu4e-buf>
|
|
<evaluate-expression>))
|
|
@end lisp
|
|
|
|
@code{<evaluate-expression>} de-multiplexes the s-expression we got.
|
|
For example, if the s-expression looks like an e-mail message header,
|
|
it is processed by the header-handling function, which appends it to
|
|
the header list. If the s-expression looks like an error message, it
|
|
is reported to the user. And so on.
|
|
|
|
The language between frontend and backend is documented partly in the
|
|
@t{mu-server} man-page and more completely in the output of @t{mu
|
|
server --commands}.
|
|
|
|
@t{mu4e} can log these communications; you can use @kbd{M-x
|
|
mu4e-toggle-logging} to turn logging on and off, and you can view the
|
|
log using @kbd{M-x mu4e-show-log} (@key{$}).
|
|
|
|
@node The message s-expression
|
|
@section The message s-expression
|
|
|
|
A typical message s-expression looks something like the following:
|
|
|
|
@lisp
|
|
(:docid 32461
|
|
:from (("Nikola Tesla" . "niko@@example.com"))
|
|
:to (("Thomas Edison" . "tom@@example.com"))
|
|
:cc (("Rupert The Monkey" . "rupert@@example.com"))
|
|
:subject "RE: what about the 50K?"
|
|
:date (20369 17624 0)
|
|
:size 4337
|
|
:message-id "C8233AB82D81EE81AF0114E4E74@@123213.mail.example.com"
|
|
:path "/home/tom/Maildir/INBOX/cur/133443243973_1.10027.atlas:2,S"
|
|
:maildir "/INBOX"
|
|
:priority normal
|
|
:flags (seen)
|
|
:parts ( (:index 1 :mime-type "text/plain" :size 12345 :attachment nil)
|
|
(:index 2 :name "photo.jpg" :mime-type "image/jpeg"
|
|
:size 147331 :attachment t)
|
|
(:index 3 :name "book.pdf" :mime-type "application/pdf"
|
|
:size 192220 :attachment t))
|
|
:references ("C8384574032D81EE81AF0114E4E74@@123213.mail.example.com"
|
|
"38203498230942D81EE81AF0114E4E74@@123213.mail.example.com")
|
|
:in-reply-to "38203498230942D81EE81AF0114E4E74@@123213.mail.example.com"
|
|
:body-txt "Hi Tom,
|
|
....
|
|
")
|
|
@end lisp
|
|
|
|
This s-expression forms a property list (@t{plist}), and we can get values
|
|
from it using @t{plist-get}; for example @code{(plist-get msg :subject)} would
|
|
get you the message subject. However, it's better to use the function
|
|
@code{mu4e-message-field} to shield you from some of the implementation
|
|
details that are subject to change; and see the other convenience functions in
|
|
@file{mu4e-message.el}.
|
|
|
|
Some notes on the format:
|
|
@itemize
|
|
@item The address fields are @emph{lists} of pairs @code{(name . email)},
|
|
where @t{name} can be @t{nil}.
|
|
@item The date is in format @command{emacs} uses (for example in
|
|
@code{current-time}).@footnote{Emacs 32-bit integers have only 29 bits
|
|
available for the actual number; the other bits are use by
|
|
@command{emacs} for internal purposes. Therefore, we need to split
|
|
@t{time_t} in two numbers.}
|
|
@item Attachments are a list of elements with fields @t{:index} (the number of
|
|
the MIME-part), @t{:name} (the file name, if any), @t{:mime-type} (the
|
|
MIME-type, if any) and @t{:size} (the size in bytes, if any).
|
|
@item Messages in the @ref{Headers view} come from the database and do not have
|
|
@t{:attachments}. @t{:body-txt} or @t{:body-html} fields. Message in the
|
|
@ref{Message view} use the actual message file, and do include these fields.
|
|
@end itemize
|
|
|
|
@subsection Example: ping-pong
|
|
|
|
As an example of the communication between @t{mu4e} and @command{mu},
|
|
let's look at the @t{ping-pong}-sequence. When @t{mu4e} starts, it
|
|
sends a command @t{ping} to the @t{mu server} backend, to learn about
|
|
its version. @t{mu server} then responds with a @t{pong} s-expression
|
|
to provide this information (this is implemented in
|
|
@file{mu-cmd-server.c}).
|
|
|
|
We start this sequence when @t{mu4e} is invoked (when the program is
|
|
started). It calls @t{mu4e-proc-ping}, and registers a (lambda) function for
|
|
@t{mu4e-proc-pong-func}, to handle the response.
|
|
|
|
@verbatim
|
|
-> (ping)
|
|
<-<prefix>(:pong "mu" :props (:version "x.x.x" :doccount 78545))
|
|
@end verbatim
|
|
|
|
When we receive such a @t{pong} (in @file{mu4e-proc.el}), the lambda
|
|
function we registered is called, and it compares the version we got
|
|
from the @t{pong} with the version we expected, and raises an error if
|
|
they differ.
|
|
|
|
@node Debugging
|
|
@appendix Debugging
|
|
|
|
As explained in @ref{How it works}, @t{mu4e} communicates with its backend
|
|
(@t{mu server}) by sending commands and receiving responses (s-expressions).
|
|
|
|
For debugging purposes, it can be very useful to see this data. For
|
|
this reason, @t{mu4e} can log all these messages. Note that the
|
|
`protocol' is documented to some extent in the @t{mu-server} manpage.
|
|
|
|
You can enable (and disable) logging with @kbd{M-x
|
|
mu4e-toggle-logging}. The log-buffer is called @t{*mu4e-log*}, and in
|
|
the @ref{Main view}, @ref{Headers view} and @ref{Message view},
|
|
there's a keybinding @key{$} that takes you there. You can quit it by
|
|
pressing @key{q}.
|
|
|
|
Logging can be a bit resource-intensive, so you may not want to leave
|
|
it on all the time. By default, the log only maintains the most recent
|
|
1200 lines. @t{mu} itself keeps a log as well, you can find it in
|
|
@t{<MUHOME>/mu.log}, on Unix typically @t{~/.cache/mu/mu.log}.
|
|
|
|
@node GNU Free Documentation License
|
|
@appendix GNU Free Documentation License
|
|
|
|
@include fdl.texi
|
|
|
|
@bye
|