Copyright © 2012-2025 Dirk-Jan C. Binnema

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

mu4e manual for version 1.12.11
*******************************

Welcome to mu4e!

   mu4e (mu-for-emacs) is an e-mail client for GNU Emacs version 26.3 or
newer, built on top of the mu (https://www.djcbsoftware.nl/code/mu)
e-mail search engine.  mu4e is optimized for quickly processing large
amounts of e-mail.

   Some of its highlights:
   • Fully search-based: there are no folders(1), only queries.
   • Fully documented, with example configurations
   • User-interface optimized for speed, with quick key strokes for
     common actions
   • Support for non-English languages (so "angstrom" matches
     "Ångström")
   • Asynchronous: heavy actions don't block emacs(2)
   • Support for cryptography -- signing, encrypting and decrypting
   • Address auto-completion based on the contacts in your messages
   • Extendable with your own snippets of elisp

   In this manual, we go through the installation of mu4e, do some basic
configuration and explain its daily use.  We also show you how you can
customize mu4e for your special needs.

   At the end of the manual, there are some example configurations, to
get you up to speed quickly: Example configurations.  There's
also a section with answers to frequently asked questions, see FAQ.

Appendices

Indices

   ---------- Footnotes ----------

   (1) that is, instead of folders, you use queries that match messages
in a particular folder

   (2) currently, the only exception to this is _sending mail_; there
are solutions for that though -- see the FAQ

1 Introduction
**************

Let's get started

1.1 Why another e-mail client?
==============================

I (mu4e's author) spend a _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 (mu), it seemed only logical to use that as a basis.

1.2 Other mail clients
======================

Under the hood, mu4e is fully search-based, similar to programs like
notmuch (https://notmuchmail.org/) and sup
(https://sup-heliotrope.github.io/).

   However, mu4e's user-interface is quite different.  mu4e's mail
handling (deleting, moving, etc.) is inspired by Wanderlust
(http://www.gohome.org/wl/) (another Emacs-based e-mail client), mutt
(http://www.mutt.org/) and the dired file-manager for emacs.

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

1.3 What mu4e does not do
=========================

There are a number of things that mu4e does not do, by design:
   • mu/mu4e do _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 offlineimap (https://www.offlineimap.org/), mbsync
     (http://isync.sourceforge.net/) or fetchmail
     (http://www.fetchmail.info/); As long as the messages end up in a
     maildir, mu4e and mu are happy to deal with them.
   • mu4e also does _not_ implement sending of messages; instead, it
     depends on smtpmail, which is part of Emacs.  In
     addition, mu4e piggybacks on Gnus' message editor.

   Thus, many of the things an e-mail client traditionally needs to do,
are delegated to other tools.  This leaves mu4e to concentrate on what
it does best: quickly finding the mails you are looking for, and handle
them as efficiently as possible.

1.4 Becoming a mu4e user
========================

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

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

   • What did you expect or wish to happen?  what actually happened?
     Please describe in detail what you saw.  Also, try some related
     scenarios and whether the problem either _always_ happens, or only
     _sometimes_.  E.g., it might happen with only one particular type
     of message
   • Provide some exact steps to reproduce?  In particular, some minimal
     steps, starting from 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.
   • hat version of mu4e and emacs were you using?  What operating
     system?  Always try with up-to-date versions.  And please use the
     'normal' mu4e for reproducing your problem, not the "remix" version
     that some Emacs "distributions" use, such as "Doom Emacs".
   • can you reproduce it with ‘emacs -q’ and only loading mu4e?
   • if the problem is related to some specific message, please include
     the raw message file (appropriately anonymized, of course)

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

2 Getting started
*****************

In this chapter, we go through the installation of mu4e and its basic
setup.  After we have succeeded in Getting mail, and
Indexing your messages, we discuss the Basic configuration.

   After these steps, mu4e should be ready to go!

2.1 Requirements
================

mu/mu4e are known to work on a wide variety of Unix- and Unix-like
systems, including many Linux distributions, OS X and FreeBSD. Emacs
26.3 or higher is required, as well as Xapian (https://xapian.org/) and
GMime (http://spruce.sourceforge.net/gmime/).

   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 mu yourself, you need to have the typical
development tools, such as C and C++17 compilers (both ‘gcc’ and ‘clang’
work), ‘meson’ and ‘make’, and the development packages for GMime 3.x,
GLib and Xapian.  Optionally, you also need the development packages for
GTK+, Webkit and Guile.

2.2 Versions
============

The stable (release) versions have even minor version numbers, while the
development versions have odd ones.  So, for example, 1.10.5 is a stable
version, while the 1.11.9 is the development version.

   The stable versions only receive bug fixes after being released,
while the development versions get new features, fixes, and, perhaps,
bugs, and are meant for people with a tolerance for that.

   There is support for one release branch; so, when the 1.10 release is
available (and a new 1.11 development series start), no more changes are
expected for the 1.8 releases.

2.3 Installation
================

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

2.3.1 Dependencies
------------------

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

2.3.2 Getting mu
----------------

The next step is to get the mu sources.  There are two alternatives:
   • _Use a stable release_ - download a release from
     <https://github.com/djcb/mu/releases>
   • _Use an experimental development version_ - get it from the
     repository, and git clone https://github.com/djcb/mu.git

2.3.3 Building mu
-----------------

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

     $ meson setup build
     $ meson compile -C build
     $ meson install -C build

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

     $ ./autogen.sh && make
     $ sudo make install

2.3.4 Installation
------------------

After this, mu and mu4e should be installed (1) on your system, and be
available from the command line and in Emacs.

   You may need to restart Emacs, so it can find mu4e in its
‘load-path’.  If, even after restarting, Emacs cannot find mu4e, you may
need to add it to your ‘load-path’ explicitly; check where mu4e is
installed, and add something like the following to your configuration
before trying again:
     ;; the exact path may differ --- check it
     (add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e")

2.3.5 mu4e and emacs customization
----------------------------------

There is some support for using the Emacs customization system in mu4e,
but for now, we recommend setting the values manually.  Please refer to
Example configurations for a couple of examples of this; here we
go through things step-by-step.

   ---------- Footnotes ----------

   (1) there's a hard dependency between versions of mu4e and mu -- you
cannot combine different versions

2.4 Getting mail
================

In order for mu (and, by extension, mu4e) to work, you need to have your
e-mail messages stored in a Maildir
(https://en.wikipedia.org/wiki/Maildir); in this manual we use the term
'maildir' for both the standard and the hierarchy of maildirs that store
your messages -- a specific directory structure with
one-file-per-message.

   If you are already using a maildir, you are lucky.  If not, some
setup is required:
   • _Using an external IMAP or POP server_ -- if you are using an IMAP
     or POP server, you can use tools like getmail, fetchmail,
     offlineimap or isync to download your messages into a maildir
     (‘~/Maildir’, often).  Because it is such a common case, there is a
     full example of setting mu4e up with offlineimap and Gmail; see
     Gmail configuration.
   • _Using a local mail server_ -- if you are using a local mail-
     server (such as postfix or qmail), you can teach them to deliver
     into a maildir as well, maybe in combination with procmail.  A bit
     of googling should be able to provide you with the details.

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

2.5 Initializing the message store
==================================

The first time you run mu, you need to initialize its store (database).
The default location for that is ~/.cache/mu/xapian, but you can change
this using the --muhome option, and remember to pass that to the other
commands as well.  Alternatively, you can use an environment variable
MUHOME.

   Assuming that your maildir is at ‘~/Maildir’, we issue the following
command:
       $ mu init --maildir=~/Maildir

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

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

   mu remembers the maildir and your addresses and uses them when
indexing messages.  If you want to change them, you need to init once
again.

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

   If you want to see the values for your message-store, you can use ‘mu
info’.

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

   The good news is that mu4e can do the conversion automatically;
however for this to work, users needs to install the pcre2el package
(available in MELPA), and ensure it is available in load-path when Emacs
runs (a normal package-installation takes care of this).  After that,
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 pcre2el to
avoid this.

2.6 Indexing your messages
==========================

After you have succeeded in Getting mail and initialized the
message database, we need to _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 mu4e -- see 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 ‘~/Maildir’, we issue the following
command:
       $ mu index

   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 mu only
scans messages that are new or have changed.  Indexing is discussed in
full detail in the 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
       $ mu find hello

   which lists all messages that match hello.  For more examples of
searches, see Queries, or check the mu-find and 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 mu4e.

2.7 Basic configuration
=======================

Before we can start using mu4e, we need to tell Emacs to load it.  So,
add to your ‘~/.emacs’ (or its moral equivalent, such as
‘~/.emacs.d/init.el’) something like:

     (require 'mu4e)

   If Emacs complains that it cannot find mu4e, check your ‘load-path’
and make sure that mu4e's installation directory is part of it.  If not,
you can add it:

     (add-to-list 'load-path MU4E-PATH)

   with MU4E-PATH replaced with the actual path.

2.8 Folders
===========

The next step is to tell mu4e where it can find your Maildir, and some
special folders.

   So, for example(1):
     ;; 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

   The folder (maildir) names are all relative to the root-maildir (see
the output of ‘mu info’).  If you use mu4e-context, see Contexts and special folders
for what that means for these special folders.

   ---------- Footnotes ----------

   (1) Note that the folders (mu4e-sent-folder, mu4e-drafts-folder,
mu4e-trash-folder and mu4e-refile-folder) can also be _functions_ that
are evaluated at runtime.  This allows for dynamically changing them
depending on the situation.  See Dynamic folders for details.

2.9 Retrieval and indexing with mu4e
====================================

As we have seen, we can do all of the mail retrieval _outside_ of
Emacs/mu4e.  However, you can also do it from within mu4e.

2.9.1 Basics
------------

To set up mail-retrieval from within mu4e, set the variable
‘mu4e-get-mail-command’ to the program or shell command you want to use
for retrieving mail.  You can then get your e-mail using ‘M-x
mu4e-update-mail-and-index’, or ‘C-S-u’ in all mu4e-views;
alternatively, you can use ‘C-c C-u’, which may be more convenient if
you use emacs in a terminal.

   You can kill the (foreground) update process with ‘q’.

   It is possible to update your mail and index periodically in the
background or foreground, by setting the variable ‘mu4e-update-interval’
to the number of seconds between these updates.  If set to ‘nil’, it
won't update at all.  After you make changes to ‘mu4e-update-interval’,
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
‘mu4e-index-update-in-background’ to ‘nil’.

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

2.9.2 Handling errors during mail retrieval
-------------------------------------------

If the mail-retrieval process returns with a non-zero exit code, mu4e
shows a warning (unless ‘mu4e-index-update-error-warning’ is set to
‘nil’), but then try to index your maildirs anyway (unless
‘mu4e-index-update-error-continue’ is set to ‘nil’).

   Reason for these defaults is that some of the mail-retrieval programs
may return non-zero, even when the updating process succeeded; however,
it is hard to tell such pseudo-errors from real ones like login failed.

   If you need more refinement, it may be useful to wrap the
mail-retrieval program in a shell-script, for example fetchmail returns
1 to indicate 'no mail'; we can handle that with:
     (setq mu4e-get-mail-command "fetchmail -v || [ $? -eq 1 ]")
   A similar approach can be used with other mail retrieval programs,
although not all of them have their exit codes documented.

2.9.3 Implicit mail retrieval
-----------------------------

If you don't have a specific command for getting mail, for example
because you are running your own mail-server, you can leave
‘mu4e-get-mail-command’ at "true" (the default), in which case mu4e
won't try to get new mail, but still re-index your messages.

2.9.4 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:

     (setq
       mu4e-index-cleanup nil      ;; don't do a full cleanup check
       mu4e-index-lazy-check t)    ;; don't consider up-to-date dirs

   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., mu4e fails to find some new messages), simply leave at
the default.

   Note that you can occasionally run a thorough indexing round using
‘mu4e-update-index-nonlazy’.

   For further details, please refer to the mu-index manpage; in
particular, see .noindex and .noupdate which can help reducing the
indexing time.

2.9.5 Example setup
-------------------

A simple setup could look something like:

     (setq
       mu4e-get-mail-command "offlineimap"   ;; or fetchmail, or ...
       mu4e-update-interval 300)             ;; update every 5 minutes

   A hook ‘mu4e-update-pre-hook’ is available which is run right before
starting the process.  That can be useful, for example, to influence,
‘mu4e-get-mail-command’ based on the the current situation (location,
time of day, ...).

   It is possible to get notifications when the indexing process does
any updates -- for example when receiving new mail.  See
‘mu4e-index-updated-hook’ and some tips on its usage in the FAQ.

2.10 Sending mail
=================

mu4e uses Emacs's message-mode (message) for writing mail.

   For sending mail using SMTP, mu4e uses 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
Example configurations.

   A very minimal setup:

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

   Since mu4e (re)uses the same message mode and smtpmail that Gnus
uses, many settings for those also apply to mu4e.

2.10.1 Dealing with sent messages
---------------------------------

By default, mu4e puts a copy of messages you sent in the folder
determined by ‘mu4e-sent-folder’.  In some cases, this may not be what
you want - for example, when using Gmail-over-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 ‘mu4e-sent-messages-behavior’ to customize
what happens with sent messages.  The default is the symbol ‘sent’
which, as mentioned, causes the message to be copied to your
sent-messages folder.  Other possible values are the symbols ‘trash’
(the sent message is moved to the trash-folder (‘mu4e-trash-folder’),
and ‘delete’ to simply discard the sent message altogether (so Gmail can
deal with it).

   For Gmail-over-IMAP, you could add the following to your settings:
;; don't save messages to Sent Messages, Gmail/IMAP takes care of this
(setq mu4e-sent-messages-behavior 'delete)
   And that's it!  We should now be ready to go.

   For more complex needs, ‘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.

2.11 Running mu4e
=================

After following the steps in this chapter, we now (hopefully!)  have a
working mu4e setup.  Great!  In the next chapters, we walk you through
the various views in mu4e.

   For your orientation, the diagram below shows how the views relate to
each other, and the default key-bindings to navigate between them.

   [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

3 The main view
***************

After you have installed mu4e (see Getting started), you can start
it with ‘M-x mu4e’.  mu4e does some checks to ensure everything is set
up correctly, and then shows you the mu4e main view.  Its major mode is
‘mu4e-main-mode’.

3.1 Overview
============

The main view looks something like the following:

* 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

   Let's walk through the menu.

3.2 Basic actions
=================

First, the _Basics_:
   • [j]ump to some maildir: after pressing <j> ("jump"), mu4e asks you
     for a maildir to visit.  These are the maildirs you set in
     Basic configuration and any of your own.  If you choose <o>
     ("other") or </>, you can choose from all maildirs under the
     root-maildir.  After choosing a maildir, the messages in that
     maildir are listed, in the Headers view.
   • enter a [s]earch query: after pressing <s>, mu4e asks you for a
     search query, and after entering one, shows the results in the
     Headers view.
   • [C]ompose a new message: after pressing <C>, you are dropped in the
     Composer to write a new message.

3.3 Bookmarks and Maildirs
==========================

The next two items in the Main view are _Bookmarks_ and _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 <b> followed by the specific bookmark's
shortcut.  If you want to edit the bookmarked query before invoking it,
use <B>.

   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 _not_ using mu4e.  For this reason, you can reset
the baseline manually, e.g.  by visiting the main view.

   Furthermore, for speed reasons, the counts do _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(1) is reset automatically when switching to the main
view, or invoking ‘buffer-revert’ (‘g’) while in the main-view.
Visiting the "favorite" bookmark does the same(explained below).

   Bookmarks are stored in the variable ‘mu4e-bookmarks’; you can add
your own and/or replace the default ones; see Bookmarks.  For
instance:
     (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"))

   There are optional keys ‘:hide’ to hide the bookmark or maildirs from
the main menu, but still have it available (using <b>)), and
‘:hide-if-no-unread’ to hide it if there are no unread messages.

   To customize the display, there is also ‘:hide-unread’ to avoid
generating the unread-number; that can be useful if you have bookmarks
for slow queries.  Note that ‘: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 ‘: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 Modeline, and you
can enable desktop notifications; see Desktop notifications.  We'd
recommend creating such a "favorite", which should match message that
require your quick attention:

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

   Note that 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 _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 ‘mu4e-maildir-shortcuts’; see
its docstring and Maildir searches for more details.

   When you ask for bookmarks or maildirs through ‘mu4e-ask-bookmark’,
‘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
mu4e-hide-short-counts to non-nil.

   ---------- Footnotes ----------

   (1) For debugging, it can be useful to see the time for the baseline
- for that, there is the ‘mu4e-baseline-time’ command.

3.4 Miscellaneous
=================

Finally, there are some _Misc_ (miscellaneous) actions:
   • [U]pdate email & database executes the shell-command in the
     variable ‘mu4e-get-mail-command’, and afterwards updates the mu
     database; see Indexing your messages and Getting mail
     for details.
   • [R]eset query-results baseline this reset the current 'baseline'
     for query and updates the screen; see Bookmarks and Maildirs.
   • toggle [m]ail sending mode (direct) toggles between sending mail
     directly, and queuing it first (for example, when you are offline),
     and [f]lush queued mail flushes any queued mail.  This item is
     visible only if you have actually set up mail-queuing.  See
     Queuing mail
   • [A]bout mu4e provides general information about the program
   • [H]elp shows help information for this view
   • Finally, [q]uit mu4e quits your mu4e-session(1)

   ---------- Footnotes ----------

   (1) mu4e-quit; or with a C-u prefix argument, it merely buries the
buffer

4 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 ‘mu4e-headers-mode’.

4.1 Overview
============

An example headers view:
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

   Some notes to explain what you see in the example:

   • The fields shown in the headers view can be influenced by
     customizing the variable ‘mu4e-headers-fields’; see
     ‘mu4e-header-info’ for the list of built-in fields.  Apart from the
     built-in fields, you can also create custom fields using
     ‘mu4e-header-info-custom’; see HV Custom headers for
     details.
   • By default, the date is shown with the :human-date field, which
     shows the _time_ for today's messages, and the _date_ for older
     messages.  If you do not want to distinguish between 'today' and
     'older', you can use the :date field instead.
   • You can customize the date and time formats with the variable
     ‘mu4e-headers-date-format’ and ‘mu4e-headers-time-format’,
     respectively.  In the example, we use ‘:human-date’, which shows
     the time when the message was sent today, and the date otherwise.
   • By default, the subject is shown using the :subject field; however,
     it is also possible to use :thread-subject, which shows the subject
     of a thread only once, similar to the display of the mutt e-mail
     client.
   • The header field used for sorting is indicated by "V" or "^"(1),
     corresponding to the sort order (descending or ascending,
     respectively).  You can influence this by a mouse click, or <O>.
     Not all fields allow sorting.
   • Instead of showing the From: and To: fields separately, you can use
     From/To (:from-or-to in ‘mu4e-headers-fields’ as a more compact way
     to convey the most important information: it shows From: _except_
     when the e-mail was sent by the user (i.e., you) -- in that case it
     shows To: (prefixed by To(2), as in the example above).
   • The 'List' field shows the mailing-list a message is sent to;
     ‘mu4e’ tries to create a convenient shortcut for the mailing-list
     name; the variable ‘mu4e-user-mailing-lists’ can be used to add
     your own shortcuts.  You can use ‘mu4e-mailing-list-patterns’ to
     specify generic shortcuts.  For instance, to shorten list names to
     the part before -list, you could use:
          (setq mu4e-mailing-list-patterns '("\\`\\([-_a-z0-9.]+\\)-list"))
   • The letters in the 'Flags' field correspond to the following:
     D=_draft_, F=_flagged_ (i.e., 'starred'), N=_new_, P=_passed_
     (i.e., forwarded), R=_replied_, S=_seen_, T=_trashed_,
     a=_has-attachment_, x=_encrypted_, s=_signed_, u=_unread_.  The
     tooltip for this field also contains this information.
   • The subject field also indicates the discussion threads, following
     Jamie Zawinski's mail threading algorithm
     (https://www.jwz.org/doc/threading.html).
   • The headers view is _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
     ‘mu4e-headers-auto-update’ to ‘nil’.
   • Just before executing a search, a hook-function ‘mu4e-search-hook’
     is invoked, which receives the search expression as its parameter.
   • Also, there is a hook-function ‘mu4e-headers-found-hook’ available
     which is invoked just after mu4e has completed showing the messages
     in the headers-view.

   ---------- Footnotes ----------

   (1) or you can use little graphical triangles; see variable
‘mu4e-use-fancy-chars’

   (2) You can customize this by changing the variable
‘mu4e-headers-from-or-to-prefix’ (a cons cell)

4.2 Keybindings
===============

Using the below key bindings, you can do various things with these
messages; these actions are also listed in the Headers menu in the Emacs
menu bar.

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
?,!          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

   Some keybindings are available through minor modes:
   • Context; see Contexts.
   • Composition; see Composer and mu4e-compose-minor-mode

4.3 Marking
===========

You can _mark_ messages for a certain action, such as deletion or move.
After one or more messages are marked, you can then execute
(‘mu4e-mark-execute-all’, <x>) these actions.  This two-step
mark-execute sequence is similar to what e.g.  dired does.  It is how
mu4e tries to be as quick as possible, while avoiding accidents.

   The mark/unmark commands support the _region_ (i.e., "selection") --
so, for example, if you select some messages and press <DEL>, all
messages in the region are marked for deletion.

   You can mark all messages that match a certain pattern with <%>.  In
addition, you can mark all messages in the current thread (<T>) or
sub-thread (<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 _apply_ them before leaving, or _ignore_ them.  This behavior
can be influenced with the variable ‘mu4e-headers-leave-behavior’.

   For more information about marking, see Marking.

4.4 Sorting and threading
=========================

By default, mu4e sorts messages by date, in descending order: the most
recent messages are shown at the top.  In addition, be default mu4e
shows the message _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 _newest_ message in the thread.

   The header field used for sorting is indicated by "V" or "^"(1),
indicating the sort order (descending or ascending, respectively).

   You can change the sort order by clicking the corresponding column
with the mouse, or with ‘M-x mu4e-headers-change-sorting’ (<O>); note
that not all fields can be used for sorting.  You can toggle threading
on/off through ‘M-x mu4e-search-toggle-property’ or <Pt>.  For both of
these functions, unless you provide a prefix argument (<C-u>), the
current search is updated immediately using the new parameters.  You can
toggle full-search (see Searching) through ‘M-x
mu4e-search-toggle-property’ as well; or <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 ‘mu4e-search-sort-field’ and ‘mu4e-search-show-threads’,
as well as ‘mu4e-search-change-sorting’ to change the sorting of the
current search results.

   ---------- Footnotes ----------

   (1) or you can use little graphical triangles; see variable
‘mu4e-use-fancy-chars’

4.5 Folding threads
===================

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

   Folding stops at the _first unread message_, unless you set
‘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
‘mu4e-search-threads’ enabled; this triggers a minor mode
‘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:
       (add-hook 'mu4e-thread-mode-hook #'mu4e-thread-fold-all)

   By default, single-child threads are _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
mu4e-thread-fold-single-children.

4.6 Custom headers
==================

Sometimes the normal headers that mu4e offers (Date, From, To, Subject,
etc.) may not be enough.  For these cases, mu4e offers _custom headers_
in both the headers-view and the message-view.

   You can do so by adding a description of your custom header to
‘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 To: and Cc: fields.  Let's further suppose
that our function takes a message-plist as its argument (see Message functions).

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

   Or, let's get the contents of the Jabber-ID header.

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

   You can then add the custom header to your ‘mu4e-headers-fields’ or
‘mu4e-view-fields’, just like the built-in headers.  However, there is
an important caveat: when your custom header in ‘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 mu4e.

4.7 Actions
===========

‘mu4e-headers-action’ (<a>) lets you pick custom actions to perform on
the message at point.  You can specify these actions using the variable
‘mu4e-headers-actions’.  See Actions for the details.

   mu4e defines some default actions.  One of those is for _capturing_ a
message: <a c> 'captures' the current message.  Next, when you're
editing some message, you can include the previously captured message as
an attachment, using ‘mu4e-compose-attach-captured-message’.  See
‘mu4e-actions.el’ in the mu4e source distribution for more example
actions.

4.8 Buffer display
==================

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

4.8.1 Split view
----------------

You can control how mu4e displays its buffers, including the
Headers view and the Message view, by customizing
‘mu4e-split-view’.  There are several options available:

   • horizontal (this is the default): display the message view below
     the header view.  Use ‘mu4e-headers-visible-lines’ the set the
     number of lines shown (default: 8).
   • vertical: display the message view on the right side of the header
     view.  Use ‘mu4e-headers-visible-columns’ to set the number of
     visible columns (default: 30).
   • single-window: single window mode.  Single-window mode tries to
     minimize mu4e window operations (opening, killing, resizing, etc)
     and buffer changes, while still retaining the view and headers
     buffers.  In addition, it replaces mu4e's main view with a
     minibuffer-prompt containing the same information.
   • anything else: prefer reusing the same window, where possible.

   Note that using a window-returning _function_ for ‘mu4e-split-view’
is no longer supported, instead you can use ‘display-buffer-alist’, see
the section on further display customization.

Some useful key bindings in the split view:
   • <C-+> and <C-->: interactively change the number of columns or
     headers shown
   • You can change the selected window from the headers-view to the
     message-view and vice-versa with ‘mu4e-select-other-view’, bound to
     <y>

4.8.2 Further customization
---------------------------

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

   Let's look at some examples.

4.8.3 Fine-tuning the main buffer display
-----------------------------------------

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

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

4.8.4 Fine-tuning headers buffer display
----------------------------------------

You do not need to configure ‘mu4e-split-view’ for this to work.  In the
absence of explicit rules to the contrary, mu4e will fall back on the
value you have set in ‘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.

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

   You can type <C-x w s> to toggle the side windows to hide or show
them at will.

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

5 The message view
******************

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

   After selecting a message in the Headers view, it appears in
a message view window, which shows the message headers, followed by the
message body.  Its major mode is ‘mu4e-view-mode’, which derives from
gnus-article-mode.

5.1 Overview
============

An example message view:

    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:

    [....]

   Some notes:
   • The variable ‘mu4e-view-fields’ determines the header fields to be
     shown; see ‘mu4e-header-info’ for a list of built-in fields.  Apart
     from the built-in fields, you can also create custom fields using
     ‘mu4e-header-info-custom’; see MSGV Custom headers.
   • For search-related operations, see Searching.
   • You can scroll down the message using <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 ‘mu4e-view-scroll-to-next’
     to ‘nil’.

5.2 Keybindings
===============

You can find most things you can do with this message in the _View_
menu, or by using the keyboard; the default bindings are:

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
+,-          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

   Some keybindings are available through minor modes:
   • Context; see Contexts
   • Composition; see Composer and mu4e-compose-minor-mode

   For the marking commands, please refer to Marking messages.

5.3 Reading rich-text messages
==============================

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
mm-discouraged-alternatives for details):

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

   When displaying rich-text messages inline, mu4e (through gnus) uses
the 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.:
     (setq shr-color-visible-luminance-min 80)

   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:

     (setq gnus-unbuttonized-mime-types nil)

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

5.3.1 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 ‘gnus-inhibit-images’ to 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 ‘gnus-blocked-images’
to a regular expression or to a function that will receive a single
parameter which is not meaningful for mu4e.

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

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

   ‘mu4e’ inherits the default gnus-blocked-images from Gnus and ensures
that it works with mu4e too.  However, mu4e is not Gnus, so if you have
Gnus-specific settings for gnus-blocked-images, you should verify that
they have the desired effect in ‘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 ‘M-x mu4e-view-show-mime-parts’.  This can be a little slow.

5.4 Attachments and MIME-parts
==============================

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 text of the message your are reading.

   Many e-mail messages also contain _attachments_, which are MIME-parts
that contain files(1).

   To save such attachments as files on your computer, mu4e's
message-view offers the command ‘mu4e-view-save-attachments’; its
default keybinding is <e> (think _extract_).

   Note that when point is on the attachment label in the message, e.g.,
on something that looks like [4. application/pdf; Some Document.pdf]...,
Gnus' binding for ‘e’ prevails, which is
‘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 <RET> to save the
chosen attachments as files to your computer.

   mu4e determines the target directory using the variable
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 ‘mu4e-view-save-attachments’ with a prefix argument.

   When completing the file names, ‘mu4e-view-completion-minor-mode’ is
active, which offers ‘mu4e-view-complete-all’ (bound to <C-c C-a> to
complete _all_ files(2).

   ‘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 ‘crm-separator’ (by default,
commas) are not supported (see completing-read-multiple for further
details).  For such corner-cases, it is recommended to use
‘mu4e-view-mime-part-action’ instead, which does not have this
limitation.

5.4.1 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 ‘mu4e-view-mime-part-action’ (default key-binding
<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 ‘mu4e-view-mime-part-actions’ for the
possibilities.  You can add your own actions as well, see
MIME-part actions for an example.

   ---------- Footnotes ----------

   (1) Attachments come in two flavors: inline and attachment.  mu4e
does not distinguish between the two when operating on them: everything
that specifies a filename is considered an attachment

   (2) Except when using 'Helm'; in that case, use the Helm-mechanism
for selecting multiple

5.5 Custom headers
==================

Sometimes the normal headers (Date, From, To, Subject, etc.) may not be
enough.  For these cases, mu4e offers _custom headers_ in both the
headers-view and the message-view.

   See HV Custom headers for an example of this; the difference
for the message-view is that you should add your custom header to
‘mu4e-view-fields’ rather than ‘mu4e-headers-fields’.

5.6 Actions
===========

You can perform custom functions ("actions") on messages and their
attachments.  For a general discussion on how to define your own, see
Actions.

5.6.1 Message actions
---------------------

‘mu4e-view-action’ (<a>) lets you pick some custom action to perform on
the current message.  You can specify these actions using the variable
‘mu4e-view-actions’; mu4e defines a number of example actions.

5.6.2 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
‘mu4e-view-mime-part-actions’.

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

5.7 Detaching and reattaching messages
======================================

You can have multiple message views, but you must rename the view buffer
and detach it to stop 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 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 <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
<Z>.

   You can freely rename a message view buffer - such as with <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 _tear off_ the window a message is in and place it in a new
frame by typing <C-x w ^ f>.  You can also detach a window and put it in
its own tab with <C-x w ^ t>.

5.8 Mailing lists
=================

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

   • ‘gnus-mailing-list-subscribe’: subscribe to mailing-list
   • ‘gnus-mailing-list-unsubscribe’: unsubscribe from mailing-list
   • ‘gnus-mailing-list-help’: request help for mailing-list

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

6 Composer
**********

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

   Much of the message-mode functionality is available, as well some
mu4e-specifics.  See message for details; not every
setting is necessarily also supported in mu4e.

   The major mode for the composer is ‘mu4e-compose-mode’.

6.1 Overview
============

    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.

6.2 Entering the composer
=========================

There are a view different ways to _enter_ the composer; i.e., from
other mu4e views or even completely outside.

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

6.2.1 New message
-----------------

You can start composing a completely new message with ‘mu4e-compose-new’
(with ‘N’ from within mu4e.

6.2.2 Reply
-----------

To compose a reply to an existing message, you can use
‘mu4e-compose-reply’ (with ‘R’) from within the headers view or when
looking at some specific message.

   If you want to reply to _all_ recipients of a message, there is
‘mu4e-compose-wide-reply’, by default bound to ‘W’.  This is often
called "reply-to-all", but 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 let-bind) message-cite-function to
mu4e-message-cite-nothing.

   See Reply (message) and Wide Reply (message) for
further details.

   Note: in older versions, ‘mu4e-compose-reply’ would _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:
     (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)

6.2.3 Forward
-------------

You can _forward_ some existing message with ‘mu4e-compose-forward’
(bound to ‘F’) from within the headers view or when looking at some
specific message.  For further details, see Forwarding (message).

   To influence the way a message is forwarded, you can use the
variables ‘message-forward-as-mime’ and ‘message-forward-show-mml’.

6.2.4 Supersede
---------------

Occasionally, it can be useful to "supersede" a message you sent; for
this, there is ‘mu4e-compose-supersede’.

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

   Superseding is only possible for messages _you_ sent, as determined
by ‘mu4e-personal-or-alternative-address-p’.

   This wraps ‘message-supersede’.

6.2.5 Resend
------------

You can re-send some existing message with 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
Resending (message).

6.3 Keybindings
===============

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

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

6.4 Address autocompletion
==========================

mu4e supports autocompleting addresses when composing e-mail messages.
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
mu4e-compose-complete-addresses to 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 mu4e's completion elsewhere in emacs.  To
enable that, a function mu4e-complete-contact exists, which you can add
to completion-at-point-functions, see Completion in Buffers (elisp).
mu4e must be running for any completions to be available.

6.4.1 Limiting the number of addresses
--------------------------------------

If you have a lot of mail, especially from mailing lists and the like,
there can be a _lot_ of e-mail addresses, many of which may not be very
useful when auto-completing.  For this reason, 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:

   • ‘mu4e-compose-complete-only-personal’ -- when set to t, only
     consider addresses that were seen in _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
     --my-address parameter to mu init.

   • ‘mu4e-compose-complete-only-after’ -- only consider e-mail
     addresses last seen after some date.  Parameter is a string,
     parseable by ‘org-parse-time-string’.  This excludes old e-mail
     addresses.  The default is "2010-01-01", i.e., only consider e-mail
     addresses seen since the start of 2010.
   • ‘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.
   • ‘mu4e-contact-process-function’ -- a function to rewrite or exclude
     certain addresses.

6.5 Compose hooks
=================

If you want to change some setting, or execute some custom action before
message composition starts, you can define a _hook function_.  mu4e
offers two hooks:
   • ‘mu4e-compose-pre-hook’: this hook is run _before_ composition
     starts; if you are composing a _reply_, _forward_ a message, or
     _edit_ an existing message, the variable
     ‘mu4e-compose-parent-message’ points to the message being replied
     to, forwarded or edited, and you can use ‘mu4e-message-field’ to
     get the value of various properties (and see Message functions).
   • ‘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.
     ‘mu4e-compose-parent-message’ (see above) is also at your disposal.
   • ‘mu4e-compose-post-hook’: this hook is run when we're done with
     message compositions.  See the docstring for details.

As mentioned, ‘mu4e-compose-mode-hook’ is especially useful for
editing-related settings:

   Let's look at an example:
     (add-hook 'mu4e-compose-mode-hook
       (defun my-do-compose-stuff ()
         "My settings for message composition."
         (set-fill-column 72)
         (flyspell-mode)))

   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
Bcc:-header, you could add something like the following, using
‘message-add-header’ from ‘message-mode’.

     (add-hook 'mu4e-compose-mode-hook
       (defun my-add-bcc ()
         "Add a Bcc: header."
         (save-excursion (message-add-header "Bcc: me@example.com\n"))))

   Or to something context-specific:

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

For a more general discussion about extending mu4e, see Extending mu4e.

6.6 Signing and encrypting
==========================

Signing and encrypting of messages is possible using emacs-mime,
most easily accessed through the Attachments-menu
while composing a message, or with ‘M-x mml-secure-message-encrypt-pgp’,
‘M-x mml-secure-message-sign-pgp’.

   Important note: the messages are encrypted when they are _sent_: this
means that draft messages are _not_ encrypted.  So if you are using e.g.
offlineimap or mbsync to synchronize with some remote IMAP-service, make
sure the drafts folder is _not_ in the set of synchronized folders, for
obvious reasons.

6.7 Queuing mail
================

If you cannot send mail right now, for example because you are currently
offline, you can _queue_ the mail, and send it when you have restored
your internet connection.  You can control this from the Main view.

   To allow for queuing, you need to tell smtpmail where you want to
store the queued messages.  For example:

     (setq smtpmail-queue-mail t  ;; start in queuing mode
       smtpmail-queue-dir   "~/Maildir/queue/cur")

   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 mu4e.  The ‘mu mkdir’ command may be useful
here, so for example:

  $ mu mkdir ~/Maildir/queue
  $ touch ~/Maildir/queue/.noindex

   The file created by the ‘touch’ command tells mu to ignore this
directory for indexing, which makes sense since it contains smtpmail
meta-data rather than normal messages; see the mu-mkdir and mu-index
man-pages for details.

   _Warning_: when you switch on queued-mode, your messages _won't_
reach their destination until you switch it off again; so, be careful
not to do this accidentally!

6.8 Message signatures
======================

Message signatures are the standard footer blobs in e-mail messages
where you can put in information you want to include in every message.
The text to include is set with ‘message-signature’ (older mu4e used
‘mu4e-compose-signature’, but that has been obsoleted).

6.9 Other settings
==================

   • If you want use mu4e as Emacs' default program for sending mail,
     see Default email client.
   • Normally, mu4e _buries_ the message buffer after sending; if you
     want to kill the buffer instead, add something like the following
     to your configuration:
          (setq message-kill-buffer-on-exit t)
   • If you want to exclude your own e-mail addresses when "replying to
     all", set ‘message-dont-reply-to-names’ to
     ‘mu4e-personal-or-alternative-address-p’.  In order for this to
     work properly you need to pass your address to ‘mu init
     --my-address=’ at database initialization time, and/or use
     message-alternative-emails.

7 Searching
***********

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 ‘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 _all_
results; you can enable this with ‘M-x mu4e-search-toggle-property’, or
by customizing the variable ‘mu4e-search-full’.  This applies to all
search commands.

   You can also influence the sort order and whether threads are shown
or not; see Sorting and threading.

7.1 Queries
===========

mu4e queries are the same as the ones that mu find understands(1).  You
can consult the ‘mu-query’ man-page for the details.  In addition, mu4e
provides a command ‘mu4e-analyze-last-query’, which shows how the mu
server has interpreted the query, similar to what the the --analyze
option does for mu find.

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

   Let's look at some examples here.

   • Get all messages regarding _bananas_:
     bananas

   • Get all messages regarding _bananas_ from _John_ with an
     attachment:
     from:john and flag:attach and bananas

   • Get all messages with subject _wombat_ in June 2017
     subject:wombat and date:20170601..20170630

   • Get all messages with PDF attachments in the /projects folder
     maildir:/projects and mime:application/pdf

   • Get all messages about _Rupert_ in the /Sent Items folder.  Note
     that maildirs with spaces must be quoted.
     "maildir:/Sent Items" and rupert

   • Get all important messages which are signed:
     flag:signed and prio:high

   • Get all messages from _Jim_ without an attachment:
     from:jim and not flag:attach

   • Get all messages with Alice in one of the contacts-fields (to,
     from, cc, bcc):
     contact:alice

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

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

   • Get today's messages:
     date:today..now

   • Get all messages we got in the last two weeks regarding _emacs_:
     date:2w.. and emacs

   • Get messages from the _Mu_ mailing list:
     list:mu-discuss.googlegroups.com

     Note -- in the 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.

   • Get messages with a subject soccer, Socrates, society, ...; note
     that the '*'-wildcard can only appear as a term's rightmost
     character:
     subject:soc*

   • Get all messages _not_ sent to a mailing-list:
     NOT flag:list

   • Get all mails with attachments with filenames starting with _pic_;
     note that the '*' wildcard can only appear as the term's rightmost
     character:
     file:pic*

   • Get all messages with PDF-attachments:
     mime:application/pdf

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

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

   ---------- Footnotes ----------

   (1) with the caveat that command-line queries are subject to the
shell's interpretation before mu sees them

7.2 Bookmarks
=============

If you have queries that you use often, you may want to store them as
_bookmarks_.  Bookmark searches are available in the main view (see
Main view), header view (see Headers view), and message view
(see Message view), using (by default) the key <b> (‘M-x
mu4e-search-bookmark’), or <B> (‘M-x mu4e-search-bookmark-edit’) which
lets you edit the bookmark first.

7.2.1 Setting up bookmarks
--------------------------

mu4e provides a number of default bookmarks.  Their definition may be
instructive:

     (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 pre-defined queries that are shown on the main screen.

     Each of the list elements is a plist with at least:
     `:name'  - the name of the query
     `:query' - the query expression string or function
     `:key'   - the shortcut key (single character)

     Optionally, 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 are 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)

   You can replace these or add your own items, by putting in your
configuration (‘~/.emacs’) something like:
     (add-to-list 'mu4e-bookmarks
       '( :name  "Big messages"
          :query "size:5M..500M"
          :key   ?b))

   This prepends your bookmark to the list, and assigns the key <b> to
it.  If you want to _append_ your bookmark, you can use ‘t’ as the third
argument to ‘add-to-list’.

   In the various mu4e views, pressing <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 ‘bb’.

7.2.2 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:

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

   Another example where the user is prompted how many days old messages
should be shown:

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

   It is defining a function to make the code more readable.

7.2.3 Editing bookmarks before searching
----------------------------------------

There is also ‘M-x mu4e-search-bookmark-edit’ (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 ‘"date:today..now AND "’(1), which
limits any result to today's messages.

   ---------- Footnotes ----------

   (1) Not a valid search query by itself

7.3 Maildir searches
====================

Maildir searches are quite similar to bookmark searches (see
Bookmarks), with the difference being that the target is always a
maildir -- maildir queries provide a 'traditional' folder-like interface
to a search-based e-mail client.  By default, maildir searches are
available in the Main view, Headers view, and
Message view, with the key <j> (‘mu4e-jump-to-maildir’).  If a prefix
argument is given, the maildir query can be refined before execution.

7.3.1 Setting up maildir shortcuts
----------------------------------

You can search for maildirs like any other message property (e.g.  with
a query like maildir:/myfolder), but since it is so common, mu4e offers
a shortcut for this.

   For this to work, you need to set the variable
‘mu4e-maildir-shortcuts’ to the list of maildirs you want to have quick
access to, for example:

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

   This sets <i> as a shortcut for the /inbox folder -- effectively a
query maildir:/inbox.  There is a special shortcut <o> or </> for
_other_ (so don't use those for your own shortcuts!), which allows you
to choose from _all_ maildirs that you have.  There is support for
autocompletion; note that the list of maildirs is determined when mu4e
starts; if there are changes in the maildirs while mu4e is running, you
need to restart 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 ‘~/Maildir’, ‘/inbox’ would refer
to ‘~/Maildir/inbox’.  With these shortcuts, you can jump around your
maildirs (folders) very quickly -- for example, getting to the /lists
folder only requires you to type ‘jl’, then change to /work with ‘jw’.

   While in queries you need to quote folder names (maildirs) with
spaces in them, you should _not_ quote them when used in
‘mu4e-maildir-shortcuts’, since mu4e does that automatically for you.

   The very same shortcuts are used by ‘M-x mu4e-mark-for-move’ (default
shortcut <m>); so, for example, if you want to move a message to the
/archive folder, you can do so by typing ‘ma’.

   For further customization, you can use ‘:hide’, ‘:hide-if-no-unread’,
‘:hide-unread’ and ‘:favorite’ properties, just like for Bookmarks and Maildirs.

7.4 Other search functionality
==============================

7.4.1 Navigating through search queries
---------------------------------------

You can navigate through previous/next queries using
‘mu4e-headers-query-prev’ and ‘mu4e-headers-query-next’, which are bound
to <M-left> and <M-right>, similar to what some web browsers do.

   mu4e tries to be smart and not record duplicate queries.  Also, the
number of queries remembered has a fixed limit, so 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 ‘M-x
mu4e-headers-forget-queries’.

7.4.2 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 (‘M-x mu4e-headers-jump-to-maildir’, <j>) or
because you followed some bookmark (‘M-x mu4e-search-bookmark’, <b>).
Now, you want to narrow things down to only those messages that have
attachments.

   This is when ‘M-x mu4e-search-narrow’ (</>) 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.  <\> takes you back
to the previous query, so, effectively 'widens' the search.
Technically, narrowing the results of query x with expression y implies
doing a search (x) AND (y).

   Note that messages that were not in your original search results
because of ‘mu4e-search-results-limit’ may show up in the narrowed
query.

7.4.3 Including related messages
--------------------------------

It can be useful to not only show the messages that directly match a
certain query, but also include messages that are related to these
messages.  That is, messages that belong to the same discussion threads
are included in the results, just like e.g.  Gmail does it.  You can
enable this behavior by setting ‘mu4e-search-include-related’ to ‘t’,
and you can toggle between including/not-including using <P>
(‘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 _other_
folders.

7.4.4 Skipping duplicates
-------------------------

Another useful feature is skipping of _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 offlineimap, since that is
the way the labels / virtual folders in Gmail are represented.  You can
enable skipping duplicates by setting ‘mu4e-search-skip-duplicates’ to
‘t’, and you can toggle the value using <P>
(‘mu4e-search-toggle-property’).

   Note, messages are considered duplicates when they have the same
Message-Id.

8 Marking
*********

In mu4e, the common way to do things with messages is a two-step process
- first you _mark_ them for a certain action, then you _execute_ (<x>)
those marks.  This is similar to the way dired operates.  Marking can
happen in both the Headers view and the Message view.

8.1 Marking messages
====================

There are multiple ways to mark messages:
   • _message at point_: you can put a mark on the message-at-point in
     either the Headers view or Message view
   • _region_: you can put a mark on all messages in the current region
     (selection) in the Headers view
   • _pattern_: you can put a mark on all messages in the Headers view
     matching a certain pattern with ‘M-x
     mu4e-headers-mark-pattern’ (<%>)
   • _thread/subthread_: You can put a mark on all the messages in the
     thread/subthread at point with ‘M-x mu4e-headers-mark-thread’ and
     ‘M-x mu4e-headers-mark-subthread’, respectively.  When you haven't
     enabled separate threads in the headers view, the thread marking
     functions simply mark _all_ messages.

8.2 What to mark for
====================

mu4e supports a number of marks:

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

   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(1).  For
this reason, you can disable this by setting ‘mu4e-headers-show-target’
to ‘nil’.

   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(2)
Later, you can set the actual mark using ‘M-x
mu4e-mark-resolve-deferred-marks’ (<#>).  Alternatively, mu4e will ask
you when you try to execute the marks (<x>).

   ---------- Footnotes ----------

   (1) this uses an Emacs feature called _overlays_, which are slow when
used a lot in a buffer

   (2) This kind of 'deferred marking' is similar to the facility in
dired, midnight commander (<https://www.midnight-commander.org/>) and
the like, and uses the same key binding (<insert>).

8.3 Executing the marks
=======================

After you have marked some messages, you can execute them with <x> (‘M-x
mu4e-mark-execute-all’).

   A hook, ‘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.

8.4 Trashing messages
=====================

When "trashing" a message, it is moved to a trash-folder (i.e.,
‘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
_immediate_ removal.

   For such cases, you can influence mu4e's behavior; see
‘mu4e-trash-without-flag’.

8.5 Leaving the headers buffer
==============================

When you quit or update a headers buffer that has marked messages (for
example, by doing a new search), mu4e asks you what to do with them,
depending on the value of the variable ‘mu4e-headers-leave-behavior’ --
see its documentation.

8.6 Built-in marking functions
==============================

Some examples of mu4e's built-in marking functions.

   • _Mark the message at point for trashing_: press <d>
   • _Mark all messages in the buffer as unread_: press ‘C-x h o’
   • _Delete the messages in the current thread_: press ‘T D’
   • _Mark messages with a subject matching "hello" for flagging_: press
     ‘% s hello RET’.

8.7 Custom mark functions
=========================

Sometimes, the built-in functions to mark messages may not be sufficient
for your needs.  For this, mu4e offers an easy way to define your own
custom mark functions.  You can choose one of the custom marker
functions by pressing <&> in the Headers view and Message view.

   Custom mark functions are to be appended to the list
‘mu4e-headers-custom-markers’.  Each of the elements of this list
('markers') is a list with two or three elements:
  1. 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.
  2. a predicate function, taking two arguments ‘msg’ and ‘param’.
     ‘msg’ is the message plist (see Message functions) and
     ‘param’ is a parameter provided by the third of the marker elements
     (see the next item).  The predicate function should return non-nil
     if the message matches.
  3. (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.

   Let's look at an example: suppose we want to match all messages that
have more than _n_ recipients -- we could do this with the following
recipe:

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

   After evaluating this expression, you can use it by pressing <&> in
the headers buffer to select a custom marker function, and then <M> to
choose this particular one (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
‘mu4e-headers-custom-markers’; see ‘mu4e-headers.el’ and see
Extending mu4e for general information about writing your own
functions.

8.8 Adding a new kind of mark
=============================

It is possible to configure new marks, by adding elements to the list
‘mu4e-marks’.  Such an element must have the following form:

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

   The symbol can be any symbol, except for the symbols ‘unmark’ and
‘something’, which are reserved.  The rest is a plist with the following
elements:

   • ‘:char’ -- the character to display in the headers view.
   • ‘:prompt’ -- the prompt to use when asking for marks (used for
     example when marking a whole thread).
   • ‘:ask-target’ -- a function run once per bulk-operation, and thus
     suitable for querying the user about a target for move-like marks.
     If nil, the TARGET passed to ‘:dyn-target’ is nil.
   • ‘:dyn-target’ -- a function run once per message (The message is
     passed as MSG to the function).  This function allows to compute a
     per-message target, for refile-like marks.  If nil, the DYN-TARGET
     passed to the ‘:action’ is the TARGET obtained as above.
   • ‘:show-target’ -- how to display the target in the headers view.
     If ‘:show-target’ is nil the DYN-TARGET is shown (and DYN-TARGET
     must be a string).
   • ‘:action’ -- the action to apply on the message when the mark is
     executed.

9 Contexts
**********

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

   Note that there are a number of existing ways to switch accounts in
mu4e, for example using the method described in the Tips and Tricks
section of this manual.  Those still work -- but the new
mechanism has the benefit of being a core part of ‘mu4e’, thus allowing
for deeper integration.

9.1 What are contexts
=====================

Let's see what's contained in a context.  Most of it is optional.

   A ‘mu4e-context’ is Lisp object with the following members:
   • name: the name of the context, e.g.  work or private in the default
     completion UI, mu4e uses the first letter of the context to select
     them, so you should ensure all start with a different letter
   • vars: an association-list (alist) of variable settings for this
     account.
   • enter-func: an (optional) function that takes no parameter and is
     invoked when entering the context.  You can use this for extra
     setup etc.
   • leave-func: an (optional) function that takes no parameter and is
     invoked when leaving the context.  You can use this for clearing
     things up.
   • match-func: an (optional) function that takes an MSG message plist
     as argument, and returns non-nil if this context matches the
     situation.  mu4e uses the first context that matches, in a couple
     of situations:
        • when starting mu4e to determine the starting context; in this
          case, MSG is nil.  You can use e.g.  the host you're running
          or the time of day to determine which context matches.
        • before replying to or forwarding a message with the given
          message plist as parameter, or nil when composing a brand new
          message.  The function should return t when this context is
          the right one for this message, or nil otherwise.
        • when determining the target folders for deleting, refiling
          etc; see Contexts and special folders.

   mu4e uses a variable ‘mu4e-contexts’, which is a list of such
objects.

9.2 Context policies
====================

When you have defined contexts and you start mu4e it decides which
context to use based on the variable ‘mu4e-context-policy’; similarly,
when you compose a new message, the context is determined using
‘mu4e-compose-context-policy’.

   For both of these, you can choose one of the following policies:
   • a symbol ‘always-ask’: unconditionally ask the user what context to
     pick.

   The other choices only apply if none of the contexts match (i.e.,
none of the contexts' match-functions returns ‘t’).  We have the
following options:

   • a symbol ‘ask’: ask the user if mu4e can't figure things out the
     context by itself (through the match-function).  This is a good
     policy if there are no match functions, or if the match functions
     don't cover all cases.
   • a symbol ‘ask-if-none’: if there's already a context, don't change
     it; otherwise, ask the user.
   • a symbol ‘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.
   • ‘nil’: don't change the context; this is useful if you don't change
     contexts very often, and e.g.  manually changes contexts with ‘M-x
     mu4e-context-switch’.

   You can easily switch contexts manually using the ‘;’ key from the
main screen.

9.3 Contexts and special folders
================================

As we discussed in Folders and Dynamic folders, mu4e
recognizes a number of special folders: ‘mu4e-sent-folder’,
‘mu4e-drafts-folder’, ‘mu4e-trash-folder’ and ‘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 mu4e needs to know the value for
such a special folder for a given message, it tries to determine the
appropriate context using ‘mu4e-context-determine’ (and policy nil; see
Context policies).  If it finds a matching context, it let-binds
the ‘vars’ for that account, and then determines the value for the
folder.  It does not, however, call the ‘enter-func’ or ‘leave-func’,
since we are not really switching contexts.

   In practice, this means that as long as each of the accounts has a
good match-func, all message operations automatically find the
appropriate folders.

9.4 Example
===========

Let's explain how contexts work by looking at an example.  We define two
contexts, 'Private' and 'Work' for a fictional user _Alice Derleth_.

   Note that in this case, we automatically switch to the first context
when starting; see the discussion in the previous section.

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

   A couple of notes about this example:
   • You can manually switch the context use ‘M-x mu4e-context-switch’,
     by default bound to ‘;’ in headers, view and main mode.  The
     current context appears in the modeline by default; see
     Modeline for details.
   • Normally, ‘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 (‘C-u’), you can force mu4e to
     invoke those function even in that case.
   • The function ‘mu4e-context-current’ returns the current-context;
     the current context is also visible in the mode-line when in
     headers, view or main mode.
   • You can set any kind of variable; including settings for mail
     servers etc.  However, settings such as ‘mu4e-mu-home’ are not
     changeable after they have been set without quitting mu4e first.
   • ‘leave-func’ (if defined) for the context we are leaving, is
     invoked before the ‘enter-func’ (if defined) of the context we are
     entering.
   • ‘enter-func’ (if defined) is invoked before setting the variables.
   • ‘match-func’ (if defined) is invoked just before
     ‘mu4e-compose-pre-hook’.
   • See the variables ‘mu4e-context-policy’ and
     ‘mu4e-compose-context-policy’ to tweak what mu4e should do when no
     context matches (or if you always want to be asked).
   • Finally, be careful to get the quotations right -- backticks,
     single quotes and commas and note the '.'  between variable name
     and its value.

10 Dynamic folders
******************

In Folders, we explained how you can set up mu4e's special
folders:
     (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

   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 _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 mu4e and
writing your own functions, see Extending mu4e.

   If you use mu4e-context, see Contexts and special folders for
what that means for these special folders.

10.1 Smart refiling
===================

When refiling messages, perhaps to archive them, it can be useful to
have different target folders for different messages, based on some
property of those message -- smart refiling.

   To accomplish this, we can set the refiling folder
(‘mu4e-refile-folder’) to a function that returns the actual refiling
folder for the particular message.  An example should clarify this:

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

This can be very powerful; you can select some messages in the headers
view, then press <r>, and have them all marked for refiling to their
particular folders.

   Some notes:
   • We set ‘mu4e-refile-folder’ to an anonymous (lambda) function.
     This function takes one argument, a message plist(1).  The plist
     corresponds to the message at point.  See Message functions
     for a discussion on how to deal with them.
   • In our function, we use a cond control structure; the function
     returns the first of the clauses that matches.  It's important to
     make the last clause a catch-all, so we always return _some_
     folder.
   • We use the convenience function
     ‘mu4e-message-contact-field-matches’, which evaluates to ‘t’ if any
     of the names or e-mail addresses in a contact field (in this case,
     the To:-field) matches the regular expression.  With mu4e version
     0.9.16 or newer, the contact field can in fact be a list instead of
     a single value, such as ‘'(:to :cc)'’.

   ---------- Footnotes ----------

   (1) a property list describing a message

10.2 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 _original_ message, that is, the message you reply
to, or forward, or edit.  If there is no such message (for example when
composing a brand new message) the message parameter is nil.

   Let's look at an example.  Suppose you want a different trash folder
for work-email.  You can achieve this with something like:

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

Good to remember:
   • The ‘msg’ parameter you receive in the function refers to the
     _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 ‘msg’
     parameter is ‘nil’.
   • When re-editing messages, the value of ‘mu4e-drafts-folder’ is
     ignored.

11 Actions
**********

mu4e lets you define custom actions for messages in Headers view
and for both messages and attachments in the Message view.
Custom actions allow you to easily extend mu4e for specific needs -- for
example, marking messages as spam in a spam filter or applying an
attachment with a source code patch.

   You can invoke the actions with key <a> for actions on messages, and
key <A> for actions on attachments.

   For general information extending mu4e and writing your own
functions, see Extending mu4e.

11.1 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 MSG
parameter, which corresponds to the message at point.  Something like:
     (defun my-action-func (msg)
       "Describe my message function."
       ;; do stuff
       )

Functions that operate on attachments receive a MSG parameter, which
corresponds to the message at point, and an ATTACHMENT-NUM, which is the
number of the attachment as seen in the message view.  An attachment
function looks like:
     (defun my-attachment-action-func (msg attachment-num)
       "Describe my attachment function."
       ;; do stuff
       )

After you have defined your function, you can add it to the list of
actions(1), either ‘mu4e-headers-actions’, ‘mu4e-view-actions’ or
‘mu4e-view-mime-part-actions’.  The format(2) of each action is a
cons-cell, ‘(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.

   ---------- Footnotes ----------

   (1) Instead of defining the functions separately, you can obviously
also add a ‘lambda’-function directly to the list; however, separate
functions are easier to change

   (2) 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;
mu4e warns you when you are using the old format.

11.2 Headers view actions
=========================

Suppose we want to inspect the number of recipients for a message in the
Headers view.  We add the following to our configuration:

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

   After evaluating this, ‘a N’ in the headers view shows the number of
recipients for the message at point.

11.3 Message view actions
=========================

As another example, suppose we would like to search for messages by the
sender of the message at point:

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

   If you wonder why we use ‘car’, remember that the From:-field is a
list of ‘(:name NAME :email EMAIL)’ plists; so this code gets us the
e-mail address of the first in the list.  From:-fields rarely have more
that one address.

11.4 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 <n> as its shortcut key (the <n> is prefixed to
the description).  See the the ‘mu4e-view-mime-part-actions’ for the
details of the format.

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

   Or another one, to import a calendar invitation into the venerable
emacs diary:
     (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))

11.5 Example actions
====================

mu4e includes a number of example actions in the file ‘mu4e-actions.el’
in the source distribution (see ‘C-h f mu4e-action-TAB’).  For example,
for viewing messages in an external web browser or tagging.

   It is easy to add such actions to your configuration; for instance,
to enable _tagging_(1) both in the message view and headers view, you
could add:
     (add-to-list 'mu4e-headers-actions
                  '("Tag message" . mu4e-action-retag-message))
     (add-to-list 'mu4e-view-actions
                  '("Tag message" . mu4e-action-retag-message))

   ---------- Footnotes ----------

   (1) mu4e does not offer tagging by default since it mutates the
message files, something that mu/mu4e generally try to avoid.

12 Extending mu4e
*****************

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

12.1 Extension points
=====================

There are a number of places where mu4e lets you plug in your own
functions:
   • Custom functions for message header -- see HV Custom headers
   • Using message-specific folders for drafts, trash, sent messages and
     refiling, based on a function -- see Dynamic folders
   • Using an attachment-specific download-directory -- see the variable
     ‘mu4e-attachment-dir’.
   • Apply a function to a message in the headers view - see
     Headers view actions
   • Apply a function to a message in the message view -- see
     Message view actions
   • Add a new kind of mark for use in the headers view - see
     Adding a new kind of mark
   • Apply a function to a MIME-part -- see MIME-part actions
   • Custom function to mark certain messages -- see Custom mark functions
   • Using various _mode_-hooks, ‘mu4e-compose-pre-hook’ (see
     Compose hooks), ‘mu4e-index-updated-hook’ (see FAQ)

You can also write your own functions without using the above.  If you
want to do so, key useful functions are ‘mu4e-message-at-point’ (see
below), ‘mu4e-headers-for-each’ (to iterate over all headers, see its
docstring) and ‘mu4e-view-for-each-part’ (to iterate over all
parts/attachments, see its docstring).  There is also
‘mu4e-view-for-each-uri’ to iterate of all the URIs in the current
message.

   Another useful function is ‘mu4e-headers-find-if’ which searches for
a message matching a certain pattern; again, see its docstring.

12.2 Available functions
========================

The whole of mu4e consists of hundreds of elisp functions.  However, the
majority of those are for _internal_ use only; you can recognize them
easily, because they all start with ‘mu4e~’ or ‘mu4e--’.  These
functions make all kinds of assumptions, and they are subject to change,
and should therefore _not_ be used.  The same is true for _variables_
with the same prefix; don't touch them.  Let me repeat that:
Do not use mu4e~... or mu4e-- functions or variables!

In addition, you should use functions in the right context; functions
that start with mu4e-view- are only applicable to the message view,
while functions starting with mu4e-headers- are only applicable to the
headers view.  Functions without such prefixes are applicable
everywhere.

12.3 Message functions
======================

Many functions in 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 ‘mu4e-message-’ functions (in ‘mu4e-message.el’), such as
‘mu4e-message-field’ and ‘mu4e-message-at-point’, and a shortcut to
combine the two, ‘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:
     (mu4e-message-field (mu4e-message-at-point) :subject)
Note that:
   • The contact fields (To, From, Cc, Bcc) are lists of cons-pairs
     ‘(name . email)’; ‘name’ may be ‘nil’.  So, for example:
            (mu4e-message-field some-msg :to)
            ;; => (("Jack" . "jack@example.com") (nil . "foo@example.com"))

     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 ‘mu4e-message-contact-field-matches’ to make this easy.
   • The message body is only available in the message view, not in the
     headers view.

   Note that in headers-mode, you only have access to a reduced message
plist, without the information about the message-body or mime-parts;
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 procmail's formail:

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

12.4 Contact functions
======================

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

   To handle this, mu4e provides ‘mu4e-contact-process-function’, which,
if defined, is applied to each contact.  If the result is 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.,
"Foo Bar" <foo.bar@example.com>
   or
cuux@example.com

   An example ‘mu4e-contact-process-function’ might look like:

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

12.5 Utility functions
======================

‘mu4e-utils’ contains a number of utility functions; we list a few here.
See their docstrings for details:
   • ‘mu4e-read-option’: read one option from a list.  For example:
          (mu4e-read-option "Choose an animal: "
          '(("Monkey" . monkey) ("Gnu" . gnu) ("xMoose" . moose)))
     The user is presented with:
          Choose an animal: [M]onkey, [G]nu, [x]Moose
   • ‘mu4e-ask-maildir’: ask for a maildir; try one of the shortcuts
     (‘mu4e-maildir-shortcuts’), or the full set of available maildirs.
   • ‘mu4e-running-p’: return ‘t’ if the mu4e process is running, ‘nil’
     otherwise.
   • ‘(mu4e-user-mail-address-p addr)’: return ‘t’ if ADDR is one of the
     user's e-mail addresses (as per ‘(mu4e-personal-addresses)’).
   • ‘mu4e-log’ logs to the mu4e debugging log if it is enabled; see
     ‘mu4e-toggle-logging’.
   • ‘mu4e-message’, ‘mu4e-warning’, ‘mu4e-error’ are the mu4e
     equivalents of the normal elisp ‘message’, ‘user-error’ and ‘error’
     functions.

13 Integrating mu4e with Emacs facilities
*****************************************

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

13.1 Default email client
=========================

Emacs allows you to select an e-mail program as the default program it
uses when you press <C-x m> (‘compose-mail’), call ‘report-emacs-bug’
and so on; see Mail Methods (emacs).

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

     (setq mail-user-agent 'mu4e-user-agent)

   Similarly, to specify mu4e as your preferred method for reading mail,
customize the variable ‘read-mail-command’.

     (set-variable 'read-mail-command 'mu4e)

13.2 Modeline
=============

One of the most visible ways in which mu4e integrates with Emacs is
through the _modeline_ See Mode Line (emacs).  The mu4e support for
that is handled through a minor-mode ‘mu4e-modeline-mode’, which is
enabled by default when mu4e is running.

   To completely turn off the modeline support, set
‘mu4e-modeline-support’ to nil before starting mu4e.

   mu4e shares information on the modeline in two ways:
   • buffer-specific
        • current context (as per Contexts)
        • current query parameters (headers-mode only)
   • global: information about the results for the "favorite query"

   The global indicators can be disabled by setting
‘mu4e-modeline-show-global’ to nil.

   All of the bookmark items provide more details in their ‘help-echo’,
i.e., their tooltip.

13.2.1 Query parameters bookmark item
-------------------------------------

The query parameters in the modeline start with the various query flags
(such as some representation of ‘mu4e-search-threads’,
‘mu4e-search-full’; the help-echo (tool-tip) has the details.

   The query parameters are followed by the query-string use 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 ‘mu4e-modeline-prefer-bookmark-name’ to
nil.

13.2.2 Favorite bookmark modeline item
--------------------------------------

The global modeline contains the results of some specific "favorite"
bookmark query from ‘mu4e-bookmarks’.  By default, the _first_ one in
chosen, but you may want to change that by using the ‘:favorite’
property for a particular query, e.g., as part of your MU4E-BOOKMARKS:
      ;; Monitor the inbox folder in the modeline
      (:query "maildir:/inbox" :name "Inbox" :key ?i :favorite t)

   The results of this query (the last time it was updated) is shown as
some character or emoji (depending on MU4E-USE-FANCY-CHARS) and 2 or 3
numbers, just like what we saw in Bookmarks and Maildirs, e.g.,
      N:10(+5)/15

   this means there are _10 unread messages_, with _5 new messages since
the baseline_, and _15 messages in total_ matching the query.

   You can customize the icon; see MU4E-MODELINE-ALL-CLEAR,
MU4E-MODELINE-ALL-READ, MU4E-MODELINE-UNREAD-ITEMS and
MU4E-MODELINE-NEW-ITEMS.

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

13.3 Transient
==============

mu4e has experimental support for the "transient" menus, as per
transient.  Because "transient" is not automatically available
in all Emacs version that mu4e support, you need to manually enable it:
     (when (require 'mu4e-transient nil 'noerror)
       (global-set-key (kbd "C-c m")  mu  #'mu4e-transient-menu))

13.4 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 Bookmarks and Maildirs, in the main
view and the Modeline, and thus gives updates when there 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
Desktop Notifications (elisp).

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

13.5 Emacs bookmarks
====================

Note, 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 mu4e.

   mu4e supports linking to the message-at-point through the normal
Emacs built-in bookmark system.  The links are based on the message's
message-id, and thus the bookmarks stay valid even if you move the
message around.

13.6 Eldoc
==========

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

13.7 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 mu4e, and

13.7.1 Org-mode links
---------------------

It can be useful to include links to e-mail messages or search queries
in your org-mode files.  mu4e supports this by default, unless you set
mu4e-support-org to ‘nil’.

   You can use the normal org-mode mechanisms to store links: ‘M-x
org-store-link’ stores a link to a particular message when you are in
Message view.  When you are in Headers view, ‘M-x
org-store-link’ links to the _query_ if
‘mu4e-org-link-query-in-headers-mode’ is non-‘nil’, and to the
particular message otherwise (which is the default).  You can customize
the link description using ‘mu4e-org-link-desc-func’.

   You can insert this link later with ‘M-x org-insert-link’.  From
org-mode, you can go to the query or message the link points to with
either ‘M-x org-agenda-open-link’ in agenda buffers, or ‘M-x
org-open-at-point’ elsewhere -- both typically bound to ‘C-c C-o’.

   You can also directly _capture_ such links -- for example, to add
e-mail messages to your todo-list.  For that, mu4e-org has a function
‘mu4e-org-store-and-capture’.  This captures the message-at-point (or
header -- see the discussion on ‘mu4e-org-link-query-in-headers-mode’
above), then calls 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:

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

   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
‘org-capture-templates’:

       ("P" "process-soon" entry (file+headline "todo.org" "Todo")
       "* TODO %:fromname: %a %?\nDEADLINE: %(org-insert-time-stamp (org-read-date nil t \"+2d\"))")

   If you use the functionality a lot, you may want to define
key-bindings for that in headers and view mode:

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

13.7.2 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
org-capture-templates:
     ("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)

   Then invoke this template from sent-hook:
     (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)

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

13.8 iCalendar
==============

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

     (require 'mu4e-icalendar)
     (mu4e-icalendar-setup)

   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:

     (setq mu4e-icalendar-trash-after-reply t)

   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

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

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

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

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

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

   By default, ‘gnus-icalendar-org-setup’ adds a temporary capture
template to the variable ‘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
‘gnus-icalendar-org-setup’ is called.

   The full default capture template is:

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

   where the values of the variables ‘gnus-icalendar-org-capture-file’
and ‘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:

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

   Note that the default behaviour for ‘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
‘: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 ‘org-capture’
functions use that to set the ‘datetree’ location:

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

   If you do this, you'll want to omit the ‘:timeprompt t’ setting from
your capture template.

13.9 Speedbar
=============

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

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

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

13.10 Dired
===========

It is possible to attach files to mu4e messages using dired (see
emacs), using the following steps (based on a post on the
mu-discuss mailing list by _Stephen Eglen_).

     (add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode)

   Then, mark the file(s) in dired you would like to attach and press
C-c RET C-a, and you'll be asked whether to attach them to an existing
message, or create a new one.

Appendix A Other tools
**********************

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

A.1 Org-contacts
================

Note, mu4e supports built-in address autocompletion; see Address autocompletion,
and that is the recommended way to do this.  However,
it is also possible to manage your addresses with org-mode, using
org-contacts
(https://julien.danjou.info/projects/emacs-packages#org-contacts).

   mu4e-actions defines a useful action (see Actions) for adding a
contact based on the From:-address in the message at point.  To enable
this, add to your configuration something like:

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

After this, you should be able to add contacts using <a o> in the
headers view and the message view, using the org-capture mechanism.
Note, the shortcut character <o> is due to the first character of
org-contact-add.

A.2 BBDB
========

Note, mu4e supports built-in address autocompletion; see Address autocompletion,
and that is the recommended way to do this.  However,
it is also possible to manage your addresses with BBDB
(https://savannah.nongnu.org/projects/bbdb/).

   To enable BBDB, add to your ‘~/.emacs’ (or its moral equivalent, such
as ‘~/.emacs.d/init.el’) the following _after_ the ‘(require 'mu4e)’
line:

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

   For recent emacs (29 and later), address-completion may need some
extra setup:
     (add-hook 'message-mode-hook
               (lambda ()
                 (add-to-list 'completion-at-point-functions
                              #'eudc-capf-complete)))
   or, if that does not work:
     (add-hook 'message-mode-hook
               (lambda ()
                 (add-to-list 'completion-at-point-functions
                              #'message-expand-name)))

After this, you should be able to:
   • In mu4e-view mode, add the sender of the email to BBDB with <C-u :>
   • Tab-complete addresses from BBDB when composing emails
   • View the BBDB contact while viewing a message

A.3 Sauron
==========

The Emacs package sauron (https://github.com/djcb/sauron) (by the same
author) can be used to get notifications about new mails.  If you run
something like the below script from your crontab (or have some other
way of having it execute every _n_ minutes), you receive notifications
in the sauron-buffer when new messages arrive.

#!/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

You might want to put:
     (setq sauron-dbus-cookie t)
in your setup, to allow the script to find the D-Bus session bus, even
when running outside its session.

A.4 Hydra
=========

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

   With Hydra installed, we can add multi-character shortcuts, for
instance:
     (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.

Appendix B 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.

B.1 Minimal configuration
=========================

An (almost) minimal configuration for mu4e might look like this -- as
you see, most of it is commented-out.

     ;; example configuration for mu4e

     ;; make sure mu4e is in your load-path
     (require 'mu4e)

     ;; use mu4e for e-mail in emacs
     (setq mail-user-agent 'mu4e-user-agent)

     ;; these must start with a "/", and must exist
     ;; (i.e.. /home/user/Maildir/sent must exist)
     ;; you use e.g. 'mu mkdir' to make the Maildirs if they don't
     ;; already exist

     ;; below are the defaults; if they do not exist yet, mu4e offers to
     ;; create them. they can also functions; see their docstrings.
     ;; (setq mu4e-sent-folder   "/sent")
     ;; (setq mu4e-drafts-folder "/drafts")
     ;; (setq mu4e-trash-folder  "/trash")

     ;; smtp mail setting; these are the same that `gnus' uses.
     (setq
        message-send-mail-function   'smtpmail-send-it
        smtpmail-default-smtp-server "smtp.example.com"
        smtpmail-smtp-server         "smtp.example.com"
        smtpmail-local-domain        "example.com")

B.2 Longer configuration
========================

A somewhat longer configuration, showing some more things that you can
customize.

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

B.3 Gmail configuration
=======================

_Gmail_ is a popular e-mail provider; let's see how we can make it work
with mu4e.  Since we are using 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 Including related messages,
and in Skipping duplicates.

B.3.1 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 offlineimap; on Debian (and derivatives
like Ubuntu), this is as easy as:

$ sudo apt-get install offlineimap

   while on Fedora (and similar) you need:
$ sudo yum install offlineimap

   Then, we can configure offlineimap by editing ‘~/.offlineimaprc’:

[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

   Obviously, you need to replace USERNAME and PASSWORD with your actual
Gmail username and password.  After this, you should be able to download
your mail:

$ 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

   We can now run ‘mu’ to make sure things work:

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

   We can run both the offlineimap and the mu index from within 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 _not_ want to
synchronize your Drafts-folder, since it contains the unencrypted
messages.  You can use OfflineIMAP's folderfilter for that.

B.3.2 Settings
--------------

Next step: let's make a mu4e configuration for this:

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

     ;; alternatively, for emacs-24 you can use:
     ;;(setq message-send-mail-function 'smtpmail-send-it
     ;;     smtpmail-stream-type 'starttls
     ;;     smtpmail-default-smtp-server "smtp.gmail.com"
     ;;     smtpmail-smtp-server "smtp.gmail.com"
     ;;     smtpmail-smtp-service 587)

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

   And that's it -- put the above in your emacs initialization file,
change USERNAME etc.  to your own, restart Emacs, and run ‘M-x mu4e’.

B.4 Other settings
==================

Finally, here are some more settings that are useful, but not enabled by
default for various reasons.

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

Appendix C FAQ -- Frequently Asked Questions
********************************************

In this chapter we list a number of actual and anticipated questions and
their answers.

C.1 General
===========

C.1.1 Results from mu and mu4e differ - why?
--------------------------------------------

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

C.1.2 The unread/all counts in the main-screen differ from the 'real' numbers - what's going on?
------------------------------------------------------------------------------------------------

For speed reasons, the counts do not exclude messages that no longer
exist in the file-system, nor do they exclude duplicate messages; see
mu-mu4e-differ.

C.1.3 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., <DEL> for
delete, <m> for move and <t> for trash) apply to all selected messages.
You can also use functions like ‘mu4e-headers-mark-thread’ (<T>),
‘mu4e-headers-mark-subthread’ (<t>) to mark whole threads at the same
time, and ‘mu4e-headers-mark-pattern’ (<%>) 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 _all_ messages.

C.1.4 Can I automatically apply the marks on messages when leaving the headers buffer?
--------------------------------------------------------------------------------------

Yes you can -- see the documentation for the variable
mu4e-headers-leave-behavior.

C.1.5 How can I set mu4e as the default e-mail client in Emacs?
---------------------------------------------------------------

See Default email client.

C.1.6 Can mu4e use some fancy Unicode instead of these boring plain-ASCII ones?
-------------------------------------------------------------------------------

Glad you asked!  Yes, if you set ‘mu4e-use-fancy-chars’ to t, mu4e uses
such fancy characters in a number of places.  Since not all fonts
include all characters, you may want to install the unifont and/or
symbola fonts on your system.

C.1.7 Can I start mu4e in the background?
-----------------------------------------

Yes -- if you provide a prefix-argument (<C-u>), mu4e starts, but does
not show the main-window.

C.1.8 Does mu4e support searching for CJK (Chinese-Japanese-Korean) characters?
-------------------------------------------------------------------------------

Only partially.  If you have Xapian 1.2.8 or newer, and set the
environment variable XAPIAN_CJK_NGRAM to non-empty before indexing, both
when using mu from the command-line and from mu4e.

C.1.9 How can I customize the function to select a folder?
----------------------------------------------------------

The 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 completing-read.  The default value is
‘ido-completing-read’; to use emacs's default behavior, set the variable
to ‘completing-read’.  Helm users can use the same value, and by
enabling ‘helm-mode’ use helm-style completion.

C.1.10 With a lot of Maildir folders, jumping to them can get slow. What can I do?
----------------------------------------------------------------------------------

Set ‘mu4e-cache-maildir-list’ to ‘t’ (make sure to read its docstring).

C.1.11 How can I hide certain messages from the search results?
---------------------------------------------------------------

See the variables ‘mu4e-headers-hide-predicate’ and
‘mu4e-headers-hide-enabled’.  The latter can be toggled through
‘mu4e-search-toggle-property’.

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

C.1.12 I'm getting an error 'Variable binding depth exceeds max-specpdl-size' when using mu4e - what can I do about it?
-----------------------------------------------------------------------------------------------------------------------

The error occurs because mu4e is binding more variables than emacs
allows for, by default.  You can avoid this by setting a higher value,
e.g.  by adding the following to your configuration:
     (setq max-specpdl-size 5000)
   Note that Emacs 29 obsoletes this variable.

C.2 Retrieving mail
===================

C.2.1 How can I get notifications when receiving mail?
------------------------------------------------------

The recommended way is to use mu4e's built-in notification system, see
Desktop notifications.

   Alternatively, you can set things up manually.

   There is ‘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 aplay and some soundfile, change as needed):
     (add-hook 'mu4e-index-updated-hook
       (defun new-mail-sound ()
         (shell-command "aplay ~/Sounds/boing.wav&")))

C.2.2 I'm getting mail through a local mail-server. What should I use for ‘mu4e-get-mail-command’?
--------------------------------------------------------------------------------------------------

Use the literal string "true" (or don't do anything, it's the default)
which then uses /bin/true (a command that does nothing and always
succeeds).  This makes getting mail a no-op, but the messages are still
re-indexed.

C.2.3 How can I re-index my messages without getting new mail?
--------------------------------------------------------------

Use ‘M-x mu4e-update-index’

C.2.4 When I try to run mu index while mu4e is running I get errors
-------------------------------------------------------------------

For instance:
mu: mu_store_new_writable: xapian error
  'Unable to get write lock on ~/.cache/mu/xapian: already locked
   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 mu4e can do about this, but
if is another ‘mu’ instance that is holding the lock, you can ask it to
(gracefully) terminate:
   pkill -2 -u $UID mu # send SIGINT
   sleep 1
   mu index
   mu4e automatically restarts mu when it needs it.  In practice, this
seems to work quite well.

C.2.5 How can I disable the Indexing... messages?
-------------------------------------------------

Set the variable ‘mu4e-hide-index-messages’ to non-nil.

C.2.6 IMAP-synchronization
--------------------------

Some IMAP-synchronization programs such as mbsync (but not offlineimap)
don't like it when message files do not change their names when they are
moved to different folders.  mu4e can attempt to help with this - you
can set the variable ‘mu4e-change-filenames-when-moving’ to non-nil.

   Also, some of these programs may interpret the "trash" flag
differently; see ‘mu4e-trash-without-flag’ for how to influence that.

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

C.2.7 ‘offlineimap’ and UTF-7
-----------------------------

‘offlineimap’ uses IMAP's UTF-7 for encoding non-ascii folder names,
while ‘mu’ expects UTF-8 (so, e.g.  /まりもえ お(1) becomes
/&MH4wijCCMEgwSg-).

   This is best solved by telling ‘offlineimap’ to use UTF-8 instead --
see this ticket
(https://github.com/djcb/mu/issues/68#issuecomment-8598652).

C.2.8 ‘mbsync’ or ‘offlineimap’ do not sync properly
----------------------------------------------------

Unfortunately, ‘mbsync’ and/or ‘offlineimap’ do not always agree with 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 _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 mu4e-index-lazy-check is kept at
its default (nil) value, since it seems ‘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.

   ---------- Footnotes ----------

   (1) some Japanese characters

C.3 Reading messages
====================

C.3.1 Opening messages is slower than expected - why?
-----------------------------------------------------

mu4e is designed to be very fast, even with large amounts of mail.
However, if you experience slowdowns, here are some things to consider:
   • opening messages while indexing: mu4e communicates with the 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 mu enough that users may
     notice.

     For some strategies to reduce that time, see the next question.
   • getting contact information can take some time: especially when
     opening mu4e the first time and you have a _lot_ of contacts, it
     can take a few seconds to process those.  Note that mu4e 1.3 and
     higher only get _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
     MU4E-COMPOSE-COMPLETE-ONLY-PERSONAL,
     MU4E-COMPOSE-COMPLETE-ONLY-AFTER and MU4E-COMPOSE-COMPLETE-MAX.
   • 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.

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

   • are all messages slow or only some messages?
   • if it's only some messages, is there something specific about them?
   • in addition, please a (sufficiently censored version of) a message
     that is slow
   • is opening _always_ slow or only sometimes?  When?

C.3.2 How can I word-wrap long lines in when viewing a message?
---------------------------------------------------------------

You can toggle between wrapped and non-wrapped states using <w>.  If you
want to do this automatically, invoke ‘visual-line-mode’ in your
‘mu4e-view-rendered-hook’ (‘mu4e-view-mode-hook’ fires too early).

C.3.3 How can I perform custom actions on messages and attachments?
-------------------------------------------------------------------

See Actions.

C.3.4 How can I prevent mu4e from automatically marking messages as 'read' when I read them?
--------------------------------------------------------------------------------------------

Set ‘mu4e-view-auto-mark-as-read’ to ‘nil’.

C.3.5 Does mu4e support including all related messages in a thread, like Gmail does?
------------------------------------------------------------------------------------

Yes -- see Including related messages.

C.3.6 There seems to be a lot of duplicate messages -- how can I get rid of them?
---------------------------------------------------------------------------------

See Skipping duplicates.

C.3.7 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 _action_ (see
Message view actions) defined for this.  Simply add to your
configuration:
     (add-to-list 'mu4e-view-actions
       '("ViewInBrowser" . mu4e-action-view-in-browser) t)
   Now, when viewing such a difficult message, type ‘aV’, and the
message opens inside a web browser.  You can influence the browser to
use with ‘browse-url-generic-program’.

C.3.8 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 kpachnis):
     (require 'epg-config)
     (setq mml2015-use 'epg
           epg-user-id "gpg_key_id"
           mml2015-encrypt-to-self t
           mml2015-sign-with-sender t)

C.4 Writing messages
====================

C.4.1 How can I automatically set the From:-address for a reply-message?
------------------------------------------------------------------------

See Compose hooks.

C.4.2 How can I dynamically determine the folders for draft/sent/trashed messages?
----------------------------------------------------------------------------------

See Dynamic folders.

C.4.3 How can I define aliases for (groups of) e-mail addresses?
----------------------------------------------------------------

See Mail Aliases (emacs).

C.4.4 How can I automatically add some header to an outgoing message?
---------------------------------------------------------------------

See Compose hooks.

C.4.5 How can I influence the way the original message looks when replying/forwarding?
--------------------------------------------------------------------------------------

Since ‘mu4e-compose-mode’ derives from message, you can
re-use many (though not _all_ of its facilities.

C.4.6 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 From: Foo, the great Bar <foo@bar.com>
instead of From: "Foo, the great Bar" <foo@bar.com>.

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

C.4.7 How can I easily include attachments in the messages I write?
-------------------------------------------------------------------

You can drag-and-drop from your desktop; alternatively, you can use
Dired (emacs).

C.4.8 How can I start a new message-thread from a reply?
--------------------------------------------------------

Remove the In-Reply-To header, and mu4e automatically removes the
(hidden) References header as well when sending it.  This makes the
message show up as a top-level message rather than as a response.

C.4.9 How can I attach an existing message?
-------------------------------------------

Use ‘mu4e-action-capture-message’ (i.e., ‘a c’ in the headers view) to
'capture' the to-be-attached message, then when editing the message, use
‘M-x mu4e-compose-attach-captured-message’.

C.4.10 How can I sign or encrypt messages?
------------------------------------------

You can do so using Emacs' MIME-support -- check the Attachments-menu
while composing a message.  Also see Signing and encrypting.

C.4.11 Address auto-completion misses some addresses
----------------------------------------------------

If you have set ‘mu4e-compose-complete-only-personal’ to non-nil, mu4e
only completes 'personal' addresses - so you tell it about your e-mail
addresses when setting up the database (mu init); see Initializing the message store.

   If you cannot find specific addresses you'd expect to find, inspect
the values of MU4E-COMPOSE-COMPLETE-ONLY-PERSONAL,
MU4E-COMPOSE-COMPLETE-ONLY-AFTER and MU4E-COMPOSE-COMPLETE-MAX.

C.4.12 How can I get rid of the message buffer after sending?
-------------------------------------------------------------

     (setq message-kill-buffer-on-exit t)

C.4.13 Sending big messages is slow and blocks Emacs
----------------------------------------------------

And what can I do about it?

   For this, there's emacs-async
(https://github.com/jwiegley/emacs-async) (also available from the Emacs
package repository); add the following snippet to your configuration:
     (require 'smtpmail-async)
     (setq
       send-mail-function 'async-smtpmail-send-it
       message-send-mail-function 'async-smtpmail-send-it)
   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
*Messages*-buffer, which should show something like:
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
   The first and final messages are the most important, and there may be
considerable time between them, depending on the size of the message.

C.4.14 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 compose-mail-other-frame (‘C-x 5
m’) and compose-mail-other-window (‘C-x 4 m’) if you have set up mu4e as
your Emacs e-mailer.

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

C.4.15 How can I apply format=flowed to my outgoing messages?
-------------------------------------------------------------

Plain text emails with 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: <https://mathiasbynens.be/notes/gmail-plain-text> (if
you don't have it, your mails mostly look quite bad especially on mobile
devices) and here's the RFC with all the details
(https://www.ietf.org/rfc/rfc2646.txt).

   Since version 0.9.17, mu4e sends emails with format=flowed by setting
     (setq mu4e-compose-format-flowed t)

in your Emacs init file (‘~/.emacs’ or ‘~/.emacs.d/init.el’).  The
transformation of your message into the proper format is done at the
time of sending.  For this to happen properly, you should write each
paragraph of your message of as a long line (i.e.  without carriage
return).  If you introduce unwanted newlines in your paragraph, use
‘M-q’ to reformat it as a single line.

   If you want to send the message with paragraphs on single lines but
without format=flowed (because, say, the receiver does not understand
the latter as it is the case for Google or Github), use ‘M-x
use-hard-newlines’ (to turn ‘use-hard-newlines’ off) or uncheck the box
format=flowed in the Text menu when composing a message.

C.4.16 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:
     (setq  message-citation-line-format "On %Y-%m-%d at %R %Z, %f wrote...")

C.5 Known issues
================

Although they are not really _questions_, we end this chapter with a
list of known issues and/or missing features in 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.

C.5.1 UTF-8 language environment is required
--------------------------------------------

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
‘(set-language-environment "UTF-8")’ in your ‘~/.emacs’ (or its moral
equivalents in other places).

C.5.2 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:
     (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)))

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

Appendix D Tips and Tricks
**************************

D.1 Fancy characters
====================

When using 'fancy characters' (‘mu4e-use-fancy-chars’) with the
_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 .emacs-file):
     (when (equal window-system 'x)
           (set-fontset-font "fontset-default" 'unicode "Dejavu Sans Mono")
           (set-face-font 'default "Inconsolata-10"))

   Other fonts with good support for Unicode are unifont and symbola.

   For a more complete solution, but with greater overhead, you can also
try the _unicode-fonts_ package:
     (require 'unicode-fonts)
     (require 'persistent-soft) ; To cache the fonts and reduce load time
     (unicode-fonts-setup)

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

      (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" . "📅"))

D.2 Refiling messages
=====================

By setting ‘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 ‘my-mu4e-subject-alist’ containing regexes plus associated
mail folders:

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

   Now you can use the following function to automatically refile
messages based on their subject line:

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

   Note the "/General" folder: it is the default folder in case the
subject does not match any of the regexes in ‘my-mu4e-subject-alist’.

   In order to make this work, you'll of course need to set
‘mu4e-refile-folder’ to this function:

     (setq mu4e-refile-folder 'my-mu4e-refile-folder-function)

   If you have multiple accounts, you can accommodate them as well:

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

   This function actually uses different methods to determine the refile
folder, depending on the account: for _Account2_, it uses
‘my-mu4e-subject-alist’, for the _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:

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

D.3 Saving outgoing messages
============================

Like ‘mu4e-refile-folder’, the variable ‘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 ‘my-mu4e-mailing-lists’
as mentioned, you can use the following function to determine a
'sent'-folder:

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

   Note that this function doesn't use ‘(mu4e-message-field msg
:maildir)’ to determine which account the message is being sent from.
The reason is that the function in ‘mu4e-sent-folder’ is called when you
send the message, but before mu4e has created the message struct from
the compose buffer, so that ‘mu4e-message-field’ cannot be used.
Instead, the function uses ‘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 (my.address@account1.example.com) it uses
‘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 /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 ‘mu4e-ask-maildir-check-exists’ to ask the
user for a maildir to save the message in.

D.4 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.

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

   If you _always_ want to be asked for for confirmation, set
‘message-confirm-send’ to non-nil so the question "Send message?"  is
asked for confirmation.

Appendix E How it works
***********************

While perhaps not interesting for all users of mu4e, some curious souls
may want to know how mu4e does its job.

E.1 High-level overview
=======================

At a high level, we can summarize the structure of the mu4e system using
some ascii-art:

                   +---------+
                   | emacs   |
                   |    +------+
                   +----| mu4e | --> send mail (smtpmail)
                        +------+
                         |  A
                         V  |  ---/ search, view, move mail
                   +---------+    \
                   |   mu    |
                   +---------+
                     |    A
                     V    |
                   +---------+
                   | Maildir |  <--- receive mail (fetchmail,
                   +---------+                     offlineimap, ...)

   In words:
   • Your e-mail messages are stored in a Maildir-directory (typically,
     ‘~/Maildir’ and its subdirectories), and new mail comes in using
     tools like fetchmail, offlineimap, or through a local mail server.
   • mu indexes these messages periodically, so you can quickly search
     for them.  mu can run in a special server-mode, where it provides
     services to client software.
   • mu4e, which runs inside Emacs is such a client; it communicates
     with ‘mu’ (in its server-mode) to search for messages, and
     manipulate them.
   • mu4e uses the facilities offered by Emacs (the Gnus message editor
     and smtpmail) to send messages.

E.2 mu server
=============

mu4e is based on the 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 mu command-line tool
with some parameters and then parse the output.  In fact, that was the
first approach -- mu4e would invoke e.g., mu find and process the output
in Emacs.

   However, with this approach, we need to load the entire e-mail
_Xapian_ database (in which the message is stored) for each invocation.
Wouldn't it be nicer to keep a running mu instance around?  Indeed, it
would -- and thus, the mu server sub-command was born.  Running mu
server starts a simple shell, in which you can give commands to ‘mu’,
which then spits out the results/errors.  ‘mu server’ is not meant for
humans, but it can be used manually, which is great for debugging.

E.3 Reading from the server
===========================

In the design, the next question was what format mu should use for its
output for mu4e (Emacs) to process.  Some other programs use JSON here,
but it seemed easier (and possibly, more efficient) just to talk to
Emacs in its native language: _s-expressions_, and interpret those using
the Emacs-function ‘read-from-string’.  See The message s-expression
for details on the format.

   So, now let's look at how we process the data from mu server in
Emacs.  We'll leave out a lot of details, mu4e-specifics, and look at a
bit more generic approach.

   The first thing to do is to create a process (for example, with
‘start-process’), and then register a filter function for it, which is
invoked whenever the process has some data for us.  Something like:

       (let ((proc (start-process <arguments>)))
         (set-process-filter proc 'my-process-filter)
         (set-process-sentinel proc 'my-process-sentinel))

   Note, the process sentinel is invoked when the process is terminated
-- so there you can clean things up.  The function ‘my-process-filter’
is a user-defined function that takes the process and the chunk of
output as arguments; in mu4e it looks something like (pseudo-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>))

   ‘<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
mu-server man-page and more completely in the output of mu server
--commands.

   mu4e can log these communications; you can use ‘M-x
mu4e-toggle-logging’ to turn logging on and off, and you can view the
log using ‘M-x mu4e-show-log’ (<$>).

E.4 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:

     (: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)
      ....
     ")

   This s-expression forms a property list (plist), and we can get
values from it using plist-get; for example ‘(plist-get msg :subject)’
would get you the message subject.  However, it's better to use the
function ‘mu4e-message-field’ to shield you from some of the
implementation details that are subject to change; and see the other
convenience functions in ‘mu4e-message.el’.

   Some notes on the format:
   • The address fields are _lists_ of plists of the form ‘(:name <name>
     :email <email>)’, where name can be nil.
   • The date is in format Emacs uses (for example in
     ‘current-time’).(1)

E.4.1 Example: ping-pong
------------------------

As an example of the communication between mu4e and ‘mu’, let's look at
the ping-pong-sequence.  When mu4e starts, it sends a command ping to
the mu server backend, to learn about its version.  mu server then
responds with a pong s-expression to provide this information (this is
implemented in ‘mu-cmd-server.c’).

   We start this sequence when mu4e is invoked (when the program is
started).  It calls mu4e--server-ping, and registers a (lambda) function
for mu4e-server-pong-func, to handle the response.

-> (ping)
<-<prefix>(:pong "mu" :props (:version "x.x.x" :doccount 78545))

   When we receive such a pong (in ‘mu4e-server.el’), the lambda
function we registered is called, and it compares the version we got
from the pong with the version we expected, and raises an error if they
differ.

   ---------- Footnotes ----------

   (1) 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 time_t in two numbers.

Appendix F Debugging
********************

As explained in How it works, mu4e communicates with its backend
(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, mu4e can log all these messages.  Note that the 'protocol'
is documented to some extent in the mu-server manpage.

   You can enable (and disable) logging with ‘M-x mu4e-toggle-logging’.
The log-buffer is called *mu4e-log*, and in the Main view,
Headers view and Message view, there's a keybinding <$> that
takes you there.  You can quit it by pressing <q>.

   Logging can be a bit resource-intensive, so you may not want to leave
it on all the time.

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

Appendix G GNU Free Documentation License
*****************************************

                      Version 1.2, November 2002

     Copyright © 2000,2001,2002 Free Software Foundation, Inc.
     51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document “free” in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.  We
     recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it can
     be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     "Document", below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as "you".  You accept
     the license if you copy, modify or distribute the work in a way
     requiring permission under copyright law.

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in the
     notice that says that the Document is released under this License.
     If a section does not fit the above definition of Secondary then it
     is not allowed to be designated as Invariant.  The Document may
     contain zero Invariant Sections.  If the Document does not identify
     any Invariant Sections then there are none.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images composed
     of pixels) generic paint programs or (for drawings) some widely
     available drawing editor, and that is suitable for input to text
     formatters or for automatic translation to a variety of formats
     suitable for input to text formatters.  A copy made in an otherwise
     Transparent file format whose markup, or absence of markup, has
     been arranged to thwart or discourage subsequent modification by
     readers is not Transparent.  An image format is not Transparent if
     used for any substantial amount of text.  A copy that is not
     "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and standard-conforming
     simple HTML, PostScript or PDF designed for human modification.
     Examples of transparent image formats include PNG, XCF and JPG.
     Opaque formats include proprietary formats that can be read and
     edited only by proprietary word processors, SGML or XML for which
     the DTD and/or processing tools are not generally available, and
     the machine-generated HTML, PostScript or PDF produced by some word
     processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow the
     conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the title
     equally prominent and visible.  You may add other material on the
     covers in addition.  Copying with changes limited to the covers, as
     long as they preserve the title of the Document and satisfy these
     conditions, can be treated as verbatim copying in other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a machine-readable
     Transparent copy along with each Opaque copy, or state in or with
     each Opaque copy a computer-network location from which the general
     network-using public has access to download using public-standard
     network protocols a complete Transparent copy of the Document, free
     of added material.  If you use the latter option, you must take
     reasonably prudent steps, when you begin distribution of Opaque
     copies in quantity, to ensure that this Transparent copy will
     remain thus accessible at the stated location until at least one
     year after the last time you distribute an Opaque copy (directly or
     through your agents or retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of copies,
     to give them a chance to provide you with an updated version of the
     Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with the
     Modified Version filling the role of the Document, thus licensing
     distribution and modification of the Modified Version to whoever
     possesses a copy of it.  In addition, you must do these things in
     the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of previous
          versions (which should, if there were any, be listed in the
          History section of the Document).  You may use the same title
          as a previous version if the original publisher of that
          version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on the
          Title Page.  If there is no section Entitled "History" in the
          Document, create one stating the title, year, authors, and
          publisher of the Document as given on its Title Page, then add
          an item describing the Modified Version as stated in the
          previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in the
          "History" section.  You may omit a network location for a work
          that was published at least four years before the Document
          itself, or if the original publisher of the version it refers
          to gives permission.

       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the section
          all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document, unaltered
          in their text and in their titles.  Section numbers or the
          equivalent are not considered part of the section titles.

       M. Delete any section Entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option designate
     some or all of these sections as invariant.  To do this, add their
     titles to the list of Invariant Sections in the Modified Version's
     license notice.  These titles must be distinct from any other
     section titles.

     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end of
     the list of Cover Texts in the Modified Version.  Only one passage
     of Front-Cover Text and one of Back-Cover Text may be added by (or
     through arrangements made by) any one entity.  If the Document
     already includes a cover text for the same cover, previously added
     by you or by arrangement made by the same entity you are acting on
     behalf of, you may not add another; but you may replace the old
     one, on explicit permission from the previous publisher that added
     the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination all
     of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications".  You
     must delete all sections Entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the documents
     in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow this
     License in all other respects regarding verbatim copying of that
     document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of a
     storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses terminated
     so long as such parties remain in full compliance.

  10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     <http://www.gnu.org/copyleft/>.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If the
     Document does not specify a version number of this License, you may
     choose any version ever published (not as a draft) by the Free
     Software Foundation.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.2
       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''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts."  line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.