path: root/mu4e/mu4e.texi

\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-@value{UPDATED-YEAR} 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 @code{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 for version @value{VERSION}
@end ifnottex

@iftex
@node Welcome to mu4e
@unnumbered Welcome to mu4e
@end iftex

Welcome to @code{mu4e}!

@code{mu4e} (@t{mu}-for-emacs) is an e-mail client for GNU Emacs version 26.3 or
newer, built on top of the @uref{https://www.djcbsoftware.nl/code/mu,mu} e-mail
search engine. @code{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 @code{mu4e}, do some
basic configuration and explain its daily use. We also show you how you
can customize @code{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 configurations}. There's also a section
with answers to frequently asked questions, @ref{FAQ}.

@menu
* Introduction:: Where to begin
* Getting started:: Setting things up
* Main view:: The @code{mu4e} overview
* Headers view:: Lists of message headers
* Message view:: Viewing specific messages
* Composer:: Creating and 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 @code{mu4e}
* SCM/Guile:: Using @command{mu}'s SCM/Guile integration
* Integration:: Integrating @code{mu4e} with Emacs facilities

Appendices
* Other tools:: @code{mu4e} and the rest of the world
* Example configurations:: 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 @code{mu4e}
* Debugging:: How to debug problems in @code{mu4e}
* GNU Free Documentation License::  The license of this manual

Indices
@c * Command Index::       An item for each standard command name.
@c * Variable Index::      An item for each variable documented in this manual.
* Concept Index::       Index of @code{mu4e} concepts and other general subjects.

@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 @code{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 (@code{mu4e}'s 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.

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 (@code{mu}), it seemed only logical to use that as a
basis.

@node Other mail clients
@section Other mail clients

Under the hood, @code{mu4e} is fully search-based, similar to programs like
@uref{https://notmuchmail.org/,notmuch} and
@uref{https://supmua.dev/,sup}.
@cindex notmuch
@cindex sup

However, @code{mu4e}'s user-interface is quite different. @code{mu4e}'s mail
handling (deleting, moving, etc.)@: is inspired by
@uref{https://github.com/wanderlust/wanderlust,wanderlust} (another Emacs-based
e-mail client), @uref{http://www.mutt.org/,mutt} and the @code{dired}
file-manager for emacs.
@cindex wanderlust
@cindex mutt

@code{mu4e} keeps all the `state' in your maildirs, so you can easily switch
between clients, synchronize over @abbr{IMAP}, backup with @t{rsync} and so on.
The Xapian-database that @code{mu} maintains is merely a @emph{cache}; if you
delete it, you won't lose any information.

@node What mu4e does not do
@section What @code{mu4e} does not do

There are a number of things that @code{mu4e} does @b{not} do, by design:
@itemize
@item @code{mu}/@code{mu4e} do @emph{not} get your e-mail messages from
a mail server. Nor does it sync-back any changes. Those tasks are delegated to
other tools, such as @uref{https://www.offlineimap.org/,offlineimap},
@uref{http://isync.sourceforge.net/,mbsync} or
@uref{http://www.fetchmail.info/,fetchmail}; As long as the messages end up in a
maildir, @code{mu4e} and @code{mu} are happy to deal with them.
@item @code{mu4e} also does @emph{not} implement sending of messages; instead, it depends on
@ref{(smtpmail) Top}, which is part of Emacs. In addition, @code{mu4e} piggybacks
on Gnus' message editor.
@end itemize

Thus, many of the things an e-mail client traditionally needs to do, are
delegated to other tools. This leaves @code{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 @code{mu4e} user

If @code{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 @code{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 @code{mu4e} into use, it's a good idea to subscribe to the
@uref{https://groups.google.com/group/mu-discuss,mu/mu4e mailing list}.

Sometimes, you might encounter some unexpected behavior while using @code{mu4e}, or
have some idea on how it could work better. To report this, you can use the
@uref{https://github.com/djcb/mu/issues,bug-tracker}. Please always include the
following information:

@itemize
@item What did you expect or wish to happen? what actually happened?
Please describe in detail what you saw; what did you expect to happen and what
actually happened? Also, please try some related scenarios and whether the
problem either @emph{always} happens, or only @emph{sometimes}. E.g., the issue
might happen with only one particular type of message
@item Provide some exact steps to reproduce?
In particular, some minimal steps, starting from @t{emacs -Q} and with minimal
configuration. If the problem is easily producible, it may be easily fixable as
well; but if it's some subtle interaction in a highly complex setup, we cannot
do much.
@item What version of @code{mu4e} and @command{emacs} were you using? What operating system?
Always try with up-to-date versions. And please use the 'normal' @code{mu4e} for
reproducing your problem, not the ``remix'' version that some Emacs
``distributions'' use, such as ``Doom Emacs''.
@item Can you reproduce it with @command{emacs -q} and only loading @code{mu4e}?
@item If the problem is related to some specific message, please include the
raw message file (appropriately anonymized, of course)
@end itemize

In general, imagine you would be the person receiving the bug-report, and think
about the information you would need to diagnose the problem.

@node Getting started
@chapter Getting started

In this chapter, we go through the installation of @code{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, @code{mu4e} should be ready to go!

@menu
* Requirements:: What is needed
* Versions:: Available stable and development versions
* Installation:: How to install @code{mu} and @code{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 @code{mu4e}
* Folders::  Setting up standard folders
* Retrieval and indexing:: Doing it from @code{mu4e}
* Sending mail:: How to send mail
* Running mu4e:: Overview of the @code{mu4e} views

@end menu

@node Requirements
@section Requirements
@cindex requirements
@code{mu}/@code{mu4e} are known to work on a wide variety of Unix- and Unix-like
systems, including many Linux distributions, OS X and FreeBSD. Emacs 28.1 or
higher is required, as well as @uref{https://xapian.org/,Xapian} and
@uref{http://spruce.sourceforge.net/gmime/,GMime}.
@cindex GMime
@cindex Xapian

@code{mu} has optional support for the Guile (Scheme) programming language (version
3.0 or higher). There are also some GUI-toys, which require GTK+ 3.x and Webkit.

If you intend to compile @code{mu} yourself, you need to have the typical
development tools, such as C and C++17 compilers (both @command{gcc} and
@command{clang} work), @command{meson} 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 Versions
@section Versions

Over its lifetime, @t{mu} has experimented with different ways to deal with
development and release versions, trying to find the balance between getting new
functionality to users quickly, and minimizing the risk of introducing
regressions.

Currently (the 1.12.x series), all feature development happens on @t{master},
with pre-releases having a version with a @t{-pre<n>} suffix, e.g.,
@t{1.12.14-pre4}. Every few months this is wrapped up in a release (on Github)
@emph{without} that suffix, e.g. @t{1.12.14}.

The version strings are parseble through Emacs' @code{version-to-list}.

@node Installation
@section Installation

@code{mu4e} is part of @code{mu} --- by installing the latter, the former is
installed as well. Some Linux distributions provide packaged versions of
@code{mu}/@code{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.

@subsection Dependencies

The first step is to get some build dependencies. The details depend a
bit on your system's setup / distribution.
@itemize
@item On Debian/Ubuntu and derivatives:
@example
$ sudo apt-get install git meson libgmime-3.0-dev libxapian-dev emacs
@end example
@item On Fedora and related:
@example
$ sudo dnf install git meson gmime30-devel xapian-core-devel emacs
@end example
@item Otherwise, install the equivalent of the above on your system
@end itemize

@subsection Getting mu

The next step is to get the @code{mu} sources. There are two alternatives:
@itemize
@item @emph{Use a stable release} --- download a release from
@url{https://github.com/djcb/mu/releases}
@item @emph{Use an experimental development version} --- get it from the repository,
and @t{git clone https://github.com/djcb/mu.git}
@end itemize

@subsection Building mu

With all that in place, let's build and install @code{mu} and @code{mu4e}.
Enter the directory where you unpacked or cloned @code{mu}. Then:

@example
$ meson setup build
$ meson compile -C build
$ meson install -C build
@end example

For old-time's sake, alternatively you can do:

@example
$ ./autogen.sh && make
$ sudo make install
@end example

@subsection Installation

After this, @code{mu} and @code{mu4e} should be installed @footnote{there's a
hard dependency between versions of @code{mu4e} and @code{mu} --- you cannot
combine different versions} on your system, and be available from the
command line and in Emacs.

You may need to restart Emacs, so it can find @code{mu4e} in its
@code{load-path}. If, even after restarting, Emacs cannot find @code{mu4e},
you may need to add it to your @code{load-path} explicitly; check where
@code{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 Emacs customization system in
@code{mu4e}, but for now, we recommend setting the values manually. Please
refer to @ref{Example configurations} for a couple of examples of this; here we
go through things step-by-step.

@node Getting mail
@section Getting mail
@cindex mail retrieval
In order for @code{mu} (and, by extension, @code{mu4e}) to work, you need to have your
e-mail messages stored in a
@uref{https://en.wikipedia.org/wiki/Maildir, 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 @command{getmail},
@command{fetchmail}, @command{offlineimap} or @command{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 @code{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 @command{postfix} or @command{qmail}), you can teach them to deliver
into a maildir as well, maybe in combination with @command{procmail}. A bit of
googling should be able to provide you with the details.
@end itemize

While a @code{mu} only supports a single Maildir, it can be spread across
different file-systems; and symbolic links are supported.

@node Initializing the message store
@section Initializing the message store

The first time you run @code{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. Alternatively, you can use an
environment variable @env{MUHOME}.

Assuming that your maildir is at @file{~/Maildir}, we issue the
following command:
@example
  $ mu init --maildir=~/Maildir
@end example

You can add some e-mail addresses, so @code{mu} recognizes them as yours:

@example
  $ mu init --maildir=~/Maildir --personal-address=jim@@example.com \
    --personal-address=bob@@example.com
@end example

(An older synonym for @t{--personal-address} is @t{--my-address}, which is still
supported).

@code{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.

The addresses may also be basic PCRE regular expressions, wrapped in slashes,
for example:
@example
  $ mu init --maildir=~/Maildir '--personal-address=/foo-.*@@example\.com/'
@end example

If you want to see the values for your message-store, you can use
@command{mu info}.

Note: unfortunately, PCRE regular expressions are not the same as Emacs regular
expressions. Very simple ones match, but e.g. @t{(foo|bar)} in PCRE syntax is
specified as @t{\(foo\|bar\)} in Emacs/@code{mu4e}.

The good news is that @code{mu4e} can do the conversion automatically; however for
this to work, users needs to install the @t{pcre2el} package (available in
MELPA), and ensure it is available in @t{load-path} when Emacs runs (a normal
package-installation takes care of this). After that, @code{mu4e} takes care of the
translation automatically.

It is possible to come up with complicated PCRE regular expressions that are not
translatable; if necessary, experiment with @t{pcre2el} to avoid this.

@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 @code{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 @code{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 @code{mu4e}.

@node Basic configuration
@section Basic configuration

Before we can start using @code{mu4e}, we need to tell 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 Emacs complains that it cannot find @code{mu4e}, check your
@code{load-path} and make sure that @code{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
@cindex folders

The next step is to tell @code{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

The folder (maildir) names are all relative to the root-maildir (see the
output of @command{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
@cindex mail retrieval
@cindex indexing
As we have seen, we can do all of the mail retrieval @emph{outside} of
Emacs/@code{mu4e}. However, you can also do it from within
@code{mu4e}.

@subsection Basics

To set up mail-retrieval from within @code{mu4e}, set the variable
@code{mu4e-get-mail-command} to a shell command you want to use for retrieving
mail. It can also be a function which returns such a shell-command.

You can then get your e-mail using @kbd{M-x mu4e-update-mail-and-index}, or
@kbd{C-S-u} in all @code{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}, @code{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}.

After updating has completed, @code{mu4e} keeps the output in a buffer
@t{*mu4e-last-update*}, which you can use for diagnosis if needed.

@subsection Handling errors during mail retrieval

If the mail-retrieval process returns with a non-zero exit code,
@code{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 @t{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 Conditional mail retrieval

The value of @code{mu4e-get-mail-command} can also be a @emph{function} that
returns a shell command. This allows for more sophistication. For
instance, you may want to attempt to retrieve mail only when online.

Let us look at an example.

On many GNU/Linux systems the online-status an be checked using @emph{Network
Manager}'s @command{nm-online}, which returns non-zero when you are online.

Thus, we could use something like:
@lisp
(setq mu4e-get-mail-command
  (lambda ()
    (if (zerop (shell-command "nm-online -q"))
		"mbsync -a"
                "true")))
@end lisp

Of course, the can be customized to the particulars of your system.

@subsection Implicit mail retrieval

Not everyone needs to run a shell command for getting mail. For example, you may
be running your own mail-server, or you already have some other way to
periodically retrieve messages.

In that case, you can leave @code{mu4e-get-mail-command} at @t{"true"} (the
default), in which case @code{mu4e} does not attempt to retrieve new mail, but
still re-indexes your messages as per @code{mu4e-update-interval}.

@subsection Speeding up indexing
@anchor{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 is that it is relatively slow, something that
can be especially noticeable with large e-mail corpora on slow file-systems. 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. If it does not work
for you (e.g., @code{mu4e} fails to find some new messages), simply leave
at the default.

Note that you can occasionally run a thorough indexing round using
@code{mu4e-update-index-nonlazy}.

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

To influence the details, a hook @code{mu4e-update-pre-hook} is available, which
is called right before starting the process. It is also possible to set
@code{mu4e-get-mail-command} to a function which returns a command.

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

@code{mu4e} uses Emacs's @ref{(message) Top,,message-mode} for writing mail.

For sending mail using @abbr{SMTP}, @code{mu4e} uses @ref{(smtpmail)
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
configurations}.

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 @code{mu4e} (re)uses the same @t{message mode} and @t{smtpmail} that
Gnus uses, many settings for those also apply to @code{mu4e}.

@subsection Dealing with sent messages

By default, @code{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:
@lisp
;; don't save messages to Sent Messages, Gmail/IMAP takes care of this
(setq mu4e-sent-messages-behavior 'delete)
@end lisp
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 @code{mu4e} setup. Great! In the next chapters, we walk you
through the various views in @code{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 @code{mu4e} (@pxref{Getting started}), you can start it
with @kbd{M-x mu4e}. @code{mu4e} does some checks to ensure everything is set up
correctly, and then shows you the @code{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 and Maildirs: Bookmarks and Maildirs. 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 x.y.z

  Basics

        * [j]ump to some maildir
        * enter a [s]earch query
        * [C]ompose a new message

  Bookmarks

        * [bu] Unread messages      13085(+3)/13085
        * [bt] Today's messages
        * [bw] Last 7 days          53(+3)/128
        * [bp] Messages with images 75/2441

  Maildirs

        * [ja] /archive             2101/18837
        * [ji] /inbox               8(+2)/10
        * [jb] /bulk                33/35
        * [jB] /bulkarchive         179/2090
        * [jm] /mu                  694(+1)/17687
        * [jn] /sauron
        * [js] /sent

  Misc

        * [;]Switch context
        * [U]pdate email & database
        * toggle [m]ail sending mode (currently direct)
        * [f]lush 1 queued mail

        * [N]ews
        * [A]bout mu4e
        * [H]elp
        * [q]uit

  Info

        * last-updated        : Sat Dec 31 16:43:56 2022
        * database-path       : /home/pam/.cache/mu/xapian
        * maildir             : /home/pam/Maildir
        * in store            : 86179 messages
        * personal addresses  : /.*example.com/, pam@@example.com
@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''),
@code{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 @ref{Headers view}.
@item @t{enter a [s]earch query}: after pressing @key{s}, @code{mu4e} asks
you for a search query, and after entering one, shows the results in
@ref{Headers view}.
@item @t{[C]ompose a new message}: after pressing @key{C}, you are dropped in
the @ref{Composer} to write a new message.
@end itemize

@node Bookmarks and Maildirs
@section Bookmarks and Maildirs

The next two items in the Main view are @emph{Bookmarks} and @emph{Maildirs}.

Bookmarks are predefined queries with a descriptive name and a shortcut. In the
example above, we see the default bookmarks. You can pick a bookmark by pressing
@key{b} followed by the specific bookmark's shortcut. If you want to edit the
bookmarked query before invoking it, use @key{B}.

@cindex baseline
Next to each bookmark are some numbers that indicate the unread(delta)/all
matching messages for the given query, with the delta being the difference in
unread count since some ``baseline'', and only shown when this delta > 0.

Note that the ``delta'' has its limitations: if you, for instance, deleted 5
messages and received 5 new one, the ``delta'' would be 0, although there were
changes indeed. So it is mostly useful for tracking changes while you are
@emph{not} using @code{mu4e}. For this reason, you can reset the baseline manually,
e.g. by visiting the main view.

Furthermore, for speed reasons, the counts do @emph{not} exclude messages that
no longer exist in the file-system, nor do they exclude duplicate messages.

By comparing current results with the baseline, you can quickly see what new
messages have arrived since the last time you looked.

The baseline@footnote{For debugging, it can be useful to see the time for the
baseline --- for that, there is the @code{mu4e-baseline-time} command.} is reset
automatically when switching to the main view, or invoking @code{buffer-revert}
(@kbd{g}) while in the main-view. Visiting the ``favorite'' bookmark does the
same(explained below).

Bookmarks are stored in the variable @code{mu4e-bookmarks}; you can add
your own and/or replace the default ones; see @ref{Bookmarks}. For
instance:
@lisp
(add-to-list 'mu4e-bookmarks
  ;; add bookmark for recent messages on the Mu mailing list.
  '( :name "Mu7Days"
     :key  ?m
     :query "list:mu-discuss.googlegroups.com AND date:7d..now"))
@end lisp

There are optional keys @code{:hide} to hide the bookmark or maildirs from the
main menu, but still have it available (using @key{b})), and
@code{:hide-if-no-unread} to hide it if there are no unread messages.

To customize the display, there is also @code{:hide-unread} to avoid generating
the unread-number; that can be useful if you have bookmarks for slow queries.
Note that @code{:hide-unread} is implied when the query is not a string; this
for the common case where the query function involves some user input, which
would be disruptive in this case.

There is also the optional @code{:favorite} property, which at most one bookmark
should have; this bookmark is highlighted in the main view, and its
unread-status is shown in the modeline; see @ref{Modeline}, and you can enable
desktop notifications; see @ref{Desktop notifications}. We'd recommend creating
such a ``favorite'', which should match message that require your quick
attention:

@lisp
(add-to-list 'mu4e-bookmarks
  ;; bookmark for message that require quick attention
  '( :name "Urgent"
     :key  ?u
     :query "maildir:/inbox AND from:boss@@example.com"))
@end lisp

Note that @code{mu4e} resets the baseline when you are interacting with it (for
instance, when you visit the urgent bookmark, or when you go to the main view);
in such cases, there won't be any further notifications.

The @emph{Maildirs} item is very similar to Bookmarks --- consider maildirs here
as being a special kind of bookmark query that matches a Maildir. You can
configure this using the variable @code{mu4e-maildir-shortcuts}; see its
docstring and @ref{Maildir searches} for more details.

When you ask for bookmarks or maildirs through @code{mu4e-ask-bookmark},
@code{mu4e-ask-maildir}, the counts are displayed in the (default) completions
next to the maildir or bookmark entry. This is a shorter version of the full
display, just showing either the delta or the number of unread messages, if any.
If you do not want to see these counts, set @t{mu4e-hide-short-counts} to
non-@t{nil}.

@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 @code{mu}
database; see @ref{Indexing your messages} and @ref{Getting mail} for
details.
@item @t{[R]eset query-results baseline} this reset the current 'baseline'
for query and updates the screen; see @ref{Bookmarks and Maildirs}.
@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 @code{mu4e}-session
@footnote{@t{mu4e-quit}; or with a @t{C-u} prefix argument, it merely buries the
buffer. A hook @code{mu4e-quit-hook} is available as well}
@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 how headers are shown
* Folding threads:: Showing and hiding thread contents
* Custom headers: HV Custom headers. Adding your own headers
* Actions: HV Actions. Defining and using actions
* Buffer display:: How and where the buffers are displayed
@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 (@code{: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).
@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 own shortcuts. You can use @code{mu4e-mailing-list-patterns} to
specify generic shortcuts. For instance, to shorten list names to the
part before @t{-list}, you could use:
@lisp
(setq mu4e-mailing-list-patterns '("\\`\\([-_a-z0-9.]+\\)-list"))
@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, following
@uref{https://www.jwz.org/doc/threading.html,Jamie Zawinski's mail threading
algorithm}.
@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-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 @code{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
Emacs menu bar.

@verbatim
key          description
===========================================================
n,p          view the next, previous message
],[          move to the next, previous unread message
},{          move to the next, previous thread
y            select the message view (if 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
c            search query with completion
j            jump to maildir
M-left,\     previous query
M-right      next query

O            change sort order
P            toggle search property

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
l            mark for labels
?,!          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

threads
-------
S-left       goto root
TAB          toggle threading at current level
S-TAB        toggle all threading

composition
-----------
R,W,F,C      reply/reply-to-all/forward/compose
E            edit (only allowed for draft messages)

misc
----
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
C-c C-u      update mail & reindex
q            leave the headers buffer
@end verbatim

Some keybindings are available through minor modes:
@itemize
@item Context; see @pxref{Contexts}.
@item Composition; see @pxref{Composer} and @code{mu4e-compose-minor-mode}
@end itemize

@node HV Marking
@section Marking

You can @emph{mark} messages for a certain action, such as deletion or move or
changing the labels.

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. @code{dired} does. It is how @code{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, @code{mu4e} sorts messages by date, in descending order: the
most recent messages are shown at the top. In addition, by default
@code{mu4e} shows the message @emph{threads}, i.e., the tree structure
representing a discussion thread; this also affects the sort order:
the top-level messages are sorted by the date of the @emph{newest}
message in the thread.

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 column 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 through
@kbd{M-x mu4e-search-toggle-property} or @key{Pt}. 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}) through @kbd{M-x mu4e-search-toggle-property} as well; or
@key{Pf}.

Note that with threading enabled, the sorting is exclusively by date,
regardless of the column clicked.

If you want to change the defaults for these settings, you can use the variables
@code{mu4e-search-sort-field} and @code{mu4e-search-show-threads}, as well as
@code{mu4e-search-change-sorting} to change the sorting of the current search
results.

@node Folding threads
@section Folding threads

It is possible to fold threads --- that is, visually collapse threads into a
single line (and the reverse), by default using the @key{TAB} and @key{S-TAB}
bindings. Note that the collapsing is always for threads as a whole, not for
sub-threads.

Folding stops at the @emph{first unread message}, unless you set
@code{mu4e-thread-fold-unread}. Similarly, when a thread has marked messages,
the folding stops at the first marked message. Marking folded messages is not
allowed as it is too error-prone.

Thread-mode functionality is only available with @code{mu4e-search-threads}
enabled; this triggers a minor mode @code{mu4e-thread-mode} in the headers-view.
For now, this functionality is not available in the message view, due to the
conflicting key bindings.

If you want to automatically fold all threads after a query, you can use a hook:
@lisp
  (add-hook 'mu4e-thread-mode-hook #'mu4e-thread-fold-all)
@end lisp

By default, single-child threads are @emph{not} collapsed, since it would result
in replacing a single line with the collapsed one. However, if, for consistency,
you also want to fold those, you can use @code{mu4e-thread-fold-single-children}.

@node HV Custom headers
@section Custom headers

Sometimes the normal headers that @code{mu4e} offers (Date, From, To,
Subject, etc.)@: may not be enough. For these cases, @code{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 contents of the Jabber-ID header.

@lisp
(add-to-list 'mu4e-header-info-custom
 '(:jabber-id .
     ( :name "Jabber-ID"     ;; long name, as seen in the message-view
       :shortname "JID"      ;; short name, as seen in the headers view
       :help "The Jabber ID" ;; tooltip
       ;; uses mu4e-fetch-field which is rel. slow, so only appropriate
       ;; for mu4e-view-fields, and _not_ mu4e-headers-fields
       :function (lambda (msg)
           (or (mu4e-fetch-field msg "Jabber-ID") "")))))
@end lisp

You can then add the custom header to your @code{mu4e-headers-fields} or
@code{mu4e-view-fields}, just like the built-in headers. However, there is an
important caveat: when your custom header is in @code{mu4e-headers-fields}, the
function is invoked for each of your message headers in search results, and if
it is slow, would dramatically slow down @code{mu4e}.

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

@code{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 @code{mu4e} source distribution for more example
actions.

@node Buffer display
@section Buffer display

By default, @code{mu4e} will attempt to manage the display of its own buffers. For
headers and message views, the variable @code{mu4e-split-view} is @code{mu4e's}
built-in way to decide how and where they are shown.

@subsection Split view
You can control how @code{mu4e} displays its buffers, including @ref{Headers
view} and @ref{Message view}, by customizing @code{mu4e-split-view}. There
are several options available:

@itemize
@item @code{horizontal} (this is the default): display the message view below the
header view. Use @code{mu4e-headers-visible-lines} to set the number of
lines shown (default: 8).
@item @code{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 @code{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 @code{mu4e}'s main view with a minibuffer-prompt containing the same
information.
@item anything else: prefer reusing the same window, where possible.
@end itemize

Note that using a window-returning @emph{function} for @code{mu4e-split-view} is
no longer supported, instead you can use @code{display-buffer-alist}, see
the section on further display customization.

@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

@subsection Further customization

However, @code{mu4e}'s display rules are provisional; you can override them
easily by customizing @code{display-buffer-alist}, which governs how Emacs ---
and thus @code{mu4e} --- must display your buffers.

Let's look at some examples.

@subsection Fine-tuning the main buffer display

By default @code{mu4e}'s main buffer occupies the complete frame, but this can be
changed to use the current window:

@lisp
(add-to-list 'display-buffer-alist
             `(,(regexp-quote mu4e-main-buffer-name)
               display-buffer-same-window))
@end lisp

@subsection Fine-tuning headers buffer display

You do not need to configure @code{mu4e-split-view} for this to work. In the
absence of explicit rules to the contrary, @code{mu4e} will fall back on the value
you have set in @code{mu4e-split-view}.

Here is an example that displays the headers buffer in a side window to the
right. It occupies half of the width of the frame.

@lisp
(add-to-list 'display-buffer-alist
             `(,(regexp-quote mu4e-headers-buffer-name)
               display-buffer-in-side-window
               (side . right)
               (window-width . 0.5)))
@end lisp

You can type @key{C-x w s} to toggle the side windows to hide or show them at
will.

Note that you may need to customize @code{mu4e-view-rendered-hook} as well; by
default it contains @code{mu4e-resize-linked-headers-window} but you can set it
to @code{nil} if you want to handle manually (through
@code{display-buffer-alist}.

@node Message view
@chapter The message view

This chapter discusses the message view, the view for reading e-mail messages.

After selecting a message in @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}, which derives
from @code{gnus-article-mode}.

@menu
* Overview: MSGV Overview. What is the Message View
* Keybindings: MSGV Keybindings. Do things with your keyboard
* Rich-text and images: MSGV Rich-text and images. Reading rich-text messages
* Attachments and MIME-parts: MSGV Attachments and MIME-parts. Working with attachments and other MIME parts
* Custom headers: MSGV Custom headers. Your very own headers
* Actions: MSGV Actions. Defining and using actions
* Detaching & reattaching: MSGV Detaching and reattaching. Multiple message views.
* Mailing lists: MSGV Mailing lists. Subscribing and unsubscribing.
@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: Thu, 11 Feb 2021 12:59:30 +0200 (4 weeks, 3 days, 21 hours ago)
    Maildir: /inbox
    Attachments: [2. image/jpeg; DSCN4961.JPG]... [3. image/jpeg; DSCN4962.JPG]...

    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 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
},{          move to the next, previous thread
y            select the headers view (if 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
S            edit last query
/            narrow the search
b            search bookmark
B            edit bookmark before search
c            search query with completion
j            jump to maildir

O            change sort order
P            toggle search property

M-left       previous query
M-right      next query

marking messages
----------------
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
l            mark for labels
+,-          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,W,F,C      reply/reply-to-all/forward/compose
E            edit (only allowed for draft messages)

actions
-------
g            go to (visit) numbered URL (using `browse-url')
(or: <mouse-2> 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)
a            execute some custom action on the message
A            execute some custom action on the message's MIME-parts
J            jump to MIME part by its number

misc
----
z, Z         detach (or reattach) a message view to a headers buffer
.            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

Some keybindings are available through minor modes:
@itemize
@item Context; see @pxref{Contexts}
@item Composition; see @pxref{Composer} and @code{mu4e-compose-minor-mode}
@end itemize

For the marking commands, please refer to @ref{Marking messages}.

@node MSGV Rich-text and images
@section Reading rich-text messages
@cindex rich-text

These days, many e-mail messages contain rich-text (typically, HTML);
either as an alternative to a text-only version, or even as the only
option.

By default, mu4e tries to display the 'richest' option, which is the
last MIME-part of the alternatives. You can customize this to prefer
the text version, if available, with something like the following in
your configuration (and see the docstring for
@code{mm-discouraged-alternatives} for details):

@lisp
(with-eval-after-load "mm-decode"
  (add-to-list 'mm-discouraged-alternatives "text/html")
  (add-to-list 'mm-discouraged-alternatives "text/richtext"))
@end lisp

These influence both display of message and what is used when citing them in a
reply.

When displaying rich-text messages inline, @code{mu4e} (through @code{gnus})
uses the @code{shr} built-in HTML-renderer. If you're using a dark color
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

Note that you can switch between the HTML and text versions by
clicking on the relevant part in the messages headers; you can make it
even clearer by indicating them in the message itself, using:

@lisp
(setq gnus-unbuttonized-mime-types nil)
@end lisp

Note that you can jump to the relevant MIME-parts using
@code{mu4e-view-jump-to-mime-part}, which ask for the number or uses the
prefix-argument.

@subsection Inline images
When you run Emacs in graphical mode, by default images attached to
messages are shown inline in the message view buffer.

To disable this, set @code{gnus-inhibit-images} to @code{t}.  By default,
external images in HTML are not retrieved from external URLs because
they can be used to track you.

Apart from that, you can also control whether to load remote images;
since loading remote images is often used for privacy violations, by
default this is not allowed.

You can specify what URLs to block by setting
@code{gnus-blocked-images} to a regular expression or to a function
that will receive a single parameter which is not meaningful for
@code{mu4e}.

For example, to enable images in Github notifications, you could use
the following:

@lisp
(setq gnus-blocked-images
   (lambda(&optional _ignore)
     (if (mu4e-message-contact-field-matches
         (mu4e-message-at-point) :from "notifications@@github.com")
        nil ".")))
@end lisp

@code{mu4e} inherits the default @code{gnus-blocked-images} from Gnus and
ensures that it works with @code{mu4e} too. However, mu4e is not Gnus, so
if you have Gnus-specific settings for @code{gnus-blocked-images}, you
should verify that they have the desired effect in @code{mu4e} as
well.

Finally, for some message with big images it can be useful to enable buttons and
full display, e.g. for saving inline images. For this you can try @kbd{M-x
mu4e-view-show-mime-parts}. This can be a little slow.

@node MSGV Attachments and MIME-parts
@section Attachments and MIME-parts
@cindex attachments
@cindex mime-parts

Nowadays, typical e-mail messages can be thought of as a series of
``MIME-parts'', which are sections of the message. The most prominent of those
parts is the 'body', which is the main text of the message your are reading.

Other MIME-parts in the messages include @emph{attachments}.

@subsection Attachments
@cindex attachments

Many e-mail messages contain @emph{attachments}, which are MIME-parts that
encode files which you can extract.

@footnote{@code{mu} uses some heuristics to decide if a part should be treated
as an attachment; including @t{inline} parts that specify a filename. The
heuristic tries to balance false-positive and false-negatives, both of which are
possible}

To save attachments as files on your computer, @code{mu4e}'s message-view
offers the command @code{mu4e-view-save-attachments}; its default keybinding is
@key{e} (think @emph{extract}).

When point is on the attachment label in the message, e.g., on something that
looks like @t{[4. application/pdf; Some Document.pdf]...}, the Gnus' binding for
@kbd{e} prevails, which is @code{gnus-mime-view-part-externally}. You can of
course customize this in the usual (Emacs) way.

After invoking the command, you can enter the file names to save,
comma-separated, with completion support. Press @key{RET} to save the chosen
attachments as files to your computer. If you do not specify any attachments,
@emph{all} are saved.

@code{mu4e} determines the target directory, using the variable
@code{mu4e-attachment-dir} (which can be either file-system path or a function;
see its docstring for details. However, you can manually set the target by
calling @code{mu4e-view-save-attachments} with a prefix argument.

When completing the file names, @code{mu4e-view-completion-minor-mode} is
active, which offers @code{mu4e-view-complete-all} (bound to @key{C-c C-a} to
complete @emph{all} files@footnote{Except when using 'Helm'; in that case, use
the Helm-mechanism for selecting multiple}.

@code{mu4e-view-save-attachments} assumes unique filenames for the attachments,
which is requirement of the underlying completion mechanism works. If there are
duplicates, only one is recognized.

Furthermore, file names that match @code{crm-separator} (by default, commas) are
@emph{not} supported (see @code{completing-read-multiple} for further details). For
such corner-cases, it is recommended to use @code{mu4e-view-mime-part-action}
instead, which does not have this limitation.

@subsection Other MIME-parts

Not all MIME-parts are message bodies or attachments, and it can be useful to
operate on those other parts as well.

To do so, there is @code{mu4e-view-mime-part-action} (default key-binding
@key{A}). You can pass the number of the MIME-part (as seen in the message view)
as a prefix argument; otherwise you get to get to choose from a completion menu.

After choosing one or more MIME-parts, you can specify an action to apply to
them; see the variable @code{mu4e-view-mime-part-actions} for the possibilities.
You can add your own actions as well, see @ref{MIME-part actions} for an
example.

@node MSGV Custom headers
@section Custom headers
@cindex custom headers

Sometimes the normal headers (Date, From, To, Subject, etc.)@: may not be
enough. For these cases, @code{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}; @code{mu4e} defines a number of example actions.

@subsection MIME-part actions
MIME-part actions allow you to act upon MIME-parts in a message --- such as
attachments. These actions are defined and documented in
@code{mu4e-view-mime-part-actions}.

There are a number of built-in actions which may be a good starting point for
creating your own.

@node MSGV Detaching and reattaching
@section Detaching and reattaching messages

You can have multiple message views, but you must rename the view
buffer and detach it to stop @code{mu4e} from reusing it when you
navigate up or down in the headers buffer. If you have several view
buffers attached to a headers view, then @code{mu4e} may pick one at
random when it has to choose which one to display a message in.

To detach the message view from its linked headers buffer, type
@key{z}. A message will appear saying it is detached (or warn you if
it is already detached.)

Detached buffers are static; they cannot change the displayed message,
and no headers buffer will use a detached buffer to display its
messages. You can reattach a buffer to an live headers buffer by
typing @key{Z}.

You can freely rename a message view buffer --- such as with @key{C-x x
r} --- if you want a custom, non-randomized name.

Detached messages are often useful for workflows involving lots of
simultaneous messages.

You can @emph{tear off} the window a message is in and place it in a
new frame by typing @key{C-x w ^ f}. You can also detach a window and
put it in its own tab with @key{C-x w ^ t}.

@node MSGV Mailing lists
@section Mailing lists

In the message view (but not the headers vies), @code{mu4e} supports various
commands for dealing with mailing-lists, such as subscribing and unsubscribing.

@itemize
@item @code{gnus-mailing-list-subscribe}: subscribe to mailing-list
@item @code{gnus-mailing-list-unsubscribe}: unsubscribe from mailing-list
@item @code{gnus-mailing-list-help}: request help for mailing-list
@end itemize

These commands depend on the current message to contain the necessary
information for these commands.

@node Composer
@chapter Composer

Writing e-mail messages takes place in the Composer. @code{mu4e}'s re-uses much of
Gnus' @code{message-mode}.

Much of the @code{message-mode} functionality is available, as well as some
@code{mu4e}-specifics. See @ref{(message) Top} for details; not every setting is
necessarily also supported in @code{mu4e}.

The major mode for the composer is @code{mu4e-compose-mode}.

@menu
* Composer overview: Composer overview. What is the composer good for
* Entering the composer:: How to start writing messages
* Keybindings: Composer 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::Miscellaneous
@end menu

@node Composer 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 Entering the composer
@section Entering the composer

There are a few different ways to @emph{enter} the composer; i.e., from other
@code{mu4e} views or even completely outside.

If you want the composer to start in a new frame or window, you can configure
the variable @code{mu4e-compose-switch}; see its docstring for details.

@subsection New message

@cindex composing, new
You can start composing a completely new message with @code{mu4e-compose-new}
(with @kbd{N} from within @code{mu4e}.

@subsection Reply

@cindex composing,reply
To compose a reply to an existing message, you can use @code{mu4e-compose-reply}
(with @kbd{R}) from within the headers view or when looking at some specific
message.

@cindex composing, reply
@cindex composing, wide reply
@cindex composing, reply to all

If you want to reply to @emph{all} recipients of a message, there is
@code{mu4e-compose-wide-reply}, by default bound to @kbd{W}. This is often
called ``reply-to-all'', but @code{mu4e} follows the Gnus terminology ``wide
reply''.

By default, the reply will cite the message being replied to. If you do not want
that, you can set (or @code{let}-bind) @code{message-cite-function} to
@code{mu4e-message-cite-nothing}.

See @ref{(message) Reply} and @ref{(message) Wide Reply} for further details.

@code{mu4e-compose-reply-include-mime-types} specifies the MIME-types for
message attachments that should be included in replies, with the default set to
@code{"text/x-patch"}-- i.e., patches are included in replies, so you can
comment on them. Set to @code{nil} to disable.

@subsubsection Interactively deciding whom to reply to

In older @t{mu4e} versions, @code{mu4e-compose-reply} would @emph{ask} whether
you want to reply-to-all or not (there was no separate ``wide'' reply); if you
are nostalgic for that old behavior, you could add something like the following
to your configuration:
@lisp
(defun compose-reply-wide-or-not-please-ask ()
  "Ask whether to reply-to-all or not."
  (interactive)
  (mu4e-compose-reply (yes-or-no-p "Reply to all?")))

(define-key mu4e-compose-minor-mode-map (kbd "R")
  #'compose-reply-wide-or-not-please-ask)
@end lisp

@subsubsection Avoiding replying to self

If you want to exclude your own e-mail addresses when issueing ``wide-replies''
(a.k.a., ``reply-to-all''), you can use @code{message-dont-reply-to-names};
i.e.,
@lisp
(setq message-dont-reply-to-names #'mu4e-personal-or-alternative-address-p)
@end lisp

In order for this to work properly, you need to pass your address to @command{mu
init --personal-address=...} at database initialization time, and/or use
the variable @code{message-alternative-emails}.

@subsection Forward
@cindex composing, forward

You can @emph{forward} some existing message with @code{mu4e-compose-forward}
(bound to @kbd{F}) from within the headers view or when looking at some specific
message. For further details, see @ref{(message) Forwarding}.

To influence the way a message is forwarded, you can use the variables
@code{message-forward-as-mime} and @code{message-forward-show-mml}.

@subsection Supersede
@cindex composing, supersede

Occasionally, it can be useful to ``supersede'' a message you sent; for this,
there is @code{mu4e-compose-supersede}.

This drops you into a new message that is just like the old message (and a
@t{Supersedes:} message header). You can then edit this message and send it.

Superseding is only possible for messages @emph{you} sent, as determined by
@code{mu4e-personal-or-alternative-address-p}.

This wraps @code{message-supersede}.

@subsection Resend
@cindex composing, resend

You can re-send some existing message with @code{mu4e-compose-resend} from within
the headers view or when looking at some specific message.

This re-sends the message without letting you edit it, as per @ref{(message)
Resending}.


@node Composer Keybindings
@section Keybindings

@code{mu4e}'s composer 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 in graphical context)
C-c C-;      switch the context

(mu4e-specific)
C-S-u        update mail & re-index
@end verbatim

@node Address autocompletion
@section Address autocompletion

@code{mu4e} supports autocompleting addresses when composing e-mail messages.
@code{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 @code{mu4e-compose-complete-addresses} to @code{nil}.

This uses the Emacs machinery for showing and cycling through the candidate
addresses; it is active when looking at one of the contact fields in the message
header area.

It is also possible to use @code{mu4e}'s completion elsewhere in @code{emacs}. To
enable that, a function @code{mu4e-complete-contact} exists, which you can add to
@code{completion-at-point-functions}, see @ref{(elisp) Completion in Buffers}.
@code{mu4e} must be running for any completions to be available.

@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, @code{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 @code{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 the
@t{--personal-address} parameter to @t{mu init}.

@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-max} --- the maximum number of contacts to use.
This adds a hard limit to the 2000 (default) contacts; those are sorted by
recency / frequency etc. so should include the ones you most likely need.
@item @code{mu4e-contact-process-function} --- a function to rewrite or
exclude certain addresses.
@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}. @code{mu4e}
offers two hooks:
@itemize
@item @code{mu4e-compose-pre-hook}: this hook is run @emph{before} composition
starts; if you compose 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.
@item @code{mu4e-compose-post-hook}: this hook is run when we're done with
message compositions. See the docstring for details.
@end itemize

@noindent
As mentioned, @code{mu4e-compose-mode-hook} is especially useful for
editing-related settings:

Let's look at an 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

The 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

By default, @code{mu4e} moves point to some ``reasonable place'' before letting you
edit the message; if you want something else, see
@code{mu4e-compose-jump-to-reasonable-place}.


@noindent
For a more general discussion about extending @code{mu4e}, see @ref{Extending
mu4e}.

@node Signing and encrypting
@section Signing and encrypting
@cindex signing
@cindex encrypting
@cindex decrypting
@cindex crypto

Signing and encrypting of messages is possible using @ref{(emacs-mime) Top,
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}.

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.

You can influence what messages to encrypt or sign using
@code{mu4e-compose-crypto-policy}; see its docstring for details.


@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
@ref{Main view}.

To allow for queuing, you need to tell @code{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 @code{mu4e}. The @command{mu mkdir} command may be useful here,
so for example:

@example
$ mu mkdir ~/Maildir/queue
$ touch ~/Maildir/queue/.noindex
@end example

The file created by the @command{touch} command tells @code{mu} to ignore this
directory for indexing, which makes sense since it contains @code{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 information you want to append to every message.

The text to include is
set with @code{message-signature} (older @code{mu4e} used
@code{mu4e-compose-signature}, but that has been obsoleted).

@node Other settings
@section Other settings

@itemize
@item If you want to use @code{mu4e} as Emacs' default program for sending mail,
see @ref{Default email client}.
@item Normally, @code{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
@end itemize

@node Searching
@chapter Searching

@code{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-search-toggle-property}, or by customizing the
variable @code{mu4e-search-full}. 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

@code{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 @code{mu} sees them}. You can consult the
@code{mu-query} man-page for the details. In addition, @code{mu4e} provides a
command @code{mu4e-analyze-last-query}, which shows how the @code{mu} server has
interpreted the query, similar to what the @t{--analyze} option does for
@t{mu find}.

Additionally, @code{mu4e} supports @kbd{TAB}-completion for queries. There is
completion for all search keywords such as @code{and}, @code{from:}, or
@code{date:} and also for certain values, i.e., the possible values for
@code{flag:}, @code{prio:}, @code{mime:}, and @code{maildir:}.

Let's look at some examples here.

@itemize

@item Get all messages regarding @emph{bananas}:
@example
bananas
@end example

@item Get all messages regarding @emph{bananas} from @emph{John} with an attachment:
@example
from:john and flag:attach and bananas
@end example

@item Get all messages with subject @emph{wombat} in June 2017
@example
subject:wombat and date:20170601..20170630
@end example

@item Get all messages with PDF attachments in the @t{/projects} folder
@example
maildir:/projects and mime:application/pdf
@end example

@item Get all messages about @emph{Rupert} in the @t{/Sent Items} folder. Note that
maildirs with spaces must be quoted.
@example
"maildir:/Sent Items" and rupert
@end example

@item Get all important messages which are signed:
@example
flag:signed and prio:high
@end example

@item Get all messages from @emph{Jim} without an attachment:
@example
from:jim and not flag:attach
@end example

@item Get all messages with Alice in one of the contacts-fields (@t{to}, @t{from},
@t{cc}, @t{bcc}):
@example
contact:alice
@end example

@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, ...)
@example
subject:Ångström and flag:unread
@end example

@item Get all unread messages between Mar-2012 and Aug-2013 about some bird:
@example
date:20120301..20130831 and nightingale and flag:unread
@end example

@item Get today's messages:
@example
date:today..now
@end example

@item Get all messages we got in the last two weeks regarding @emph{emacs}:
@example
date:2w.. and emacs
@end example

@item Get messages from the @emph{Mu} mailing list:
@example
list:mu-discuss.googlegroups.com
@end example

Note --- in @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:
@example
subject:soc*
@end example

@item Get all messages @emph{not} sent to a mailing-list:
@example
NOT flag:list
@end example

@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:
@example
file:pic*
@end example

@item Get all messages with PDF-attachments:
@example
mime:application/pdf
@end example

Get all messages with image attachments, and note that the `*' wildcard can
only appear as the term's rightmost character:
@example
mime:image/*
@end example

Get all messages with files that end in @t{.ppt}; this uses the
regular-expression support, which is powerful but relatively slow:
@example
file:/\.ppt$/
@end example

@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

@code{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"
      :hide-unread t
      :key ?w)
    ( :name "Messages with images"
      :query "mime:image/*"
      :key ?p))
  "List of predefined queries that are shown on the main screen.

Each of the list elements is a plist with at least:
`:name'  - the name of the query
`:query' - the query expression string or function

Likely, you also want to assign a shortcut key;
`:key'   - the shortcut key (single character)

Furthermore, you can add the following:

- `:favorite' - if t, monitor the results of this query, and make
it eligible for showing its status in the modeline. At most
one bookmark should have this set to t (otherwise the _first_
bookmark is the implicit favorite). The query for the `:favorite'
item must be unique among `mu4e-bookmarks' and
`mu4e-maildir-shortcuts'.
- `:hide' - if t, the bookmark is hidden from the main-view and
speedbar.
- `:hide-if-no-unread' - if t, the shortcut is hidden from
   the main-view if it contains no unread messages.

You can also use:
- `:hide-unread' - do not show the counts of
unread/total number of matches for the query in the main-view.
This can be useful if a bookmark uses a very slow query.

`:hide-unread' is implied from `:hide'.

Note: for efficiency, queries used to determine the unread/all
counts do not discard duplicate or unreadable messages. Thus, the
numbers shown may differ from the number you get from a normal
query."
  :type '(repeat (plist))
  :group 'mu4e-bookmarks)
@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 @code{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-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 @ref{Main view},
@ref{Headers view}, and @ref{Message view}, with the key @key{j}
(@code{mu4e-jump-to-maildir}). If a prefix argument is given, the maildir
query can be refined before execution.

@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,
@code{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
  '( (:maildir "/inbox"     :key  ?i)
     (:maildir "/archive"   :key  ?a)
     (:maildir "/lists"     :key  ?l)
     (:maildir "/work"      :key  ?w)
     (:maildir "/sent"      :key  ?s)
     (:maildir "/lists/project/project_X" :key ?x :name "Project X")))
@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 @code{mu4e}
starts; if there are changes in the maildirs while @code{mu4e} is running, you
need to restart @code{mu4e}. Optionally, you can specify a name to be displayed
in the main view.

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 @code{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}.

For further customization, you can use @code{:hide}, @code{:hide-if-no-unread},
@code{:hide-unread} and @code{:favorite} properties, just like for
@ref{Bookmarks and Maildirs}.

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

@code{mu4e} tries to be smart and not record duplicate queries. Also, the number
of queries remembered has a fixed limit, so @code{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-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-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-search-results-limit} may show up in the narrowed query.

@subsection Including related messages
@anchor{Including related messages}

It can be useful not only to show the messages that directly match a certain
query, but also to 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-search-include-related} to @code{t}, and you can toggle between
including/not-including using @key{P} (@code{mu4e-search-toggle-property}).

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-search-skip-duplicates} to @code{t}, and you can toggle
the value using @key{P} (@code{mu4e-search-toggle-property}).

Note, messages are considered duplicates when they have the same
@t{Message-Id}.

@node Marking
@chapter Marking

In @code{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 from both @ref{Headers view} and @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::Marking messages for removal
* 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 @ref{Headers view} or @ref{Message view}
@item @emph{region}: you can put a mark on all messages in the current region
(selection) in @ref{Headers view}
@item @emph{pattern}: you can put a mark on all messages in @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. When you haven't enabled separate
threads in the headers view, the thread marking functions simply mark @emph{all}
messages.
@end itemize

@node What to mark for
@section What to mark for

@code{mu4e} supports a number of marks:

@cartouche
@verbatim
mark for/as  | keybinding  | description
-------------+-------------+------------------------------
delete       | D, <delete> | delete
move         | m           | move to some maildir
refile       | r           | mark for refiling
-------------+-------------+------------------------------
flag         | +           | mark as 'flagged' ('starred')
unflag       | -           | remove 'flagged' mark
read         | !           | mark as read
unread       | ?           | marks as unread
trash        | d           | move to the trash folder
untrash      | =           | remove 'trash' flag
-------------+-------------+------------------------------
label        | l           | change the labels
unlabel      | L           | clear all labels
action       | a           | apply some action
'something'  | *, <insert> | mark now, decide later
-------------+-------------------------------------------
unmark       | u           | remove mark at point
unmark all   | U           | remove all marks
-------------+-------------------------------------------
@end verbatim
@end cartouche

@itemize
@item @emph{delete} deletes the message from database and file-system
@item @emph{move} moves the message to some different maildir
@item @emph{refile} is similar to @emph{move}, but determines the target maildir based
on the characteristics of the message; this is very powerful. See
@code{mu4e-refile-folder} and especially see @ref{Smart refiling} for details.
@item @emph{flag}/@emph{unflag}, @emph{read}/@emph{unread} and @emph{trash}/@emph{untrash}
set or unset the corresponding Maildir flags
@item @emph{label} lets you enter a label delta expression which gets applied; see below
@item @emph{unlabel} lets you clear @emph{all} labels; see below
@item @emph{action} lets you apply some pre-defined action on the message,
as per @code{mu4e-headers-actions}
@item @emph{'something'} marks the message for ``something'', and then decide
later what this something should be; see below
@item @emph{unmark} and @emph{unmark all} are ``meta'' marks,
which remove the mark from the currently selected message(s) or all
@end itemize

@node Applying and clearing labels
@subsection Applying and clearing labels
@cindex labels

The @t{plabel} mark lets you apply @emph{labels} to messages, which are short
strings to attach to this message which you can query using the @t{label:}
field.

To see them in your headers / message views, you need to add @code{:labels} to
the @code{mu4e-headers-fields} and/or @code{mu4e-view-fields}, respectively.

For instance:
@lisp
(setq mu4e-headers-fields
   '((:human-date      .  10)
     (:flags           .  4)
     (:from-or-to      .  20)
     (:mailing-list    .  8)
     (:maildir         .  8)
     (:labels          .  8)
     (:thread-subject  .  nil)))
(setq mu4e-view-fields
   '(:from :date :to :cc :bcc :subject
     :flags  :maildir
     :message-id :labels))
@end lisp

To change the labels for some message, you specify a @emph{label expression},
which consists of a space-separated sequence of labels, each prefixed with
either a @t{+} to add the label, or @t{-} to remove it.

For instance, to remove the @t{boring} label and add @t{urgent} to the message
at point or the messages in region, press @kbd{l} and enter:
@example
+urgent -boring
@end example

For clearing @emph{all} labels, you can mark with @kbd{L} ('unlabel').

You can search for labels using the @t{label:} field. For instance,
@t{label:urgent} retrieves all messages labeled @t{urgent}.

@emph{Important}: the labels are only stored in the database (the message files
are not changed). This means that you would @emph{loose} this information when
you remove the database and recreate it, @emph{unless} you @emph{export} the
labels before removing the database and re-@emph{import} them after re-creating
and re-indexing it; see the @command{mu-labels} man-page for further details.

@subsection Doing @emph{something}

@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 @code{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, @code{mu4e}
will ask you when you try to execute the marks (@key{x}).

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


@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

When ``trashing'' a message, it is moved to a trash-folder (i.e.,
@code{mu4e-trash-folder}) and is flagged as ``trashed'' (a ``T'' is added to its
filename).

Following the Maildir specification, this flag is to be interpreted as ``marked
for manual removal later''. However, some mail retrieval and IMAP
synchronization programs interpret this instead as a trigger for
@emph{immediate} removal.

For such cases, you can influence @code{mu4e}'s behavior; see
@code{mu4e-trash-without-flag}.

@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), @code{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 @code{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, @code{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 @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 @code{msg} and @code{param}.
@code{msg} is the message plist (see @ref{Message functions}) and @code{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 (@code{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 by adding elements to 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 the symbols @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 @code{nil}, the
@t{TARGET} passed to @code{:dyn-target} is @code{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 @code{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 @code{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


@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
@end menu

It can be useful to switch between different sets of settings in
@code{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 @code{mu4e}-specific mechanism to allow
for that; users can define different @i{contexts} with corresponding
groups of setting and either manually switch between them, or let
@code{mu4e} determine the right context based on some user-provided
function.

Note that there are a number of existing ways to switch accounts in
@code{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 a Lisp object with the following members:
@itemize
@item @t{name}: the name of the context, e.g. @t{work} or @t{private}.
In the default completion UI, @code{mu4e} uses the first letter of the context
to select them, so you should ensure all start with a different letter
@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 cleaning things up.
@item @t{match-func}:
an (optional) function that takes an @t{MSG} message plist as argument,
and returns non-@code{nil} if this context matches the situation. @code{mu4e}
uses the first context that matches, in a couple of situations:
@itemize
@item when starting @code{mu4e} to determine the
starting context; in this case, @t{MSG} is nil. You can use e.g. the host name
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 @code{nil} when
composing a brand new message. The function should return @t{t} when
this context is the right one for this message, or @code{nil} otherwise.
@item when determining the target folders for deleting, refiling etc;
see @ref{Contexts and special folders}.
@end itemize
@end itemize

@code{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 @code{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 @code{mu4e} can't figure
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 change contexts with @kbd{M-x
mu4e-context-switch}.
@end itemize

You can easily switch contexts manually using the @kbd{;} key from
the main screen.

@node Contexts and special folders
@section Contexts and special folders

As we discussed in @ref{Folders} and @ref{Dynamic folders}, @code{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 @code{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
@code{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" )
                   ( message-user-organization . "Homebase" )
                   ( message-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" )
                   ( message-user-organization . "Miskatonic University" )
                   ( message-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" )
                   ( message-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 @kbd{M-x mu4e-context-switch},
by default bound to @kbd{;} in headers, view and main mode. The current context
appears in the modeline by default; see @ref{Modeline} for details.
@item Normally, @kbd{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 @code{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 @code{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 @code{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 Dynamic folders
@chapter Dynamic folders

In @ref{Folders}, we explained how you can set up @code{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 messages
@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 @code{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 messages --- 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 some specific address go to /private
      ((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
      ((mu4e-message-sent-by-me msg)
       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 matche. 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 @code{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,
forward, or edit. If there is no such message (for example when composing a
brand new message) the message parameter is @code{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 @code{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 @code{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

@code{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 @code{mu4e} for specific needs --- for example,
marking messages as spam in a spam filter or applying a source code patch from
an attachment.

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 @code{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
* MIME-part actions::Doing things with MIME-parts such as 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-mime-part-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; @code{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
@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-search
    (concat "from:"
      (mu4e-contact-email (car (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{car}, remember that the @t{From:}-field
is a list of @code{(:name NAME :email EMAIL)} plists; so this code gets
us the e-mail address of the first in the list. @t{From:}-fields rarely
have more that one address.

@node MIME-part actions
@section MIME-part actions

Finally, let's define a MIME-part action.

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). See the @code{mu4e-view-mime-part-actions} for the details of
the format.

@lisp
(add-to-list 'mu4e-view-mime-part-actions
    ;; count the number of lines in a MIME-part
    '(:name "line-count" :handler "wc -l" :receives pipe))
@end lisp

Or another one, to import a calendar invitation into the venerable emacs diary:
@lisp
(add-to-list 'mu4e-view-mime-part-actions
    ;; import into calendar;
    '(:name "dimport-in-diary" :handler (lambda(file) (icalendar-import-file file diary-file))
      :receives temp))
@end lisp

@node Example actions
@section Example actions

@code{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 tagging.

@cindex tagging
It is easy to add such actions to your configuration; for instance, to enable
@emph{tagging}@footnote{@code{mu4e} does not offer tagging by default since it
mutates the message files, something that @code{mu}/@code{mu4e} generally tries
to avoid. An alternative to tagging is @emph{labeling}, see @ref{Applying and
clearing labels}}, you could add:
@lisp
(add-to-list 'mu4e-headers-actions
             '("Tag message" . mu4e-action-retag-message))
(add-to-list 'mu4e-view-actions
             '("Tag message" . mu4e-action-retag-message))
@end lisp

@node Extending mu4e
@chapter Extending mu4e

@code{mu4e} is designed to be easily extensible --- that is, write your own
emacs-lisp to make @code{mu4e} behave exactly as you want. Here, we provide some
guidelines for doing so.

@menu
* Extension points::Where to hook into @code{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 @code{mu4e} lets you plug in your own
functions:
@itemize
@item Custom functions for message header --- see @ref{HV 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 a MIME-part --- see @ref{MIME-part 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-mime-parts} (a list of 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 @code{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~} or
@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} with the same prefix; don't touch them. Let
me repeat that:
@verbatim
Do not use mu4e~... or 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 @code{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;
@code{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

@node Contact functions
@section Contact functions

It can sometimes be useful to discard or rewrite the contact information
that @code{mu4e} provides, for example to fix spelling errors, or omit
unwanted contacts.

To handle this, @code{mu4e} provides @code{mu4e-contact-process-function},
which, if defined, is applied to each contact. If the result is @code{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 @code{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-personal-addresses)}).
@item @code{mu4e-log} logs to the @code{mu4e} debugging log if it is enabled;
see @code{mu4e-toggle-logging}.
@item @code{mu4e-message}, @code{mu4e-warning}, @code{mu4e-error} are the
@code{mu4e} equivalents of the normal elisp @code{message},
@code{user-error} and @code{error} functions.
@end itemize

@node SCM/Guile
@chapter Using @command{mu}'s SCM/Guile integration
@cindex scm
@cindex guile
@cindex REPL
@cindex geiser

With version 1.12.12, @command{mu} gained bindings for the SCM/Guile programming
 language, called @code{mu-scm}, with its own manual @ref{(mu-scm)
 Top}@footnote{These replace long-deprecated older bindings}. You can check if
 your @command{mu} includes the support by checking the output of @command{mu
 info}, which should say something like:
@example
| scm-support      | yes     |
@end example

If you have the support, you can connect to this ``REPL'' directly, which uses
the same database/store instance that @code{mu4e} uses.

Assuming your @code{mu} supports @code{scm}, there are two steps:

@itemize
@item install the @code{geiser-guile} package for Emacs,
available through the ELPA package archive.
@item request @code{mu4e} to start the SCM server in the
background, listening on a socket:
@lisp
(setq mu4e-mu-scm-server t)
@end lisp
@end itemize

After that, (re)start @t{mu4e}, and you should be able to invoke @kbd{M-x
mu4e-mu-scm-repl}, and be switched to a buffer to interact with the REPL.
@example
GNU Guile 3.0.9
Copyright (C) 1995-2023 Free Software Foundation, Inc.
[...]
Enter `,help' for help.
scheme@@(guile-user)> (let ((message (car (mfind "mu4e"))))
                       (format #t "Subject: ~a\n" (subject message)))
Subject: Re: Custom header in message view
$8 = #t
scheme@@(guile-user)>
@end example

A discussion of the capabilities of @code{mu-scm} goes far beyond this manual,
so please refer to @ref{(mu-scm) Top} for that.

@node Integration
@chapter Integrating @code{mu4e} with Emacs facilities

In this chapter, we discuss how you can integrate @code{mu4e} with Emacs in
various ways. Here we focus on Emacs built-ins; for dealing with external tools,
see @ref{Other tools}.

@menu
* Default email client::Making mu4e the default emacs e-mail program
* Modeline::Showing mu4e's status in the modeline
* Transient::Transient menus for mu4e
* Desktop notifications::Get desktop notifications for new mail
* DBus service::Accessing Mu4e through DBus
* Emacs bookmarks::Using Emacs' bookmark system
* Eldoc::Information about the current header in the echo area
* Org-mode::Adding mu4e to your organized life
* iCalendar::Enabling iCalendar invite processing
* Speedbar::A special frame with your folders
* Dired:: Attaching files using @t{dired}
@end menu

@node Default email client
@section Default email client

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; see @ref{(emacs) Mail Methods}.

If you want to use @code{mu4e} for this, you can do so by adding the following
to your configuration:

@lisp
(setq mail-user-agent 'mu4e-user-agent)
@end lisp

Similarly, to specify @code{mu4e} as your preferred method for reading
mail, customize the variable @code{read-mail-command}.

@lisp
(set-variable 'read-mail-command 'mu4e)
@end lisp

@node Modeline
@section Modeline
@cindex modeline

One of the most visible ways in which @code{mu4e} integrates with Emacs is through
the @emph{modeline} see @ref{Mode Line,,,emacs}. The @code{mu4e} support for that is
handled through a minor-mode @code{mu4e-modeline-mode}, which is enabled by
default when @code{mu4e} is running.

To completely turn off the modeline support, set @code{mu4e-modeline-support} to
@code{nil} before starting @code{mu4e}.

@code{mu4e} shares information on the modeline in two ways:
@itemize
@item buffer-specific
@itemize
@item current context (as per @ref{Contexts})
@item current query parameters (headers-mode only)
@end itemize
@item global: information about the results for the ``favorite query''
@end itemize

The global indicators can be disabled by setting @code{mu4e-modeline-show-global}
to @code{nil}.

All of the bookmark items provide more details in their @code{help-echo},
i.e., their tooltip.

@subsection Query parameters bookmark item
The query parameters in the modeline start with the various query flags (such as
some representation of @code{mu4e-search-threads}, @code{mu4e-search-full}; the
@t{help-echo} (tool-tip) has the details.

The query parameters are followed by the query-string used for the headers-view.
By default, if the query string matches some bookmark, the name of that bookmark
is shown instead of the query it specifies. This can be changed by setting
@code{mu4e-modeline-prefer-bookmark-name} to @code{nil}.

@cindex favorite bookmark
@subsection Favorite bookmark modeline item
The global modeline contains the results of some specific ``favorite'' bookmark
query from @code{mu4e-bookmarks}. By default, the @emph{first} one in chosen,
but you may want to change that by using the @code{:favorite} property for a
particular query, e.g., as part of your @var{mu4e-bookmarks}:
@example
 ;; Monitor the inbox folder in the modeline
 (:query "maildir:/inbox" :name "Inbox" :key ?i :favorite t)
@end example

The results of this query (the last time it was updated) is shown as some
character or emoji (depending on @var{mu4e-use-fancy-chars}) and 2 or 3 numbers,
just like what we saw in @ref{Bookmarks and Maildirs}, e.g.,
@example
 N:10(+5)/15
@end example

@cindex baseline query results
this means there are @emph{10 unread messages}, with @emph{5 new messages since
the baseline}, and @emph{15 messages in total} matching the query.

You can customize the icon; see @code{mu4e-modeline-all-clear},
@code{mu4e-modeline-all-read}, @code{mu4e-modeline-unread-items} and
@code{mu4e-modeline-new-items}.

Due to the way queries work, the modeline is @emph{not} immediately updated when
you read messages; but going back to the main view (with @kbd{M-x mu4e} resets
the counts to latest known ones. When in the main-view, you can use
@code{revert-buffer} (@kbd{g}) to reset the counters explicitly.

@node Transient
@section Transient
@cindex transient

@code{mu4e} has support for the ``transient'' menus, as per @ref{(transient)
Top}, through @kbd{M-x mu4e-transient-menu}, or bind it to some key.

@node Desktop notifications
@section Desktop notifications
@cindex desktop notifications

Depending on your desktop environment, it is possible to get notification when
there is new mail.

The default implementation (which you can override) depends on the same system
used for the @ref{Bookmarks and Maildirs}, in the main view and the
@ref{Modeline}, and thus gives updates when there are new messages compared to
some ``baseline'', as discussed earlier.

For now, notifications are implemented for desktop environments that support
DBus-based notifications, as per Emacs' notification sub-system, see
@ref{(elisp) Desktop Notifications}.

You can enable mu4e's desktop notifications (provided that you are on a
supported system) by setting @code{mu4e-notification-support} to @t{t}. If you
want to tweak the details, have a look at @code{mu4e-notification-filter} and
@code{mu4e-notification-function}.

@node DBus service
@section DBus service
@cindex DBus

DBus is a message-bus system for GNU/Linux and some other systems, which allows
for communications between programs using a binary protocol; see @ref{(dbus)
Top} for further details.

@code{mu4e} uses Emacs' DBus-support to implements a service for making some of
its information visible to external programs. This information includes the
current context (@code{mu4e-context-name}) and the read/unread counts for
various bookmarked queries (@code{mu4e-query-items})- the same information that
is used for the new mail notifications and the read/unread counts,
@pxref{Bookmarks and Maildirs}.

An external program could use this information display such status information.

@subsection @code{mu4e-dbus-mode}
@cindex mu4e-dbus-mode

Enabling and disabling the service is through a minor-mode
@code{mu4e-dbus-mode}. @code{M-x mu4e-dbus-mode}.

This starts a DBus service with the name @t{nl.djcbsoftware.nl} on the
session-bus, and at object-path @t{nl.djcbsoftware.Mu4e}, exposes the interface
@t{/nl/djcbsoftware/Mu4e}.

The interface is described as an XML string, in a constant
@code{mu4e-dbus-intrspection-xml}. This currently looks like:

@verbatim
  <node>
  <interface name='org.freedesktop.DBus.Introspectable'>
    <method name='Introspect'>
      <arg name='xml_data' type='s' direction='out'/>
    </method>
  </interface>
  <interface name='org.freedesktop.DBus.Properties'>
    <method name='Get'>
      <arg type='s' name='interface_name' direction='in'/>
      <arg type='s' name='property_name' direction='in'/>
      <arg type='v' name='value' direction='out'/>
    </method>
    <method name='GetAll'>
      <arg type='s' name='interface_name' direction='in'/>
      <arg type='a{sv}' name='properties' direction='out'/>
    </method>
    <method name='Set'>
      <arg type='s' name='interface_name' direction='in'/>
      <arg type='s' name='property_name' direction='in'/>
      <arg type='v' name='value' direction='in'/>
    </method>
    <signal name='PropertiesChanged'>
      <arg type='s' name='interface_name'/>
      <arg type='a{sv}' name='changed_properties'/>
      <arg type='as' name='invalidated_properties'/>
    </signal>
  </interface>
  <interface name='nl.djcbsoftware.Mu4e'>
    <property name='Version' type='s' access='read'/>
    <property name='DatabasePath' type='s' access='read'/>
    <property name='RootMaildir' type='s' access='read'/>
    <property name='Context' type='s' access='readwrite'/>
    <property name='QueryInfo' type='aa{sv}' access='readwrite'/>
  </interface>
</node>
@end verbatim

@node Emacs bookmarks
@section Emacs bookmarks
@cindex Emacs bookmarks

@code{mu4e} integrates with the Emacs bookmarks system, and allows you to create
bookmarks with @code{bookmark-set} for either message-at-point or the last
query. The message links are based on the message's message-id, and thus the
bookmarks stay valid even if you move the message around.

For deciding whether to link to message or query, you can customize
@code{mu4e-emacs-bookmark-policy}.

Emacs bookmarks are not to be confused with mu4e's bookmarks; the former are a
generic linking system across Emacs, while the latter are stored queries within
@code{mu4e}.

@node Eldoc
@section Eldoc
@cindex eldoc

It is possible to get information about the current header in the echo-area.
You can enable this by setting @t{mu4e-eldoc-support} to non-@code{nil}.

@node Org-mode
@section Org-mode
@cindex org-mode

Org-mode is a popular and powerful way to deal with todo-lists, agendas inside
Emacs. It's only natural to integrate it with @code{mu4e}, and

@subsection Org-mode links

It can be useful to include links to e-mail messages or search queries in your
org-mode files. @code{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 customize the link description using @code{mu4e-org-link-desc-func}.

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{mu4e-org} 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. In your capture
templates, the following mu4e-specific values are available:

@cartouche
@verbatim
item                                                 | description
-----------------------------------------------------+------------------------
%:date, %:date-timestamp, %:date-timestamp-inactive  | date, org timestamps
%:from, %:fromname, %:fromaddress                    | sender, name/address
%:to, %:toname, %:toaddress                          | recipient, name/address
%:maildir                                            | maildir for the message
%:message-id                                         | message-id
%:path                                               | file system path
%:subject                                            | message subject
@end verbatim
@end cartouche

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 %:fromname: %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") 'mu4e-org-store-and-capture)
  (define-key mu4e-view-mode-map    (kbd "C-c c") 'mu4e-org-store-and-capture)
@end lisp

@subsection Tracking sent mail

To build on the above, it can be useful to automatically track outgoing e-mail
so you can follow-up later.

One way to do this is to first add a template to @t{org-capture-templates}:
@lisp
("wm" "To-do" entry (file+headline "~/Org/todo.org" "Waiting for")
 "* WAIT [[mu4e:msgid:%(eval sent-message-id)][%(eval sent-subject)]]\n\t%u"
 :immediate-finish t)
@end lisp

Then invoke this template from @t{sent-hook}:
@lisp
(defun my-org-wait-for-sent-mail ()
  "Capture the outgoing mail."
  (interactive)
  (let* ((sent-message-id
          (replace-regexp-in-string
           "[<>]" "" (message-fetch-field "Message-Id")))
         (sent-subject (or (message-fetch-field "Subject") "No subject")))
    (org-capture nil "wm")))

(add-hook 'sent-hook #'my-org-wait-for-sent-mail)
@end lisp

All of the above likely needs tweaking for your particular setup, but should
hopefully give some inspiration.

@node iCalendar
@section iCalendar

When Gnus' article-mode is chosen (@ref{Message view}), it is possible
to view and reply to iCalendar events. To enable this feature, add

@lisp
(require 'mu4e-icalendar)
(mu4e-icalendar-setup)
@end lisp

to your configuration. If you want that the original invitation message
be automatically trashed after sending the message created by clicking
on the buttons “Accept”, “Tentative”, or “Decline”, also add:

@lisp
(setq mu4e-icalendar-trash-after-reply t)
@end lisp

When you reply to an iCal event, a line may be automatically added to
the diary file of your choice. You can specify that file with

@lisp
(setq mu4e-icalendar-diary-file "/path/to/your/diary")
@end lisp

Note that, if the specified file is not your main diary file, add
@t{#include "/path/to/your/diary"} to you main diary file to display
the events.

To enable optional iCalendar→Org sync functionality, add the following:

@lisp
(setq gnus-icalendar-org-capture-file "~/org/notes.org")
(setq gnus-icalendar-org-capture-headline '("Calendar"))
(gnus-icalendar-org-setup)
@end lisp

Both the capture file and the headline(s) inside it must already exist.

By default, @code{gnus-icalendar-org-setup} adds a temporary capture
template to the variable @code{org-capture-templates}, with the
description ``used by gnus-icalendar-org'', and the shortcut key ``#''.
If you want to use your own template, create it using the same key and
description. This will prevent the temporary one from being installed
next time you @code{gnus-icalendar-org-setup} is called.

The full default capture template is:

@lisp
("#" "used by gnus-icalendar-org" entry
   (file+olp ,gnus-icalendar-org-capture-file
             ,gnus-icalendar-org-capture-headline)
   "%i" :immediate-finish t)
@end lisp

where the values of the variables @code{gnus-icalendar-org-capture-file}
and @code{gnus-icalendar-org-capture-headline} are inserted via macro
expansion.

If, for example, you wanted to store ical events in a date tree,
prompting for the date, you could use the following:

@lisp
("#" "used by gnus-icalendar-org" entry
   (file+olp+datetree path-to-capture-file)
   "%i" :immediate-finish t :time-prompt t)
@end lisp

Note that the default behaviour for @code{datetree} targets in this
situation is to store the event at the date that you capture it, not at
the date that it is scheduled. That's why I've suggested using the
@code{:timeprompt t} argument. This gives you an opportunity to set the
time to the correct value yourself.

You can extract the event time directly, and have the @code{org-capture}
functions use that to set the @code{datetree} location:

@lisp
(defun my-catch-event-time (orig-fun &rest args)
  "Set org-overriding-default-time to the start time of the capture event"
  (let ((org-overriding-default-time (date-to-time
                                      (gnus-icalendar-event:start (car args)))))
    (apply orig-fun args)))

(advice-add 'gnus-icalendar:org-event-save :around #'my-catch-event-time)
@end lisp

If you do this, you'll want to omit the @code{:timeprompt t} setting
from your capture template.

@node Speedbar
@section Speedbar
@cindex speedbar

@code{speedbar} is an Emacs-extension that shows navigational
information for an Emacs buffer in a separate frame. Using
@code{mu4e-speedbar}, @code{mu4e} lists your bookmarks and maildir
folders and allows for one-click access to them.

To enable this, add @t{(require 'mu4e-speedbar)} to your configuration; then,
all you need to do to activate it is @kbd{M-x speedbar}. Then, when switching to
@ref{Main view}, the speedbar-frame is updated with your bookmarks and maildirs.

For speed reasons, the list of maildirs is determined when @code{mu4e}
starts; if the list of maildirs changes while @code{mu4e} is running, you
need to restart @code{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.

@node Dired
@section Dired
@cindex dired

It is possible to attach files to @code{mu4e} messages using @t{dired}
(@ref{Dired,,emacs}), using the following steps (based on a post on
the @t{mu-discuss} mailing list by @emph{Stephen Eglen}).

@lisp
(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 @kbd{C-c
RET C-a} or @code{gnus-dired-attach}, and you'll be asked whether to attach them
to an existing message, or create a new one.

@node Other tools
@appendix Other tools

In this chapter, we discuss some ways in which @code{mu4e} can cooperate
with other tools.

@menu
* Org-contacts::Hooking up with org-contacts
* BBDB::Hooking up with the Insidious Big Brother Database
* Sauron::Getting new mail notifications with Sauron
* Hydra:: Custom shortcut menus
@end menu

@node Org-contacts
@section Org-contacts

Note, @code{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
@uref{https://orgmode.org/worg/org-contrib/org-contacts.html,org-contacts}.

@t{mu4e-actions} define 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, @code{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
@uref{https://savannah.nongnu.org/projects/bbdb/,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-rendered-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

For recent emacs (29 and later), address-completion may need some extra setup:
@lisp
(add-hook 'message-mode-hook
          (lambda ()
            (add-to-list 'completion-at-point-functions
                         #'eudc-capf-complete)))
@end lisp
or, if that does not work:
@lisp
(add-hook 'message-mode-hook
          (lambda ()
            (add-to-list 'completion-at-point-functions
                         #'message-expand-name)))
@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 Emacs package @uref{https://github.com/djcb/sauron,sauron} (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 -not -iname '.uidvalidity'`; 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 Hydra
@section Hydra

People sometimes ask about having multi-character shortcuts for bookmarks; an
easy way to achieve this, is by using an emacs package
@uref{https://github.com/abo-abo/hydra,Hydra}.

With Hydra installed, we can add multi-character shortcuts, for instance:
@lisp
(defhydra my-mu4e-bookmarks-work (:color blue)
  "work bookmarks"
  ("b" (mu4e-search "banana AND maildir:/work") "banana")
  ("u" (mu4e-search "flag:unread AND maildir:/work")   "unread"))

(defhydra my-mu4e-bookmarks-personal (:color blue)
  "personal bookmarks"
  ("c" (mu4e-search "capybara AND maildir:/personal") "capybara")
  ("u" (mu4e-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 configurations
@appendix Example configurations

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 @code{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 be 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
    '((:maildir "/archive" :key ?a)
      (:maildir "/inbox"   :key ?i)
      (:maildir "/work"    :key ?w)
      (:maildir "/sent"    :key ?s)))

;; 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

(add-to-list 'mu4e-bookmarks
    ;; ':favorite t' i.e, use this one for the modeline
   '(:query "maildir:/inbox" :name "Inbox" :key ?i :favorite t))

;; 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 message-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 @code{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/.cache/mu/xapian]
| processing mail; checked: 520; updated/new: 520, cleaned-up: 0
mu: elapsed: 3 second(s), ~ 173 msg/s
mu: cleaning up messages [/home/foo/.cache/mu/xapian]
/ processing mail; checked: 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
@code{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 @code{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
    '( (:maildir "/INBOX"              :key ?i)
       (:maildir "/[Gmail].Sent Mail"  :key ?s)
       (:maildir "/[Gmail].Trash"      :key ?t)
       (:maildir "/[Gmail].All Mail"   :key ?a)))

(add-to-list 'mu4e-bookmarks
    ;; ':favorite t' i.e, use this one for the modeline
   '(:query "maildir:/inbox" :name "Inbox" :key ?i :favorite t))

;; 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"
   message-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)

;; don't keep message buffers around
(setq message-kill-buffer-on-exit t)
@end lisp

And that's it --- put the above in your emacs initialization file, change
@t{USERNAME} etc. to your own, restart 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 @code{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

@subsection Results from @command{mu} and @code{mu4e} differ --- why?
@anchor{mu-mu4e-differ} In general, the same queries for @command{mu}
and @code{mu4e} should yield the same results. If they differ, this is
usually because one of the following reasons:
@itemize
@item Database caching:
changes in @code{mu4e} are not immediately visible in the command-line @command{mu},
since it can take a while before changes are committed to disk (for performance
reasons). Note that quitting @code{mu4e} or invoking @t{mu4e-update-mail-and-index}
and @t{mu4e-update-index} have the side-effect of committing changed data to disk.
@item different options:
@code{mu4e} defaults to having @t{mu4e-headers-include-related}, and
@t{mu4e-headers-results-limit} set to 500. However, the command-line @command{mu
find}'s corresponding @t{--include-related} is false, and there's no limit
(@t{--maxnum}). Furthermore, @t{mu find} by default includes duplicate messages,
while @code{mu4e} does not (see
@t{--skip-dups}/@t{mu4e-search-skip-duplicates}).
@item reverse sorting:
The results may be different when @code{mu4e} and @command{mu find} do
not both sort their results in the same direction.
@item shell quoting issues:
Depending on the shell, various shell metacharacters in search query
(such as @t{*}) may be expanded by the shell before @command{mu} ever
sees them, and the query may not be what you think it is. Quoting is
necessary.
@end itemize

@subsection The counts in the main-screen differ from the 'real' numbers --- why?
For speed reasons, the counts do @emph{not} exclude messages that no longer
exist in the file-system, nor do they exclude duplicate messages; see
@ref{mu-mu4e-differ}.

@subsection How can I quickly delete/move/trash a lot of messages?
You can select ('mark' in Emacs-speak) messages, just 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.

Note that when you haven't enabled separate threads in the headers view, the
thread marking functions simply mark @emph{all} messages.

@subsection Can I automatically apply the marks when leaving the headers buffer?
Yes you can --- see the documentation for the variable
@t{mu4e-headers-leave-behavior}.

@subsection How can I set @code{mu4e} as the default e-mail client in Emacs?
See @ref{Default email client}.

@subsection Can @code{mu4e} use some fancy Unicode instead of boring ASCII?
Glad you asked! Yes, if you set @code{mu4e-use-fancy-chars} to @t{t}, @code{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.

@subsection Can I start @code{mu4e} in the background?
Yes --- if you provide a prefix-argument (@key{C-u}), @code{mu4e} starts, but does
not show the main-window.

@subsection Does @code{mu4e} support searching for CJK (Chinese-Japanese-Korean) characters?
Yes. This is not enabled by default though, since this is fairly intrusive, and
influences both indexing and querying. The enable this, pass
@t{--support-ngrams} to @code{mu init}; see the @t{mu-init} manpage for further
details.

@subsection 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.

@subsection With a lot of Maildir folders, jumping to them can get slow. What can I do?
Set @code{mu4e-cache-maildir-list} to @code{t} (make sure to read its
docstring).

@subsection How can I hide certain messages from the search results?
See the variables @code{mu4e-headers-hide-predicate} and
@code{mu4e-headers-hide-enabled}. The latter can be toggled through
@code{mu4e-search-toggle-property}.

For example, to filter out GMail's spam folder, set it to:
@lisp
(setq mu4e-headers-hide-predicate
     (lambda (msg)
       (string-suffix-p "Spam" (mu4e-message-field msg :maildir))))
@end lisp

@subsection I'm getting 'Variable binding depth exceeds...'. What can I do about it?
The error @t{'Variable binding depth exceeds max-specpdl-size'} occurs because
@code{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
Note that Emacs 29 obsoletes this variable.

@node Retrieving mail
@section Retrieving mail

@subsection How can I get notifications when receiving mail?

The recommended way is to use @code{mu4e}'s built-in notification system, see
@ref{Desktop notifications}.

Alternatively, you can set things up manually.

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

@subsection I'm getting mail through a local mail-server. 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.

@subsection How can I re-index my messages without getting new mail?
Use @kbd{M-x mu4e-update-index}

@subsection When I try to run @t{mu index} while @code{mu4e} is running I get errors
For instance:
@verbatim
mu: mu_store_new_writable: xapian error
  'Unable to get write lock on ~/.cache/mu/xapian: already locked
@end verbatim
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 @code{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
@code{mu4e} automatically restarts @command{mu} when it needs it. In practice, this
seems to work quite well.

@subsection How can I disable the @t{Indexing...} messages?
Set the variable @code{mu4e-hide-index-messages} to non-@code{nil}.

@subsection IMAP-synchronization

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. @code{mu4e} can attempt to help with this --- you can set the
variable @code{mu4e-change-filenames-when-moving} to non-@code{nil}.

Also, some of these programs may interpret the ``trash'' flag differently; see
@code{mu4e-trash-without-flag} for how to influence that.

Finally, we would warn against synchronizing the ``Drafts'' folder; the messages
in @code{mu4e}'s draft are in @code{mu4e}'s (i.e., Gnus') format, which is not
necessarily usable by other clients.

@subsection @command{offlineimap} and UTF-7
@command{offlineimap} uses IMAP's UTF-7 for encoding non-ascii folder
names, while @command{mu} expects UTF-8 (so, e.g. @t{/まりもえ
お}@footnote{some Japanese characters} becomes @t{/&MH4wijCCMEgwSg-}).

This is best solved by telling @command{offlineimap} to use UTF-8 instead ---
see @uref{https://github.com/djcb/mu/issues/68#issuecomment-8598652,this
ticket}.

@subsection @command{mbsync} or @command{offlineimap} do not sync properly

Unfortunately, @command{mbsync} and/or @command{offlineimap} do not
always agree with @command{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.

Also, you may want to ensure that @t{mu4e-index-lazy-check} is kept at
its default (@code{nil}) value, since it seems @command{mbsync} can make
changes that escape a 'lazy' check.

Furthermore, there have been quite a few related queries on the
mailing-list; worthwhile to check out.

@node Reading messages
@section Reading messages

@subsection Opening messages is slower than expected --- why?
@code{mu4e} is designed to be very fast, even with large amounts of mail.
However, if you experience slowdowns, here are some things to consider:
@itemize
@item opening messages while indexing:
@code{mu4e} communicates with the @command{mu} server mostly synchronously; this means
that you can do only one thing at a time. The one operation that potentially
does take a bit of time is indexing of mail. Indexing does happen
asynchronously, but still can slow down @command{mu} enough that users may notice.

For some strategies to reduce that time, see the next question.
@item getting contact information can take some time:
especially when opening @code{mu4e} the first time and you have a
@emph{lot} of contacts, it can take a few seconds to process those. Note
that @code{mu4e} 1.3 and higher only get @emph{changed} contacts in
subsequent updates (after and indexing operation), so this should be
less of a concern. And you can tweak what contacts you get using
@code{mu4e-compose-complete-only-personal},
@code{mu4e-compose-complete-only-after} and
@code{mu4e-compose-complete-max}.
@item decryption / sign verification:
encrypted / signed messages sometimes require network access, and this
may take a while; certainly if the needed servers cannot be found.
Part of this may be that influential environment variables are not set
in the emacs environment.
@end itemize

If you still experience unexpected slowness, you can of course file a
ticket, but please be sure to mention the following:

@itemize
@item are all messages slow or only some messages?
@item if it's only some messages, is there something specific about them?
@item in addition, please include a (sufficiently censored version of) a message that is slow
@item is opening @emph{always} slow or only sometimes? When?
@end itemize

@subsection 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-rendered-hook} (@code{mu4e-view-mode-hook} fires too early).
@subsection How can I perform custom actions on messages and attachments?
See @ref{Actions}.
@subsection How can I prevent @code{mu4e} from automatically marking messages as `read' when I read them?
Set @code{mu4e-view-auto-mark-as-read} to @code{nil}.
@subsection Does @code{mu4e} support including all related messages in a thread, like Gmail does?
Yes --- see @ref{Including related messages}.
@subsection There seems to be a lot of duplicate messages --- how can I get rid of them?
See @ref{Skipping duplicates}.
@subsection 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 web browser. You can influence the browser to
use with @code{browse-url-generic-program}.
@subsection 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


@subsection Some plain-text attachments get corrupted, how can I avoid that?
@code{mu4e} (or, more precisely, its Gnus helpers) automatically convert CR-LF
(``Windows-style'') line-endings to Unix line endings for the text attachments.

That is usually convenient, but can be problematic when attachments are
mislabeled as text when they contain binary data: in that case, the conversion
would result in invalid data.

If you run into that problem, you can @t{advise} the responsible function:

@lisp
(defun mm-dcte-keep-crlf (args)
  "Don't convert crlf->lf.
Advise `mm-decode-content-transfer-encoding' to not perform the
conversion."
  (when (and (= (length args) 2)
             (memq (nth 0 args) '(base64 x-uuencode x-uue x-binhex x-yenc))
             (string-match "\\`text/" (nth 1 args)))
    ;; fake the type, so no conversion happens
    (setf (nth 1 args) "application/octet-stream"))
  args)

(advice-add 'mm-decode-content-transfer-encoding :filter-args #'mm-dcte-keep-crlf)
@end lisp

@node Writing messages
@section Writing messages

@subsection How can I automatically set the @t{From:}-address for a reply-message?
See @ref{Compose hooks}.

@subsection How can I dynamically determine the folders for draft/sent/trashed messages?
See @ref{Dynamic folders}.

@subsection How can I define aliases for (groups of) e-mail addresses?
See @ref{(emacs) Mail Aliases}.

@subsection How can I automatically add some header to an outgoing message?
See @ref{Compose hooks}.

@subsection How can I influence the way the original message looks when replying/forwarding?
Since @code{mu4e-compose-mode} derives from @code{gnus-article-mode}, see
@ref{(message) Top}, you can re-use many (though not @emph{all}) of its
facilities.

@subsection Replying to unquoted contacts with commas in their name

Senders may have commas in their RFC2047-encoded name without using the needed
quoting, for instance @t{From: Foo, the great Bar <foo@@bar.com>} instead of
@t{From: "Foo, the great Bar" <foo@@bar.com>}.

By default, when replying to such messages, @code{mu4e} then interprets the address
as @emph{multiple} contacts. To avoid that, you can add to your configuration:
@lisp
(setq rfc2047-quote-decoded-words-containing-tspecials t)
@end lisp

@subsection How can I easily include attachments in the messages I write?
You can drag-and-drop from your desktop; alternatively, you can use @ref{(emacs)
Dired}.

@subsection How can I start a new message-thread from a reply?
Remove the @t{In-Reply-To} header, and @code{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.

@subsection 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}.

@subsection How can I sign or encrypt messages?
You can do so using Emacs' MIME-support --- check the
@t{Attachments}-menu while composing a message. Also see @ref{Signing
and encrypting}.

@subsection Address auto-completion misses some addresses
If you have set @code{mu4e-compose-complete-only-personal} to non-nil, @code{mu4e}
only completes 'personal' addresses --- so you tell it about your e-mail addresses
when setting up the database (@t{mu init}); @ref{Initializing the message
store}.

If you cannot find specific addresses you'd expect to find, inspect the
values of @code{mu4e-compose-complete-only-personal},
@code{mu4e-compose-complete-only-after} and
@code{mu4e-compose-complete-max}.

@subsection How can I get rid of the message buffer after sending?
@lisp
(setq message-kill-buffer-on-exit t)
@end lisp

@subsection Sending big messages is slow and blocks Emacs

And what can I do about it?

For this, there's @uref{https://github.com/jwiegley/emacs-async,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 delivery 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.

@subsection Using a separate frame or window for composing

Is it possible to view headers and messages, or compose new ones, in a separate
frame or window?

Yes. There is built-in support for composing messages in a new frame or window.
Either use Emacs' standard @t{compose-mail-other-frame} (@kbd{C-x 5 m}) and
@t{compose-mail-other-window} (@kbd{C-x 4 m}) if you have set up @code{mu4e} as your Emacs
e-mailer.

Additionally, there's the variable @code{mu4e-compose-switch} (see its
docstring) which you can customize to influence how @code{mu4e} creates new
messages.

@subsection How can I apply format=flowed to my outgoing messages?

Plain text emails with @t{Content-Type: text/plain; format=flowed} can be
re-flowed (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 @uref{https://www.ietf.org/rfc/rfc2646.txt,RFC with all the details}.

Since version 0.9.17, @code{mu4e} sends 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 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.

@subsection 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

@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 @code{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.

@subsection UTF-8 language environment is required
@code{mu4e} does not work well if the 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.d/init.el} (or
its moral equivalent, such as @file{~/.emacs}.

@subsection Headers-buffer can get mis-aligned
Due to the way the headers buffer works, it can get misaligned.

For the particular case where the header values are misaligned with the column
headings, you can try something like the following:
@lisp
(add-hook 'mu4e-headers-mode-hook #'my-mu4e-headers-mode-hook)
(defun my-mu4e-headers-mode-hook ()
  ;; Account for the fringe and other spacing in the header line.
  (header-line-indent-mode 1)
  (push (propertize " " 'display '(space :align-to header-line-indent-width))
        header-line-format)
  ;; Ensure `text-scale-adjust' scales the header line with the headers themselves
  ;; by ensuring the `default' face is in the inheritance hierarchy.
  (face-remap-add-relative 'header-line '(:inherit (mu4e-header-face default)))
@end lisp

This does not solve all possible issues; that would require a thorough rework of
the headers-view, which may happen at some time.

@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
* Refiling from the command-line:: Refiling using shell commands
* 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
(when (equal window-system 'x)
      (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

It's possible to customize various header marks as well, with a ``fancy'' and
``non-fancy'' version (if you cannot see some of the ``fancy'' characters, that
is an indication that the font you are using does not support those characters.

@lisp
 (setq
   mu4e-headers-draft-mark     '("D" . "💈")
   mu4e-headers-flagged-mark   '("F" . "📍")
   mu4e-headers-new-mark       '("N" . "🔥")
   mu4e-headers-passed-mark    '("P" . "❯")
   mu4e-headers-replied-mark   '("R" . "❮")
   mu4e-headers-seen-mark      '("S" . "☑")
   mu4e-headers-trashed-mark   '("T" . "💀")
   mu4e-headers-attach-mark    '("a" . "📎")
   mu4e-headers-encrypted-mark '("x" . "🔒")
   mu4e-headers-signed-mark    '("s" . "🔑")
   mu4e-headers-unread-mark    '("u" . "⎕")
   mu4e-headers-list-mark      '("l" . "🔈")
   mu4e-headers-personal-mark  '("p" . "👨")
   mu4e-headers-calendar-mark  '("c" . "📅"))
@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 Refiling from the command-line
@section Refiling from the command-line

If you want to refile a lot of messages, a powerful way is to use some of
@t{mu}' command-line utilities.

For instance, to move all message from 2010 to some maildir @t{/archive-2010},
you could try something like:

@example
$ mu find date:2010..2010 --exec 'echo' | \
     xargs -I @{@} echo "mu move @{@} /archive-2010"

(this ^^ just echoes, use to test first...).
@end example

@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 'sent'-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 @code{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
(defun confirm-empty-subject ()
  "Require confirmation before sending without subject."
  (let ((sub (message-field-value "Subject")))
    (or (and sub (not (string-match "\\`[ \t]*\\'" sub)))
        (yes-or-no-p "Really send without Subject? ")
        (keyboard-quit))))

(add-hook 'message-send-hook #'confirm-empty-subject)
@end lisp

If you @emph{always} want to be asked for confirmation before sending, you can
set @code{message-confirm-send} to non-@code{nil}.

@node How it works
@appendix How it works

While perhaps not interesting for all users of @code{mu4e}, some curious
souls may want to know how @code{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 @code{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 @command{fetchmail}, @command{offlineimap}, or through a local
mail server.
@item @command{mu} indexes these messages periodically, so you can quickly search for
them. @command{mu} can run in a special @t{server}-mode, where it provides services
 to client software.
@item @code{mu4e}, which runs inside Emacs is
 such a client; it communicates with @command{mu} (in its @t{server}-mode) to
 search for messages, and manipulate them.
@item @code{mu4e} uses the facilities
 offered by Emacs (the Gnus message editor and @t{smtpmail}) to send
 messages.
@end itemize

@node mu server
@section @command{mu server}

@code{mu4e} is based on the @command{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 @command{mu} command-line
tool with some parameters and then parse the output. In fact, that was
the first approach --- @code{mu4e} would invoke e.g., @t{mu find} and
process the output in 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 @command{mu} instance around? Indeed, it would --- and
thus, the @command{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 @command{mu} should use for its
output for @code{mu4e} (Emacs) to process. Some other programs use @abbr{JSON}
here, but it seemed easier (and possibly, more efficient) just to talk to Emacs
in its native language: @emph{s-expressions}, and interpret those using the
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 Emacs. We'll
leave out a lot of details, @code{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 @code{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}.

@code{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

As a word of warning, the details of the s-expression are internal to the mu4e -
mu communications, and are subject to change between versions.

A typical message s-expression looks something like the following:

@lisp
(:docid 32461
 :from ((:name "Nikola Tesla" :email "niko@@example.com"))
 :to ((:name "Thomas Edison" :email "tom@@example.com"))
 :cc ((:name "Rupert The Monkey" :email "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 attach)
 ....
")
@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 @t{plists} of the form
@code{(:name <name>   :email <email>)}, where @t{name} can be @code{nil}.
@item The date is in format 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 Emacs for
internal purposes. Therefore, we need to split @t{time_t} in two
numbers.}
@end itemize

@subsection Example: ping-pong

As an example of the communication between @code{mu4e} and @command{mu},
let's look at the @t{ping-pong}-sequence. When @code{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 @code{mu4e} is invoked (when the program is
started). It calls @t{mu4e--server-ping}, and registers a (lambda)
function for @t{mu4e-server-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-server.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}, @code{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,
@code{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 @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.

@command{mu} itself keeps a log as well; depending on your system that could be in
your @t{systemd} journal, @t{syslog} or in @t{<MUHOME>/mu.log}, on Unix
typically @t{~/.cache/mu/mu.log}. To run the server in debug-mode, set
@code{mu4e-mu-debug} to @t{t} (before starting the server).

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi

@c @node Command Index
@c @unnumbered Command and Function Index
@c @printindex fn

@c @node Variable Index
@c @unnumbered Variable Index
@c @printindex vr

@node Concept Index
@unnumbered Concept Index
@printindex cp

@bye

@c Local Variables:
@c coding: utf-8
@c End: