mu/mu4e/mu4e.texi

@documentencoding UTF-8
\input texinfo.tex    @c -*-texinfo-*-
@include texi.texi
@c %**start of header
@setfilename mu4e.info
@settitle mu4e @value{mu-version} user manual

@c Use proper quote and backtick for code sections in PDF output
@c Cf. Texinfo manual 14.2
@set txicodequoteundirected
@set txicodequotebacktick
@c %**end of header

@copying
Copyright @copyright{} 2012-2015 Dirk-Jan C. Binnema

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end quotation
@end copying

@titlepage
@title @t{mu4e} - an e-mail client for Emacs
@subtitle version  @value{mu-version}
@author Dirk-Jan C. Binnema

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@dircategory Emacs
@direntry
* mu4e: (mu4e).        An email client for Emacs.
@end direntry

@contents

@ifnottex
@node Top
@top mu4e manual
@end ifnottex

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

Welcome to @t{mu4e} @value{mu-version}!

@t{mu4e} (@t{mu}-for-emacs) is an e-mail client for GNU-Emacs version 24
(version 23 may works as well, but is not tested as much), built on top
of the @t{mu}@footnote{@url{http://www.djcbsoftware.nl/code/mu}} e-mail
search engine. @t{mu4e} is optimized for fast handling of large amounts
of e-mail.

Some of @t{mu4e}'s highlights:

@itemize
@item Fully search-based: there are no folders@footnote{that is, instead of
folders, you use queries that match messages in a particular folder}, only
queries.
@item Fully documented, with example configurations
@item User-interface optimized for speed, with quick key strokes for common actions
@item Support for non-English languages (so ``angstrom'' will match ``Angström'')
@item Asynchronous: heavy actions don't block @command{emacs}@footnote{currently,
the only exception to this is @emph{sending mail}; there are solutions for
that though - see the @ref{FAQ}}
@item Support for crypto
@item Address auto-completion based on the contacts in your messages
@item Extendable with your own snippets of elisp
@end itemize

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

At the end of the manual, there are some example configurations, to get you up
to speed quickly: @ref{Example configurations}. There's also an @ref{FAQ},
which should help you with some common questions.

@menu
* Introduction:: How it all began
* Getting started:: Setting things up
* Main view:: Where we go when starting @t{mu4e}
* Headers view:: Lists of message headers
* Message view:: Viewing specific messages
* Editor view:: Creating / editing messages
* Searching:: Some more background on searching/queries
* Marking:: Marking messages and performing actions
* Dynamic folders:: Folders that depend on the context
* Actions:: Defining and using custom actions
* Extending mu4e:: Writing code for @t{mu4e}

Appendices
* Interaction with other tools:: mu4e and the rest of the world
* Example configurations:: Some examples to set you up quickly
* FAQ:: Common questions and answers
* Tips and Tricks:: Useful tips
* How it works:: Some notes about the implementation of @t{mu4e}
* Logging and debugging:: How to debug problems in @t{mu4e}
* GNU Free Documentation License::  The license of this manual
@end menu

@node Introduction
@chapter Introduction

@menu
* Why another e-mail client::
* Other mail clients::
* What mu4e does not do::
* Becoming a mu4e user::
@end menu

@node Why another e-mail client
@section Why another e-mail client?

Fair question.

I'm not sure the world needs yet another e-mail client, but perhaps
@emph{I} do!

I (the author) spend a @emph{lot} of time dealing with e-mail, both
professionally and privately. Having an efficient e-mail client is
essential.  Since none of the existing ones worked the way I wanted, I
created my own. @command{emacs} is an integral part of my workflow, so
it made a lot of sense to use it for e-mail as well. And as I already
had written an e-mail search engine (@t{mu}), it seemed only logical to
use that as a basis.

@node Other mail clients
@section Other mail clients

Under the hood, @t{mu4e} is fully search-based, similar to programs like
@t{notmuch}@footnote{@url{http://notmuchmail.org}},
@t{md}@footnote{@url{https://github.com/nicferrier/md} (inactive)} and
@t{sup}@footnote{@url{http://sup.rubyforge.org/}
(unreachable)}. However, @t{mu4e}'s user-interface is quite
different. @t{mu4e}'s mail handling (deleting, moving etc.) is inspired
by @emph{Wanderlust}@footnote{@url{http://www.gohome.org/wl/}} (another
@code{emacs}-based e-mail client),
@t{mutt}@footnote{@url{http://www.mutt.org/}} and @t{dired}.

@t{mu4e} tries to keep all the 'state' in your maildirs, so you can easily
switch between clients, synchronize over @abbr{IMAP}, backup with @t{rsync}
and so on. If you delete the database, you won't lose any information.

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

There are a number of things that @t{mu4e} does @emph{not} do:
@itemize
@item @t{mu}/@t{mu4e} do @emph{not} get your e-mail messages from
a mail server. That task is delegated to other tools, such as
@t{offlineimap}@footnote{@url{http://offlineimap.org/}},
@t{isync/mbsync}@footnote{@url{http://isync.sourceforge.net/}} or
@t{fetchmail}@footnote{@url{http://www.fetchmail.info/}}. As long as the
messages end up in a maildir, @t{mu4e} and @t{mu} are happy to deal with
them.
@item @t{mu4e} also does @emph{not} implement sending of messages; instead, it
depends on @t{smptmail} (@inforef{Top,,smtpmail}), which is part of
@command{emacs}. In addition, @t{mu4e} piggybacks on Gnus' message editor;
@inforef{Top,,message}.
@end itemize

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

@node Becoming a mu4e user
@section Becoming a @t{mu4e} user

If @t{mu4e} looks like something for you, give it a shot! We've been
trying hard to make it as easy as possible to set up and use; and while
you can use elisp in various places to augment @t{mu4e}, a lot of
knowledge about programming or elisp shouldn't be required. The idea is
to provide sensible defaults, and allow for customization.

When you take @t{mu4e} into use, it's a good idea to subscribe to the
@t{mu}/@t{mu4e}-mailing
list@footnote{@url{http://groups.google.com/group/mu-discuss}}.

If you have suggestions for improvements or bug reports, please use the
GitHub issues list@footnote{@url{https://github.com/djcb/mu/issues}}. In
bug reports, please clearly specify the versions of @t{mu}/@t{mu4e} and
@command{emacs} you are using, as well as any other relevant
details. Also, if it is about the behavior for specific messages, please
attach the raw message (that is, the message file as it exists in your
maildir); you can of course strip off any personal information.

If you are new to all this, the somewhat paternalistic @emph{``How to ask
questions the smart
way''}@footnote{@url{http://www.catb.org/esr/faqs/smart-questions.html}} may
be a good read.

@node Getting started
@chapter Getting started

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

After these steps, @t{mu4e} should be ready to go!

@menu
* Requirements:: What is needed
* Installation:: How to install @t{mu} and @t{mu4e}
* Getting mail:: Getting mail from a server
* Indexing your messages:: Creating and maintaining the index
* Basic configuration:: Settings for @t{mu4e}
* Folders::  Setting up standard folders
* Retrieval and indexing:: Doing it from mu4e
* Sending mail:: How to send mail
* Running mu4e:: Overview of the @t{mu4e} views

@end menu

@node Requirements
@section Requirements

@t{mu}/@t{mu4e} are known to work on a wide variety of Unix- and Unix-like
systems, including many Linux distributions, MacOS and
FreeBSD. @command{emacs} 23 or 24 (recommended) is required, as well as
Xapian@footnote{@url{http://xapian.org/}} and
GMime@footnote{@url{http://spruce.sourceforge.net/gmime/}}.

@t{mu} has optional support for the Guile 2.x (Scheme) programming
language. There are also some GUI-tools, which require GTK+ 3.x and
Webkit.

If you intend to compile @t{mu} yourself, you need to have the typical
development tools, such as C and C++ compilers (both @command{gcc} and
@command{clang} should work), GNU Autotools and @command{make}, and the
development packages for GMime, GLib and Xapian. Optionally (if you use them),
you also need the development packages for GTK+, Webkit and Guile.

@node Installation
@section Installation

@t{mu4e} is part of @t{mu} - by installing the latter, the former is installed
as well. Some Linux distributions provide packaged versions of
@t{mu}/@t{mu4e}; if you can use those, there is no need to compile anything
yourself. However, if there are no packages for your distribution, if they are
outdated, or if you want to use the latest development versions, you can
follow the steps below.

First, you need make sure you have the necessary dependencies; the details
depend on your distribution. If you're using another distribution (or another
OS), the below at least be helpful in identifying the packages to install.

We provide some instructions for Debian, Ubuntu and Fedora; if those do not
apply to you, you can follow either @ref{Building from a release tarball} or
@ref{Building from git}.

@subsection Dependencies for Debian/Ubuntu

@example
$ sudo apt-get install libgmime-2.6-dev libxapian-dev
# if libgmime-2.6-dev is not available, try libgmime-2.4-dev

# get emacs 23 or 24 if you don't have it yet
$ sudo apt-get install emacs24

# optional
$ sudo apt-get install guile-2.0-dev html2text xdg-utils

# optional: only needed for msg2pdf and mug (toy gtk+ frontend)
$ sudo apt-get install libwebkit-dev
@end example

@subsection Dependencies for Fedora

@example
$ sudo yum install gmime-devel xapian-core-devel

# get emacs 23 or 24 if you don't have it yet
$ sudo yum install emacs

# optional
$ sudo yum install html2text xdg-utils

# optional: only needed for msg2pdf and mug (toy gtk+ frontend)
$ sudo yum install webkitgtk3-devel
@end example

@subsection Building from a release tarball
@anchor{Building from a release tarball}

Using a release-tarball (as available from
GoogleCode@footnote{@url{http://code.google.com/p/mu0/downloads/list}},
installation follows the typical steps:

@example
$ tar xvfz mu-<version>.tar.gz  # use the specific version
$ cd mu-<version>
# On the BSDs: use gmake instead of make
$ ./configure && make
$ sudo make install
@end example

Xapian, GMime and their dependencies must be installed.

@subsection Building from git
@anchor{Building from git}

Alternatively, if you build from the git repository or use a tarball like the
ones that @t{github} produces, the instructions are slightly different, and
require you to have @t{autotools} (Autoconf, Automake, Libtool, and friends)
installed:

@example
# get from git (alternatively, use a github tarball)
$ git clone git://github.com/djcb/mu.git

$ cd mu
$ autoreconf -i && ./configure && make
# On the BSDs: use gmake instead of make
$ sudo make install
@end example

(Xapian, GMime and their dependencies must be installed).

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

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

@subsection mu4e and emacs customization

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

@node Getting mail
@section Getting mail

In order for @t{mu} (and, by extension, @t{mu4e}) to work, you need to have
your e-mail messages stored in a
@emph{maildir}@footnote{@url{http://en.wikipedia.org/wiki/Maildir}; in this
manual we use the term 'maildir' for both the standard and the hierarchy of
maildirs that store your messages} - a specific directory structure with
one-file-per-message. If you are already using a maildir, you are lucky. If
not, some setup is required:

@itemize
@item @emph{Using an external IMAP or POP server} - if you are using an
@abbr{IMAP} or @abbr{POP} server, you can use tools like @t{getmail},
@t{fetchmail}, @t{offlineimap} or @t{isync} to download your messages into a
maildir (@file{~/Maildir}, often). Because it is such a common case, there is
a full example of setting @t{mu4e} up with @t{offlineimap} and Gmail;
@pxref{Gmail configuration}.
@item @emph{Using a local mail server} - if you are using a local mail-server
(such as @t{postfix} or @t{qmail}), you can teach them to deliver into a
maildir as well, maybe in combination with @t{procmail}. A bit of googling
should be able to provide you with the details.
@end itemize

@node Indexing your messages
@section Indexing your messages

After you have succeeded in @ref{Getting mail}, we need to @emph{index} the
messages. That is - we need to scan the messages in the maildir and store the
information about them in a special database. We can do that from @t{mu4e} --
@ref{Main view}, but the first time, it is a good idea to run it from the
command line, which makes it easier to verify that everything works correctly.

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

This should scan your @file{~/Maildir}@footnote{In most cases, you do not even
need to provide the @t{--maildir=~/Maildir} since it is the default; see the
@t{mu-index} man-page for details} and fill the database, and give progress
information while doing so.

The indexing process may take a few minutes the first time you do it
(for thousands of e-mails); afterwards it is much faster, since @t{mu}
only scans messages that are new or have changed. Indexing is discussed
in full detail in the @t{mu-index} man-page.

After the indexing process has finished, you can quickly test if everything
worked, by trying some command-line searches, for example
@example
  $ mu find hello
@end example

which lists all messages that match @t{hello}. For more examples of searches,
see @ref{Queries}, or check the @t{mu-find} and @t{mu-easy} man pages. If all
of this worked well, we are well on our way setting things up; the next step
is to do some basic configuration for @t{mu4e}.

@node Basic configuration
@section Basic configuration

Before we can start using @t{mu4e}, we need to tell @command{emacs} to load
it. So, add to your @file{~/.emacs} (or its moral equivalent, such as
@file{~/.emacs.d/init.el}) something like:

@lisp
(require 'mu4e)
@end lisp

If @command{emacs} complains that it cannot find @t{mu4e}, check your
@code{load-path} and make sure that @t{mu4e}'s installation directory is part
of it. If not, you can add it:

@lisp
(add-to-list 'load-path MU4E-PATH)
@end lisp

with @t{MU4E-PATH} replaced with the actual path.

@node Folders
@section Folders

The next step is to tell @t{mu4e} where it can find your Maildir, and
some special folders. So, for example@footnote{Note that the folders
(@t{mu4e-sent-folder}, @t{mu4e-drafts-folder}, @t{mu4e-trash-folder} and
@t{mu4e-refile-folder}) can also be @emph{functions} that are evaluated
at runtime. This allows for dynamically changing them depending on the
context. See @ref{Dynamic folders} for details.}:
@lisp
  ;; these are actually the defaults
  (setq
    mu4e-maildir       "~/Maildir"   ;; top-level Maildir
    mu4e-sent-folder   "/sent"       ;; folder for sent messages
    mu4e-drafts-folder "/drafts"     ;; unfinished messages
    mu4e-trash-folder  "/trash"      ;; trashed messages
    mu4e-refile-folder "/archive")   ;; saved messages
@end lisp

Note, @code{mu4e-maildir} takes an actual filesystem-path, the other
folder names are all relative to @code{mu4e-maildir}. Also note that
this must @emph{not} be a symbolic link.

@node Retrieval and indexing
@section Retrieval and indexing with mu4e

As we have seen, we can do all of the mail retrieval @emph{outside} of
@command{emacs}/@t{mu4e}. However, you can also do it from within
@t{mu4e}. 

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

You can interrupt the (foreground) update process with @kbd{q}.

It is possible to update your mail and index periodically in the
background, by setting the variable @code{mu4e-update-interval} to the
number of seconds between these updates. If set to @code{nil}, it won't
update at all. After you make changes to @code{mu4e-update-interval},
@t{mu4e} must be restarted before the changes take effect.

@subsection Handling errors during mail retrieval

If the mail-retrieval process returns with a non-zero exit code,
@t{mu4e} will show a warning (unless
@code{mu4e-index-update-error-warning} is set to @code{nil}), but then
try to index your maildirs anyway (unless
@code{mu4e-index-update-error-continue} is set to @code{nil}).

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

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

@subsection Implicit mail retrieval 

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

@subsection Example setup

A simple setup could look something like:

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

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

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

@node Sending mail
@section Sending mail

@t{mu4e} re-uses Gnu's @code{message-mode} (@inforef{Top,,message}) for
writing mail and inherits the setup for sending mail as well.

For sending mail using @abbr{SMTP}, @t{mu4e} uses @t{smtpmail}
(@inforef{Top,,smtpmail}). This package supports many different ways to send
mail; please refer to its documentation for the details.

Here, we only provide some simple examples - for more, see @ref{Example
configurations}.

A very minimal setup:

@lisp
;; tell message-mode how to send mail
(setq message-send-mail-function 'smtpmail-send-it)
;; if our mail server lives at smtp.example.org; if you have a local
;; mail-server, simply use 'localhost' here.
(setq smtpmail-smtp-server "smtp.example.org")
@end lisp

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

@subsection Dealing with sent messages

By default, @t{mu4e} puts a copy of messages you sent in the folder determined
by @code{mu4e-sent-folder}.  In some cases, this may not be what you want -
for example, when using Gmail-over-@abbr{IMAP}, this interferes with Gmail's
handling of the sent messages folder, and you may end up with duplicate
messages.

You can use the variable @code{mu4e-sent-messages-behavior} to customize what
happens with sent messages. The default is the symbol @code{sent} which, as
mentioned, causes the message to be copied to your sent-messages folder. Other
possible values are the symbols @code{trash} (the sent message is moved to the
trash-folder (@code{mu4e-trash-folder}), and @code{delete} to simply discard
the sent message altogether (so Gmail can deal with it).

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

For more complex needs, @code{mu4e-sent-messages-behavior} can also be
a a parameter-less function that returns one of the mentioned symbols;
see the built-in documentation for the variable.

@node Running mu4e
@section Running mu4e

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

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

@cartouche
@verbatim

            [C]     +--------+   [RFCE]
          --------> | editor | <--------
         /          +--------+          \
        /         [RFCE]^                \
       /                |                 \
    +-------+ [sjbB]+---------+  [RET] +---------+
    | main  | <---> | headers | <----> | message |
    +-------+  [q]  +---------+ [qbBjs]+---------+
                      [sjbB]                ^
                                        [.] | [q]
                                            V
                                          +-----+
                                          | raw |
                                          +-----+

    Default bindings
    ----------------
    R: Reply      s: search            .: raw view (toggle)
    F: Forward    j: jump-to-maildir   q: quit
    C: Compose    b: bookmark-search
    E: Edit       B: edit bookmark-search

@end verbatim
@end cartouche

@node Main view
@chapter The main view

After you have installed @t{mu4e} (@pxref{Getting started}), you can start it
with @kbd{M-x mu4e}. @t{mu4e} does some checks to ensure everything is set up
correctly, and then shows you the @t{mu4e} main view. Its major mode is
@code{mu4e-main-mode}.



@menu
* Overview: MV Overview.
* Basic actions::
* Bookmarks: MV Bookmarks.
* Miscellaneous::
@end menu

@node MV Overview
@section Overview

The main view looks something like the following:

@cartouche
@verbatim
    * mu4e - mu for emacs version x.x CG

      Basics

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

      Bookmarks

            * [bu] Unread messages
            * [bt] Today's messages
            * [bw] Last 7 days
            * [bp] Messages with images
      Misc

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

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

@end verbatim
@end cartouche

In the example above, you can see the letters ``@t{CG}'', which indicate:
@itemize
@item @t{C}: support for decryption of encrypted messages, and verifying
signatures. See @ref{MSGV Crypto} in the @ref{Message view} for details.
@item @t{G}: support for the Guile 2.0 programming language
@end itemize
Whether you see both, one or none of these letters depends on the way @t{mu}
is built.

Let's walk through the menu.

@node Basic actions
@section Basic actions

First, the @emph{Basics}:
@itemize
@item @t{[j]ump to some maildir}: after pressing @key{j} (``jump''),
@t{mu4e} asks you for a maildir to visit. These are the maildirs you set in
@ref{Basic configuration} and any of your own. If you choose @key{o}
(``other'') or @key{/}, you can choose from all maildirs under
@code{mu4e-maildir}. After choosing a maildir, the messages in that maildir
are listed, in the @ref{Headers view}.
@item @t{enter a [s]earch query}: after pressing @key{s}, @t{mu4e} asks
you for a search query, and after entering one, shows the results in the
@ref{Headers view}.
@item @t{[C]ompose a new message}: after pressing @key{C}, you are dropped in
the @ref{Editor view} to write a new message.
@end itemize

@node MV Bookmarks
@section Bookmarks

The next item in the Main view is @emph{Bookmarks}. Bookmarks are predefined
queries with a descriptive name and a shortcut - in the example above, we see
the default bookmarks. You can view the list of messages matching a certain
bookmark by pressing @key{b} followed by the bookmark's shortcut. If you'd
like to edit the bookmarked query first before invoking it, use @key{B}.

Bookmarks are stored in the variable @code{mu4e-bookmarks}; you can add your
own and/or replace the default ones; @xref{Bookmarks}.

@node Miscellaneous
@section Miscellaneous

Finally, there are some @emph{Misc} (miscellaneous) actions:
@itemize
@item @t{[U]pdate email & database} executes the shell-command in the variable
 @code{mu4e-get-mail-command}, and afterwards updates the @t{mu} database;
see @ref{Indexing your messages} and @ref{Getting mail} for details.
@item @t{toggle [m]ail sending mode (direct)} toggles between sending
mail directly, and queuing it first (for example, when you are offline), and
@t{[f]lush queued mail} flushes any queued mail. This item is visible only
if you have actually set up mail-queuing. @ref{Queuing mail}
@item @t{[A]bout mu4e} provides general information about the program
@item @t{[H]elp} shows help information for this view
@item Finally, @t{[q]uit mu4e} quits your @t{mu4e}-session
@end itemize

@node Headers view
@chapter The headers view

The headers view shows the results of a query. The header-line shows
the names of the fields. Below that, there is a line with those
fields, for each matching message, followed by a footer line. The
major-mode for the headers view is @code{mu4e-headers-mode}.

@menu
* Overview: HV Overview.
* Keybindings::
* Marking messages::
* Sort order and threading::
* HV Custom headers::
* HV Actions::
* Split view::
@end menu

@node HV Overview
@section Overview

An example headers view:
@cartouche
@verbatim
Date V       Flgs  From/To             List       Subject
06:32        Nu    To Edmund Dantès    GstDev       + Re: Gstreamer-V4L...
15:08        Nu    Abbé Busoni         GstDev         + Re: Gstreamer-V...
18:20        Nu    Pierre Morrel       GstDev           \ Re: Gstreamer...
2013-03-18   S     Jacopo              EmacsUsr   + emacs server on win...
2013-03-18   S     Mercédès            EmacsUsr     \ RE: emacs server ...
2013-03-18   S     Beachamp            EmacsUsr   + Re: Copying a whole...
22:07        Nu    Albert de Moncerf   EmacsUsr     \ Re: Copying a who...
2013-03-18   S     Gaspard Caderousse  GstDev     | Issue with GESSimpl...
2013-03-18   Ss    Baron Danglars      GuileUsr   | Guile-SDL 0.4.2 ava...
End of search results
@end verbatim
@end cartouche

Some notes to explain what you see in the example:

@itemize
@item The fields shown in the headers view can be influenced by customizing
the variable @code{mu4e-headers-fields}; see @code{mu4e-header-info} for the
list of built-in fields. Apart from the built-in fields, you can also create
custom fields using @code{mu4e-header-info-custom}; see @ref{HV Custom
headers} for details.
@item By default, the date is shown with the @t{:human-date} field, which
shows the @emph{time} for today's messages, and the @emph{date} for older
messages. If you want to distinguish between 'today' and 'older', you can use
the @t{:date} field instead.
@item You can customize the date and time formats with the variable
@code{mu4e-headers-date-format} and @code{mu4e-headers-time-format},
respectively. In the example, we use @code{:human-date}, which shows when the
time when the message was sent today, and the date otherwise.
@item By default, the subject is shown using the @t{:subject} field;
however, it is also possible to use @t{:thread-subject}, which shows
the subject of a thread only once, similar to the display of the
@t{mutt} e-mail client.
@item The header field used for sorting is indicated by ``@t{V}'' or
``@t{^}''@footnote{or you can use little graphical triangles; see
variable @code{mu4e-use-fancy-chars}}, corresponding to the sort order
(descending or ascending, respectively). You can influence this by a
mouse click, or @key{O}. Not all fields allow sorting.
@item Instead of showing the @t{From:} and @t{To:} fields separately, you
can use From/To (@t{:from-or-to} in @code{mu4e-headers-fields} as a more
compact way to convey the most important information: it shows @t{From:}
@emph{except} when the e-mail was sent by the user (i.e., you) - in that case
it shows @t{To:} (prefixed by @t{To}@footnote{You can customize this by
changing the variable @code{mu4e-headers-from-or-to-prefix} (a cons cell)}, as
in the example above). To determine whether a message was sent by you,
@t{mu4e} uses the variable @code{mu4e-user-mail-address-list}, a list of
your e-mail addresses.
@item The 'List' field shows the mailing-list a message is sent to;
@code{mu4e} tries to create a convenient shortcut for the mailing-list name;
the variables @code{mu4e-user-mailing-lists} and
@code{mu4e-mailing-list-patterns} can be used to add your own shortcuts.
@item The letters in the 'Flags' field correspond to the following: D=@emph{draft},
F=@emph{flagged} (i.e., 'starred'), N=@emph{new}, P=@emph{passed} (i.e.,
forwarded), R=@emph{replied}, S=@emph{seen}, T=@emph{trashed},
a=@emph{has-attachment}, x=@emph{encrypted}, s=@emph{signed},
u=@emph{unread}. The tooltip for this field also contains this information.
@item The subject field also indicates the discussion threads @footnote{using
Jamie Zawinski's mail threading algorithm,
@url{http://www.jwz.org/doc/threading.html}}.
@item The headers view is @emph{automatically updated} if any changes are
found during the indexing process, and if there is no current
user-interaction. If you do not want such automatic updates, set
@code{mu4e-headers-auto-update} to @code{nil}.
@item There is a hook-function @code{mu4e-headers-found-hook} available which
is invoked just after @t{mu4e} has completed showing the messages in the
headers-view.
@end itemize

@node Keybindings
@section Keybindings

Using the below key bindings, you can do various things with these messages;
these actions are also listed in the @t{Headers} menu in the @command{emacs}
menu bar.

@verbatim
key          description
===========================================================
n,p          view the next, previous message
],[          move to the next, previous unread message
y            select the message view (if it's visible)
RET          open the message at point in the message view

searching
---------
s            search
S            edit last query
/            narrow the search
b            search bookmark
B            edit bookmark before search
j            jump to maildir
M-left,\     previous query
M-right      next query

O            change sort order
P            toggle threading
Q            toggle full-search
V            toggle skip-duplicates
W            toggle include-related

marking
-------
d            mark for moving to the trash folder
=            mark for removing trash flag ('untrash')
DEL,D        mark for complete deletion
m            mark for moving to another maildir folder
r            mark for refiling
+,-          mark for flagging/unflagging
?,!          mark message as unread, read

u            unmark message at point
U            unmark *all* messages

%            mark based on a regular expression
T,t          mark whole thread, subthread

<insert>,*   mark for 'something' (decide later)
#            resolve deferred 'something' marks

x            execute actions for the marked messages

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


misc
----
a            execute some custom action on a header
|            pipe message through shell command
C-+,C--      increase / decrease the number of headers shown
H            get help
C-S-u        update mail & reindex
q,z          leave the headers buffer
@end verbatim


@node Marking messages
@section Marking messages

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

The mark/unmark commands support the @emph{region} (i.e., ``selection'') --
so, for example, if you select some messages and press @key{DEL}, all messages
in the region are marked for deletion.

You can mark all messages that match a certain pattern with @key{%}. In
addition, you can mark all messages in the current thread (@key{T}) or
sub-thread (@key{t}).

When you do a new search or refresh the headers buffer while you still have
marked messages, you are asked what to do with those marks -- whether to
@emph{apply} them before leaving, or @emph{ignore} them. This behavior can be
influenced with the variable @code{mu4e-headers-leave-behavior}.

For more information about marking, see @ref{Marking}.

@node Sort order and threading
@section Sort order and threading

By default, @t{mu4e} sorts messages by date, in descending order: the most
recent messages are shown at the top. In addition, the messages are
@emph{threaded}, i.e., shown in the context of a discussion thread; this also
affects the sort order.

The header field used for sorting is indicated by ``@t{V}'' or
``@t{^}''@footnote{or you can use little graphical triangles; see variable
@code{mu4e-use-fancy-chars}}, indicating the sort order (descending or
ascending, respectively).

You can change the sort order by clicking the corresponding field with the
mouse, or with @kbd{M-x mu4e-headers-change-sorting} (@key{O}); note that not
all fields can be used for sorting. You can toggle threading on/off using
@kbd{M-x mu4e-headers-toggle-threading} or @key{P}. For both of these functions,
unless you provide a prefix argument (@key{C-u}), the current search is
updated immediately using the new parameters. You can toggle full-search
(@ref{Searching}) using @kbd{M-x mu4e-headers-toggle-full-search} or @key{Q}.

If you want to change the defaults for these settings, you can use the
variables @code{mu4e-headers-sortfield} and @code{mu4e-headers-show-threads}.

@node HV Custom headers
@section Custom headers

Sometimes the normal headers that @t{mu4e} offers (Date, From, To, Subject
etc.) may not be enough. For these cases, @t{mu4e} offers @emph{custom
headers} in both the headers-view and the message-view.

You can do so by adding a description of your custom header to
@code{mu4e-header-info-custom}, which is a list of custom headers.

Let's look at an example -- suppose we want to add a custom header that shows
the number of recipients for a message, i.e., the sum of the number of
recipients in the To: and Cc: fields. Let's further suppose that our function
takes a message-plist as its argument (@ref{Message functions}).

@lisp
(add-to-list 'mu4e-header-info-custom
  '(:recipnum .
    ( :name "Number of recipients"  ;; long name, as seen in the message-view
      :shortname "Recip#"           ;; short name, as seen in the headers view
      :help "Number of recipients for this message" ;; tooltip
      :function
      (lambda (msg)
	(format "%d"
	  (+ (length (mu4e-message-field msg :to))
	    (length (mu4e-message-field msg :cc))))))))
@end lisp

Or, let's get the full mailing-list name:
@lisp
(add-to-list 'mu4e-header-info-custom
  '(:full-mailing-list .
     ( :name "Mailing-list"               ;; long name, as seen in the message-view
       :shortname "ML"                    ;; short name, as seen in the headers view
       :help "Full name for mailing list" ;; tooltip
       :function
       (lambda (msg)
	 (or (mu4e-message-field msg :mailing-list) "")))))
@end lisp

You can then add the custom header to your @code{mu4e-headers-fields},
just like the built-in headers. After evaluation, you headers-view
should include a new header @t{Recip#} with the number of recipients,
and/or @t{ML} with the full mailing-list name.

This function can be used in both the headers-view and the message-view;
if you need something specific for one of these, you can check for the
mode in your function, or create separate functions.

@node HV Actions
@section Actions

@code{mu4e-headers-action} (@key{a}) lets you pick custom actions to perform
on the message at point. You can specify these actions using the variable
@code{mu4e-headers-actions}. See @ref{Actions} for the details.

@t{mu4e} defines some default actions. One of those is for @emph{capturing} a
message: @key{a c} 'captures' the current message. Next, when you're editing
some message, you can include the previously captured message as an
attachment, using @code{mu4e-compose-attach-captured-message}. See
@file{mu4e-actions.el} in the @t{mu4e} source distribution for more example
actions.

@node Split view
@section Split view

Using the @emph{Split view}, we can see the @ref{Headers view} and the
@ref{Message view} next to each other, with the message selected in the
former, visible in the latter. You can influence the way the splitting is done
by customizing the variable @code{mu4e-split-view}. Possible values are:

@itemize
@item @t{horizontal} (this is the default): display the message view below the
header view. Use @code{mu4e-headers-visible-lines} the set the number of lines
shown (default: 8).
@item @t{vertical}: display the message view on the
right side of the header view. Use @code{mu4e-headers-visible-columns} to set
the number of visible columns (default: 30).
@item anything else: don't do any splitting
@end itemize

@noindent
Some useful key bindings in the split view:
@itemize
@item @key{C-+} and @key{C--}: interactively change the number of columns or
headers shown
@item You can change the selected window from the
headers-view to the message-view and vice-versa with
@code{mu4e-select-other-view}, bound to @key{y}
@end itemize

@node Message view
@chapter The message view

After selecting a message in the @ref{Headers view}, it appears in a message
view window, which shows the message headers, followed by the message
body. Its major mode is @code{mu4e-view-mode}.

@menu
* Overview: MSGV Overview.
* Keybindings: MSGV Keybindings.
* Opening and saving attachments::
* Viewing images inline::
* Displaying rich-text messages::
* Crypto: MSGV Crypto.
* Custom headers: MSGV Custom headers
* Actions: MSGV Actions.
@end menu

@node MSGV Overview
@section Overview

An example message view:

@cartouche
@verbatim
    From: randy@epiphyte.com
    To: julia@eruditorum.org
    Subject: Re: some pics
    Flags: (seen attach)
    Date: Mon 19 Jan 2004 09:39:42 AM EET
    Maildir: /inbox
    Attachments(2): [1]DSCN4961.JPG(1.3M), [2]DSCN4962.JPG(1.4M)

    Hi Julia,

    Some pics from our trip to Cerin Amroth. Enjoy!

    All the best,
    Randy.

    On Sun 21 Dec 2003 09:06:34 PM EET, Julia wrote:

    [....]
@end verbatim
@end cartouche

Some notes:
@itemize
@item The variable @code{mu4e-view-fields} determines the header fields to be
shown; see @code{mu4e-header-info} for a list of built-in fields. Apart from
the built-in fields, you can also create custom fields using
@code{mu4e-header-info-custom}; see @ref{MSGV Custom headers}.
@item You can set the date format with the variable
@code{mu4e-date-format-long}.
@item By default, only the names of contacts in address fields are visible
(see @code{mu4e-view-show-addresses} to change this). You can view the e-mail
addresses by clicking on the name, or pressing @key{M-RET}.
@item You can compose a message for the contact at point by either clicking
@key{[mouse-2]} or pressing @key{C}.
@item The body text can be line-wrapped using @t{visual-line-mode}. @t{mu4e}
defines @key{w} to toggle between the wrapped and unwrapped state. If you want
to do this automatically when viewing a message, invoke @code{visual-line-mode}
in your @code{mu4e-view-mode-hook}.
@item You can hide cited parts in messages (the parts starting with ``@t{>}'')
using @code{mu4e-view-hide-cited}, bound to @key{h}. If you want to do this
automatically for every message, invoke the function in your
@code{mu4e-view-mode-hook}.
@item For search-related operations, see @ref{Searching}.
@item You can scroll down the message using @key{SPC}; if you do this at the
end of a message,it automatically takes you to the next one. If you want to
prevent this behavior, set @code{mu4e-view-scroll-to-next} to @code{nil}.
@end itemize

@node MSGV Keybindings
@section Keybindings

You can find most things you can do with this message in the @emph{View} menu,
or by using the keyboard; the default bindings are:

@verbatim
key          description
==============================================================
n,p          view the next, previous message
],[          move to the next, previous unread message
y            select the headers view (if it's visible)

RET          scroll down
M-RET        open URL at point / attachment at point

SPC          scroll down, if at end, move to next message
S-SPC        scroll up

searching
---------
s            search
e            edit last query
/            narrow the search
b            search bookmark
B            edit bookmark before search
j            jump to maildir

M-left       previous query
M-right      next query

marking
-------
d            mark for moving to the trash folder
=            mark for removing trash flag ('untrash')
DEL,D        mark for complete deletion
m            mark for moving to another maildir folder
r            mark for refiling
+,-          mark for flagging/unflagging

u            unmark message at point
U            unmark *all* messages

%            mark based on a regular expression
T,t          mark whole thread, subthread

<insert>,*   mark for 'something' (decide later)
#            resolve deferred 'something' marks

x            execute actions for the marked messages

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

actions
-------
g            go to (visit) numbered URL (using `browse-url')
             (or: <mouse-1> or M-RET with point on url)
             C-u g visits multiple URLs
k            save the numbered URL in the kill-ring.
             C-u k saves multiple URLs

e            extract (save) attachment (asks for number)
             (or: <mouse-2> or S-RET with point on attachment)
             C-u e extracts multiple attachments
o            open attachment (asks for number)
             (or: <mouse-1> or M-RET with point on attachment)

a            execute some custom action on the message
A            execute some custom action on an attachment

misc
----
c            copy address at point (with C-u copy long version)
w            toggle line wrapping
h            toggle showing cited parts

v            show details about the cryptographic signature

.            show the raw message view. 'q' takes you back.
C-+,C--      increase / decrease the number of headers shown
H            get help
C-S-u        update mail & reindex
q,z          leave the message view
@end verbatim

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

@node Opening and saving attachments
@section Opening and saving attachments

By default, @t{mu4e} uses the @t{xdg-open}-program
@footnote{@url{http://portland.freedesktop.org/wiki/}} or (on MacOS) the
@t{open} program for opening attachments. If you want to use another program,
you do so by setting the @t{MU_PLAY_PROGRAM} environment variable to the
program to be used.

The default directory for extracting (saving) attachments is your home
directory (@file{~/}); you can change this using the variable
@code{mu4e-attachment-dir}, for example:

@lisp
(setq mu4e-attachment-dir  "~/Downloads")
@end lisp

For more flexibility, @code{mu4e-attachment-dir} can also be a user-provided
function. This function receives two parameters: the file-name and the
mime-type as found in the e-mail message@footnote{sadly, often
@t{application/octet-stream} is used for the mime-type, even if a better type
is available} of the attachment, either or both of which can be @t{nil}. For
example:

@lisp
(setq mu4e-attachment-dir
  (lambda (fname mtype)
    (cond
      ;; docfiles go to ~/Desktop
      ((and fname (string-match "\\.doc$" fname))  "~/Desktop")
      ;; ... other cases  ...
      (t "~/Downloads")))) ;; everything else
@end lisp

You can extract multiple attachments at once by prefixing the extracting
command by @key{C-u}; so @kbd{C-u e} asks you for a range of attachments to
extract (for example, @kbd{1 3-6 8}). The range "@samp{a}" is a shortcut for
@emph{all} attachments.

@node Viewing images inline
@section Viewing images inline

It is possible to show images inline in the message view buffer if you run
@command{emacs} in GUI-mode. You can enable this by setting the variable
@code{mu4e-view-show-images} to @t{t}. Since @command{emacs} does not always
handle images correctly, this is not enabled by default. If you are using
@command{emacs} 24 with
@emph{ImageMagick}@footnote{@url{http://www.imagemagick.org}} support, make
sure you call @code{imagemagick-register-types} in your configuration, so it
is used for images.

@lisp
;; enable inline images
(setq mu4e-view-show-images t)
;; use imagemagick, if available
(when (fboundp 'imagemagick-register-types)
   (imagemagick-register-types))
@end lisp

@node Displaying rich-text messages
@section Displaying rich-text messages

@t{mu4e} normally prefers the plain-text version for messages that consist of
both a plain-text and html (rich-text) versions of the body-text. You can
change this by setting @code{mu4e-view-prefer-html} to @t{t}.

If there is only an html-version, or if the plain-text version is too
short in comparison with the html part@footnote{this is for the case
where the text-part only warns that you should use the html-version},
@t{mu4e} tries to convert the html into plain-text for display.

The default way to do that is to use the @command{emacs} built-in
@code{html2text} function. However, you can set the variable
@code{mu4e-html2text-command} to a either a shell command or a function
instead.

@subsection Html2text commands

If @code{mu4e-html2text-command} is a shell command, it is expected to
take html from standard input and write plain text in @t{UTF-8} encoding
on standard output.

An example of such a program is the program that is actually
@emph{called}
@t{html2text}@footnote{@url{http://www.mbayer.de/html2text/}}. After
installation, you can set it up with something like the following:

@lisp
(setq mu4e-html2text-command "html2text -utf8 -width 72")
@end lisp

An alternative to this is the Python @t{python-html2text} package; after
installing that, you can tell @t{mu4e} to use it with something like:

@lisp
(setq mu4e-html2text-command
   "html2markdown | grep -v '&nbsp_place_holder;'")
@end lisp

OS X, there is a program called @t{textutil} as yet another alternative:

@lisp
(setq mu4e-html2text-command
  "textutil -stdin -format html -convert txt -stdout")
@end lisp

@subsection Html2text functions
@anchor{Html2text functions}

If @code{mu4e-html2text-command} refers to an elisp function, it is
expected to take the current buffer in html as input, and transform it
into text (just like the @code{html2text} function).

For example, emacs 24.4 and later versions include the @code{eww}
browser which uses the @code{shr} html renderer; @t{mu4e} includes a
little snippet to uses this with @code{mu4e-html2text-command}; for
this, add the following to your configuration:

@lisp
(require 'mu4e-contrib)
(setq mu4e-html2text-command 'mu4e-shr2text)
@end lisp

If you use the @code{mu4e-shr2text}, it might be useful to emulate some
of the @t{shr} key bindings, with something like:
@lisp
(add-hook 'mu4e-view-mode-hook
  (lambda()
     ;; try to emulate some of the eww key-bindings
    (local-set-key (kbd "<tab>") 'shr-next-link)
    (local-set-key (kbd "<backtab>") 'shr-previous-link)))
@end lisp

@node MSGV Crypto
@section Crypto

The @t{mu4e} message view supports@footnote{Crypto-support in @t{mu4e}
requires @t{mu} to have been build with crypto-support; see the
@ref{FAQ}} decryption of encrypted messages, as well as verification of
signatures. For signing/encrypting messages your outgoing messages, see
@ref{Signing and encrypting}.

Currently, only PGP/MIME is supported; PGP-inline and S/MIME are not.

For all of this to work, @command{gpg-agent} must be running, and it
must set the environment variable @t{GPG_AGENT_INFO}. You can check from
@command{emacs} with @key{M-x getenv GPG_AGENT_INFO}.

In many mainstream Linux/Unix desktop environments, everything works
out-of-the-box, but if your environment does not automatically start
@command{gpg-agent}, you can do so by hand:
@verbatim
$ eval $(gpg-agent --daemon)
@end verbatim

@noindent
This starts the daemon, and sets the environment variable.

@subsection Decryption
@anchor{Decryption}

If you receive messages that are encrypted (using PGP/MIME), @t{mu4e} can try
to decrypt them, base on the setting of @code{mu4e-decryption-policy}. If you
set it to @t{t}, @t{mu4e} attempts to decrypt messages automatically; this is
the default. If you set it to @t{nil}, @t{mu4e} @emph{won't} attempt to
decrypt anything. Finally, if you set it to @t{'ask}, it asks you what to do,
each time an encrypted message is encountered.

When opening an encrypted message, @t{mu} consults @t{gpg-agent} to see if it
already has unlocked the key needed to decrypt the message; if not, it prompts
you for a password (typically with a separate top-level window). This is only
needed once per session.

@subsection Verifying signatures
@anchor{Verifying signatures}

Some e-mail messages are cryptographically signed, and @t{mu4e} can check the
validity of these signatures. If a message has one or more signatures, the
message view shows an extra header @t{Signature:} (assuming it is part of your
@code{mu4e-view-fields}), and one or more 'verdicts' of the signatures found;
either @t{verified}, @t{unverified} or @t{error}. For instance:

@verbatim
Signature: unverified (Details)
@end verbatim

You can see the details of the signature verification by activating the
@t{Details} or pressing @key{v}. This pops up a little window with the
details of the signatures found and whether they could be verified or not.

For more information, see the @command{mu-verify} manual page.

@node MSGV Custom headers
@section Custom headers

Sometimes the normal headers that @t{mu4e} offers (Date, From, To, Subject
etc.) may not be enough. For these cases, @t{mu4e} offers @emph{custom
headers} in both the headers-view and the message-view.

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

@node MSGV Actions
@section Actions

You can perform custom functions (``actions'') on messages and their
attachments. For a general discussion on how to define your own, see see
@ref{Actions}.

@subsection Message actions
@code{mu4e-view-action} (@key{a}) lets you pick some custom action to perform
on the current message. You can specify these actions using the variable
@code{mu4e-view-actions}; @t{mu4e} defines a number of example actions.

@subsection Attachment actions
Similarly, there is @code{mu4e-view-attachment-action} (@key{A}) for actions
on attachments, which you can specify with
@code{mu4e-view-attachment-actions}.

@t{mu4e} predefines a number of attachment-actions:
@itemize
@item @t{open-with} (@key{w}): open the attachment with some arbitrary
program. For example, suppose you have received a message with a picture
attachment; then, @kbd{A w 1 RET gimp RET} opens that attachment in @emph{The
Gimp}
@item @t{pipe} (@key{|}: process the attachment with some Unix shell-pipe and
see the results. Suppose you receive a patch file, and would like to get an
overview of the changes, using the @t{diffstat} program. You can use something
like: @kbd{A | 1 RET diffstat -b RET}.
@item @command{emacs} (@key{e}): open the attachment in your running @command{emacs}. For
example, if you receive some text file you'd like to open in @command{emacs}:
@kbd{A e 1 RET}.
@end itemize

These actions all work on a @emph{temporary copy} of the attachment.

@node Editor view
@chapter The editor view

Writing e-mail messages takes place in the Editor View. @t{mu4e}'s editor view
builds on top of Gnu's @t{message-mode}. Most of the @t{message-mode}
functionality is available, as well some @t{mu4e}-specifics. Its major mode is
@code{mu4e-compose-mode}.

@menu
* EV Overview::
* Useful keybindings::
* Address autocompletion::
* Compose hooks::
* Signing and encrypting::
* Queuing mail::
* Message signatures::
* Other settings::
@end menu

@node EV Overview
@section Overview

@cartouche
@verbatim
From: Rupert the Monkey <rupert@example.com>
To: Wally the Walrus <wally@example.com>
Subject: Re: Eau-qui d'eau qui?
--text follows this line--

On Mon 16 Jan 2012 10:18:47 AM EET, Wally the Walrus wrote:

 > Hi Rupert,
 >
 > Dude - how are things?
 >
 > Later -- wally.
@end verbatim
@end cartouche


@node Useful keybindings
@section Useful keybindings

@t{mu4e}'s editor view derives from Gnu's message editor and shares most of
its keybindings. Here are some of the more useful ones (you can use the menu
to find more):

@verbatim
key          description
---          -----------
C-c C-c      send message
C-c C-d      save to drafts and leave
C-c C-k      kill the message
C-c C-a      attach a file (pro-tip: drag & drop works as well)

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

@node Address autocompletion
@section Address autocompletion

@t{mu4e} supports@footnote{@command{emacs} 23.2 or higher is required}
autocompleting addresses when composing e-mail messages. @t{mu4e} uses the
e-mail addresses from the messages you sent or received as the source for
this. Address auto-completion is enabled by default; if you want to disable it
for some reason, set @t{mu4e-compose-complete-addresses} to @t{nil}.

Emacs 24 also supports cycling through the alternatives. When there are more
than @emph{5} matching addresses, they are shown in a @t{*Completions*}
buffer. Once the number of matches gets below this number, one is inserted in
the address field and you can cycle through the alternatives using @key{TAB}.

@subsection Limiting the number of addresses

If you have a lot of mail, especially from mailing lists and the like, there
can be a @emph{lot} of e-mail addresses, many of which may not be very useful
when auto-completing. For this reason, @t{mu4e} attempts to limit the number
of e-mail addresses in the completion pool by filtering out the ones that are
not likely to be relevant. The following variables are available for tuning
this:

@itemize
@item @code{mu4e-compose-complete-only-personal} - when set to @t{t},
only consider addresses that were seen in @emph{personal} messages -- that is,
messages in which one of my e-mail addresses was seen in one of the address
fields. This is to exclude mailing list posts. You can define what is
considered 'my e-mail address' using @code{mu4e-user-mail-address-list}, a
list of e-mail address (defaults to @code{user-mail-address}, and when
indexing from the command line, the @t{--my-address} parameter for @t{mu
index}.
@item @code{mu4e-compose-complete-only-after} - only consider e-mail
addresses last seen after some date. Parameter is a string, parseable by
@code{org-parse-time-string}. This excludes old e-mail addresses. The default
is @t{"2010-01-01"}, i.e., only consider e-mail addresses seen since the start
of 2010.
@item @code{mu4e-compose-complete-ignore-address-regexp} - a regular expression to
filter out other 'junk' e-mail addresses; defaults to ``@t{no-?reply}''.
@end itemize

@node Compose hooks
@section Compose hooks

If you want to change some setting, or execute some custom action before
message composition starts, you can define a @emph{hook function}. @t{mu4e}
offers two hooks:
@itemize
@item @code{mu4e-compose-pre-hook}: this hook is run @emph{before} composition
starts; if you are composing a @emph{reply}, @emph{forward} a message, or
@emph{edit} an existing message, the variable
@code{mu4e-compose-parent-message} points to the message being replied to,
forwarded or edited, and you can use @code{mu4e-message-field} to get the
value of various properties (and see @ref{Message functions}).
@item @code{mu4e-compose-mode-hook}: this hook is run just before composition
starts, when the whole buffer has already been set up. This is a good place
for editing-related settings. @code{mu4e-compose-parent-message} (see above)
is also at your disposal.
@end itemize

@noindent
Let's look at some examples. First, suppose we want to set the
@t{From:}-address for a reply message based on the receiver of the original:
@lisp
;; 1) messages to me@@foo.com should be replied with From:me@@foo.com
;; 2) messages to me@@bar.com should be replied with From:me@@bar.com
;; 3) all other mail should use From:me@@cuux.com
(add-hook 'mu4e-compose-pre-hook
  (defun my-set-from-address ()
    "Set the From address based on the To address of the original."
    (let ((msg mu4e-compose-parent-message)) ;; msg is shorter...
      (when msg
	(setq user-mail-address
	  (cond
	    ((mu4e-message-contact-field-matches msg :to "me@@foo.com")
	      "me@@foo.com")
	    ((mu4e-message-contact-field-matches msg :to "me@@bar.com")
	      "me@@bar.com")
	    (t "me@@cuux.com")))))))
@end lisp

Second, as mentioned, @code{mu4e-compose-mode-hook} is especially useful for
editing-related settings. For example:
@lisp
(add-hook 'mu4e-compose-mode-hook
   (defun my-do-compose-stuff ()
      "My settings for message composition."
      (set-fill-column 72)
      (flyspell-mode)))
@end lisp

This hook is also useful for adding headers or changing headers, since the
message is fully formed when this hook runs. For example, to add a
@t{Bcc:}-header, you could add something like the following, using
@code{message-add-header} from @code{message-mode}.

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

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

@node Signing and encrypting
@section Signing and encrypting

Signing and encrypting of messages is possible using @t{emacs-mime}
(@inforef{Composing,,emacs-mime}), most easily accessed through the
@t{Attachments}-menu while composing a message, or with @kbd{M-x
mml-secure-message-encrypt-pgp}, @kbd{M-x mml-secure-message-sign-pgp}.

The support for encryption and signing is @emph{independent} of the support
for their counterparts, decrypting and signature verification (as discussed in
@ref{MSGV Crypto}). Even if your @t{mu4e} does not have support for the latter
two, you can still sign/encrypt messages.

Currently, decryption and signature verification only works for PGP/MIME;
inline-PGP and S/MIME are not supported.

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

@node Queuing mail
@section Queuing mail

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

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

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

For convenience, we put the queue directory somewhere in our normal
maildir. If you want to use queued mail, you should create this directory
before starting @t{mu4e}. The @command{mu mkdir} command may be useful here,
so for example:

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

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

@emph{Warning}: when you switch on queued-mode, your messages @emph{won't}
reach their destination until you switch it off again; so, be careful not to
do this accidentally!

@node Message signatures
@section Message signatures

Message signatures are the standard footer blobs in e-mail messages where you
can put in information you want to include in every message. The text to
include is set with @code{mu4e-compose-signature}.

If you don't want to include this automatically with each message,
you can set @code{mu4e-compose-signature-auto-include} to @code{nil}; you can
then still include the signature manually, using the function
@code{message-insert-signature}, typically bound to @kbd{C-c C-w}.
 

@node Other settings
@section Other settings

@itemize
@item If you want use @t{mu4e} as @command{emacs}' default program for sending mail,
see @ref{Setting the default emacs mail program}.
@item Normally, @t{mu4e} @emph{buries} the message buffer after sending; if you want
to kill the buffer instead, add something like the following to your
configuration:
@lisp
(setq message-kill-buffer-on-exit t)
@end lisp
@item If you want to exclude your own e-mail address when ``replying to
all'', set @code{mu4e-compose-dont-reply-to-self} to @code{t}.  In order
for this to work properly you need to properly set the
@code{user-mail-address} variable or in the case you use multiple e-mail
addresses you need to set the @code{mu4e-user-mail-address-list}
variable accordingly.
@end itemize

@node Searching
@chapter Searching

@t{mu4e} is fully search-based: even if you 'jump to a folder', you are
executing a query for messages that happen to have the property of being in a
certain folder (maildir).

Normally, queries return up to @code{mu4e-headers-results-limit} (default:
500) results. That is usually more than enough, and makes things significantly
faster. Sometimes, however, you may want to show @emph{all} results; you can
enable this with @kbd{M-x mu4e-headers-toggle-full-search}, or by customizing
the variable @code{mu4e-headers-full-search}. This applies to all search
commands.

You can also influence the sort order and whether threads are shown or not;
see @ref{Sort order and threading}.

@menu
* Queries:: Searching for messages.
* Bookmarks:: Remembering queries.
* Maildir searches:: Queries for maildirs.
* Other search functionality:: Some more tricks.
@end menu

@node Queries
@section Queries

@t{mu4e} queries are the same as the ones that @t{mu find}
understands@footnote{with the caveat that command-line queries are subject to
the shell's interpretation before @t{mu} sees them}. Let's look at some
examples here, please refer to the @code{mu-find} and @code{mu-easy} man pages
for details and more examples.

@itemize

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

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

@item Get all messages with subject @emph{wombat} in June 2009
@verbatim
subject:wombat date:20090601..20090630
@end verbatim

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

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

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

@item Get all messages from @emph{Jim} without an attachment:
@verbatim
from:jim AND NOT flag:attach
@end verbatim

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

@item Get all unread messages where the subject mentions Ångström: (search is
case-insensitive and accent-insensitive, so this matches Ångström, angstrom,
aNGstrøM, ...)
@verbatim
subject:Ångström flag:unread
@end verbatim

@item Get all unread messages between Mar-2002 and Aug-2003 about some bird:
@verbatim
date:20020301..20030831 nightingale flag:unread
@end verbatim

@item Get today's messages:
@verbatim
date:today..now
@end verbatim
or, unless you have a really old Xapian
@verbatim
date:today
@end verbatim

@item Get all messages we got in the last two weeks regarding @emph{emacs}:
@verbatim
date:2w..now emacs
@end verbatim
or, unless you have a really old Xapian
@verbatim
date:2w.. emacs
@end verbatim

@item Get messages from the @emph{Mu} mailing list:
@verbatim
list:mu-discuss.googlegroups.com
@end verbatim
Note - in the @ref{Headers view} you may see the 'friendly name' for a
list; however, when searching you need the real name. You can see the
real name for a mailing list from the friendly name's tool-tip.

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

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

@item Get all mails with attachments with filenames starting with @emph{pic}; note
that the '*' wildcard can only appear as the term's rightmost character:
@verbatim
file:pic*
@end verbatim

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

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

@end itemize

@node Bookmarks
@section Bookmarks

If you have queries that you use often, you may want to store them as
@emph{bookmarks}. Bookmark searches are available in the main view @ref{Main
view}, header view @xref{Headers view}, and message view @xref{Message view},
using (by default) the key @key{b} (@kbd{M-x mu4e-search-bookmark}), or
@key{B} (@kbd{M-x mu4e-search-bookmark-edit}) which lets you edit the bookmark
first.

@subsection Setting up bookmarks

@t{mu4e} provides a number of default bookmarks. Their definition is
instructive:

@lisp
(defvar mu4e-bookmarks
  '( ("flag:unread AND NOT flag:trashed" "Unread messages"      ?u)
     ("date:today..now"                  "Today's messages"     ?t)
     ("date:7d..now"                     "Last 7 days"          ?w)
     ("mime:image/*"                     "Messages with images" ?p))
  "A list of pre-defined queries; these show up in the main
screen. Each of the list elements is a three-element list of the
form (QUERY DESCRIPTION KEY), where QUERY is a string with a mu
query, DESCRIPTION is a short description of the query (this
shows up in the UI), and KEY is a shortcut key for the query.")
@end lisp

You can replace these or add your own items, by putting in your
configuration (@file{~/.emacs}) something like:
@lisp
(add-to-list 'mu4e-bookmarks
  '("size:5M..500M"       "Big messages"     ?b))
@end lisp

This prepends your bookmark to the list, and assigns the key @key{b} to it. If
you want to @emph{append} your bookmark, you can use @code{t} as the third
argument to @code{add-to-list}.

In the various @t{mu4e} views, pressing @key{b} lists all the bookmarks
defined in the echo area, with the shortcut key highlighted. So, to invoke the
bookmark we just defined (to get the list of "Big Messages"), all you need to
type is @kbd{bb}.

@subsection Lisp expressions as bookmarks

Instead of using strings, it is also possible to use Lisp expressions as
bookmarks. The only requirement is that they evaluate to a query string.

For example, to get all the messages that are at least a week old in
your inbox:

@lisp
(add-to-list 'mu4e-bookmarks '(
   (concat "maildir:/inbox date:.."
       (format-time-string "%Y%m%d"
                 (subtract-time (current-time) (days-to-time 7))))
    "Messages older than a week" ?O) t)
@end lisp


@subsection Editing bookmarks before searching

There is also @kbd{M-x mu4e-headers-search-bookmark-edit} (key @key{B}), which
lets you edit the bookmarked query before invoking it. This can be useful if
you have many similar queries, but need to change some parameter. For example,
you could have a bookmark @samp{"date:today..now AND "}@footnote{Not a valid
search query by itself}, which limits any result to today's messages.

@node Maildir searches
@section Maildir searches

Maildir searches are quite similar to bookmark searches (see @ref{Bookmarks}),
with the difference being that the target is always a maildir -- maildir
queries provide a 'traditional' folder-like interface to a search-based e-mail
client. By default, maildir searches are available in the @ref{Main view},
@ref{Headers view}, and @ref{Message view}, with the key @key{j}
(@code{mu4e-jump-to-maildir}).

@subsection Setting up maildir shortcuts

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

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

@lisp
   (setq mu4e-maildir-shortcuts
    '( ("/inbox"     . ?i)
       ("/archive"   . ?a)
       ("/lists"     . ?l)
       ("/work"      . ?w)
       ("/sent"      . ?s)))
@end lisp

This sets @key{i} as a shortcut for the @t{/inbox} folder -- effectively a
query @t{maildir:/inbox}. There is a special shortcut @key{o} or @key{/} for
@emph{other} (so don't use those for your own shortcuts!), which allows you to
choose from @emph{all} maildirs that you have. There is support for
autocompletion; note that the list of maildirs is determined when @t{mu4e}
starts; if there are changes in the maildirs while @t{mu4e} is running, you
need to restart @t{mu4e}.

Each of the folder names is relative to your top-level maildir directory; so
if you keep your mail in @file{~/Maildir}, @file{/inbox} would refer to
@file{~/Maildir/inbox}. With these shortcuts, you can jump around your
maildirs (folders) very quickly - for example, getting to the @t{/lists}
folder only requires you to type @kbd{jl}, then change to @t{/work} with
@kbd{jw}.

While in queries you need to quote folder names (maildirs) with spaces in
them, you should @emph{not} quote them when used in
@code{mu4e-maildir-shortcuts}, since @t{mu4e} does that automatically for you.

The very same shortcuts are used by @kbd{M-x mu4e-mark-for-move} (default
shortcut @key{m}); so, for example, if you want to move a message to the
@t{/archive} folder, you can do so by typing @kbd{ma}.

@node Other search functionality
@section Other search functionality

@subsection Navigating through search queries
You can navigate through previous/next queries using
@code{mu4e-headers-query-prev} and @code{mu4e-headers-query-next}, which are
bound to @key{M-left} and @key{M-right}, similar to what some web browsers do.

@t{mu4e} tries to be smart and not record duplicate queries. Also, the number
of queries remembered has a fixed limit, so @t{mu4e} won't use too much
memory, even if used for a long time. However, if you want to forget
previous/next queries, you can use @kbd{M-x mu4e-headers-forget-queries}.

@subsection Narrowing search results

It can be useful to narrow existing search results, that is, to add some
clauses to the current query to match fewer messages.

For example, suppose you're looking at some mailing list, perhaps by
jumping to a maildir (@kbd{M-x mu4e-headers-jump-to-maildir}, @key{j}) or
because you followed some bookmark (@kbd{M-x mu4e-headers-search-bookmark},
@key{b}). Now, you want to narrow things down to only those messages that have
attachments.

This is when @kbd{M-x mu4e-headers-search-narrow} (@key{/}) comes in handy. It
asks for an additional search pattern, which is appended to the current search
query, in effect getting you the subset of the currently shown headers that
also match this extra search pattern. @key{\} takes you back to the previous
query, so, effectively 'widens' the search. Technically, narrowing the results
of query @t{x} with expression @t{y} implies doing a search @t{(x) AND y}.

Note, messages that were not in your in your original search results because
of @code{mu4e-headers-results-limit}, may show up in the narrowed query.

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

It can be useful to not only show the messages that directly match a certain
query, but also include messages that are related to these messages. That is,
messages that belong to the same discussion threads are included in the
results, just like e.g. Gmail does it. You can enable this behavior by setting
@code{mu4e-headers-include-related} to @code{t}, and you can toggle between
including/not-including with @key{W}.

Be careful though when e.g. deleting ranges of messages from a certain folder
-- the list may now also include messages from @emph{other} folders.

@subsection Skipping duplicates
@anchor{Skipping duplicates}

Another useful feature is skipping of @emph{duplicate messages}. When you have
copies of messages, there's usually little value in including more than one in
search results. A common reason for having multiple copies of messages is the
combination of Gmail and @t{offlineimap}, since that is the way the labels /
virtual folders in Gmail are represented. You can enable skipping duplicates
by setting @code{mu4e-headers-skip-duplicates} to @code{t}, and you can toggle
between the skipping/not skipping with @key{V}.

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

@node Marking
@chapter Marking

In @t{mu4e}, the common way to do things with messages is a two-step process -
first you @emph{mark} them for a certain action, then you @emph{execute}
(@key{x}) those marks. This is similar to the way @t{dired} operates. Marking
can happen in both the @ref{Headers view} and the @ref{Message view}.

@menu
* Selecting messages for marking::
* What to mark for::
* Executing the marks::
* Leaving the headers buffer::
* Built-in marking functions::
* Custom mark functions::
* Adding a new kind of mark::
@end menu

@node Selecting messages for marking
@section Selecting messages for marking

There are multiple ways to mark messages:
@itemize
@item @emph{message at point}: you can put a mark on the message-at-point in
either the @ref{Headers view} or @ref{Message view}
@item @emph{region}: you can put a mark on all messages in the current region
(selection) in the @ref{Headers view}
@item @emph{pattern}: you can put a mark on all messages in the @ref{Headers
view} matching a certain pattern with @kbd{M-x mu4e-headers-mark-pattern}
(@key{%})
@item @emph{thread/subthread}: You can put a mark on all the messages in the
thread/subthread at point with @kbd{M-x mu4e-headers-mark-thread} and @kbd{M-x
mu4e-headers-mark-subthread}, respectively
@end itemize

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

@t{mu4e} supports a number of marks:

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

After marking a message, the left-most columns in the headers view indicate
the kind of mark. This is informative, but if you mark many (say, thousands)
messages, this slows things down significantly@footnote{this uses an
@command{emacs} feature called @emph{overlays}, which are slow when used a lot
in a buffer}. For this reason, you can disable this by setting
@code{mu4e-headers-show-target} to @code{nil}.

@t{something} is a special kind of mark; you can use it to mark messages
for 'something', and then decide later what the 'something' should
be@footnote{This kind of 'deferred marking' is similar to the facility
in @t{dired}, @t{midnight commander}
(@url{http://www.midnight-commander.org/}) and the like, and uses the
same key binding (@key{insert}).}  Later, you can set the actual mark
using @kbd{M-x mu4e-mark-resolve-deferred-marks}
(@key{#}). Alternatively, @t{mu4e} will ask you when you try to execute
the marks (@key{x}).

@node Executing the marks
@section Executing the marks

After you have marked some messages, you can execute them with @key{x}
(@kbd{M-x mu4e-mark-execute-all}).

@node Leaving the headers buffer
@section Leaving the headers buffer

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

@node Built-in marking functions
@section Built-in marking functions

Some examples of @t{mu4e}'s built-in marking functions.

@itemize
@item @emph{Mark the message at point for trashing}: press @key{d}
@item @emph{Mark all messages in the buffer as unread}: press @kbd{C-x h o}
@item @emph{Delete the messages in the current thread}: press @kbd{T D}
@item @emph{Mark messages with a subject matching ``hello'' for flagging}:
press @kbd{% s hello RET}.
@end itemize

@node Custom mark functions
@section Custom mark functions

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

Custom mark functions are to be appended to the list
@code{mu4e-headers-custom-markers}. Each of the elements of this list
('markers') is a list with two or three elements:
@enumerate
@item The name of the marker - a short string describing this marker. The
first character of this string determines its shortcut, so these should be
unique. If necessary, simply prefix the name with a unique character.
@item a predicate function, taking two arguments @var{msg} and @var{param}.
@var{msg} is the message plist (see @ref{Message functions}) and @var{param} is
a parameter provided by the third of the marker elements (see the next
item). The predicate function should return non-@t{nil} if the message
matches.
@item (optionally) a function that is evaluated once, and the result is passed as a
parameter to the predicate function. This is useful when user-input is needed.
@end enumerate

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

@lisp
(add-to-list 'mu4e-headers-custom-markers
  '("More than n recipients"
      (lambda (msg n)
        (> (+ (length (mu4e-message-field msg :to))
              (length (mu4e-message-field msg :cc))) n))
      (lambda ()
        (read-number "Match messages with more recipients than: "))) t)
@end lisp

After evaluating this expression, you can use it by pressing @key{&} in
the headers buffer to select a custom marker function, and then @key{M}
to choose this particular one (@t{M} because it is the first character
of the description).

As you can see, it's not very hard to define simple functions to match
messages. There are more examples in the defaults for
@code{mu4e-headers-custom-markers}; see @file{mu4e-headers.el} and see
@ref{Extending mu4e} for general information about writing your own functions.


@node Adding a new kind of mark
@section Adding a new kind of mark

It is possible to configure new marks. To do so one can add entries
in the list @code{mu4e-marks}. Such an element must have the following form:

@lisp
(SYMBOL
  :char STRING
  :prompt STRING
  :ask-target (lambda () TARGET)
  :dyn-target (lambda (TARGET MSG) DYN-TARGET)
  :show-target (lambda (DYN-TARGET) STRING)
  :action (lambda (DOCID MSG DYN-TARGET) nil))
@end lisp

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

@itemize
@item @code{:char} -- the character to display in the headers view.
@item @code{:prompt} -- the prompt to use when asking for marks (used for example when marking a whole thread).
@item @code{:ask-target} -- a function run once per bulk-operation, and thus suitable for
querying the user about a target for move-like marks. If nil, the
TARGET passed to @code{:dyn-target} is nil.
@item @code{: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 @code{:action} is the TARGET obtained as above.
@item @code{:show-target} -- how to display the target in the headers view.
If @code{:show-target} is nil the DYN-TARGET is shown (and DYN-TARGET must be
a string).
@item @code{:action} -- the action to apply on the message when the mark is executed.
@end itemize

As an example, suppose we would like to add a mark for tagging
messages (gmail-style), then we can run the following code (after
loading mu4e):

@lisp
(add-to-list 'mu4e-marks
   '(tag
     :char       "g"
     :prompt     "gtag"
     :ask-target (lambda () (read-string "What tag do you want to add?"))
     :action      (lambda (docid msg target)
                    (mu4e-action-retag-message msg (concat "+" target)))))
@end lisp

As another example, suppose we would like to ``archive and mark read''
a message (gmail-style), then we can run the following code (after
loading mu4e):

@lisp
(add-to-list 'mu4e-marks
   '(archive
     :char       "A"
     :prompt     "Archive"
     :show-target (lambda (target) "archive")
     :action      (lambda (docid msg target)
                    ;; must come before proc-move since retag runs
                    ;; 'sed' on the file
                    (mu4e-action-retag-message msg "-\\Inbox")
                    (mu4e~proc-move docid nil "+S-u-N"))))
@end lisp

Adding to @code{mu4e-marks} list allows to use the mark in bulk operations
(for example when tagging a whole thread), but does not bind the mark
to a key to use at the top-level. This must be done separately. In our
example:

@lisp
(mu4e~headers-defun-mark-for tag)
(mu4e~headers-defun-mark-for archive)
(define-key mu4e-headers-mode-map (kbd "g") 'mu4e-headers-mark-for-tag)
(define-key mu4e-headers-mode-map (kbd "A") 'mu4e-headers-mark-for-archive)
@end lisp

@node Dynamic folders
@chapter Dynamic folders

In @ref{Folders}, we explained how you can set up @t{mu4e}'s special folders:
@lisp
(setq
  mu4e-sent-folder   "/sent"       ;; sent messages
  mu4e-drafts-folder "/drafts"     ;; unfinished messages
  mu4e-trash-folder  "/trash"      ;; trashed messages
  mu4e-refile-folder "/archive")   ;; saved messages
@end lisp

In some cases, having such static folders may not suffice - perhaps you want
to change the folders depending on the context. For example, the folder for
refiling could vary, based on the sender of the message.

To make this possible, instead of setting the standard folders to a string,
you can set them to be a @emph{function} that takes a message as its
parameter, and returns the desired folder name. This chapter shows you how to
do that. For a more general discussion of how to extend @t{mu4e} and writing
your own functions, see @ref{Extending mu4e}.

@menu
* Smart refiling:: Automatically choose the target folder
* Other dynamic folders:: Flexible folders for sent, trash, drafts
@end menu


@node Smart refiling
@section Smart refiling

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

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

@lisp
(setq mu4e-refile-folder
  (lambda (msg)
    (cond
      ;; messages to the mu mailing list go to the /mu folder
      ((mu4e-message-contact-field-matches msg :to
        "mu-discuss@@googlegroups.com")
      	"/mu")
      ;; messages sent directly to me go to /archive
      ;; also `mu4e-user-mail-address-p' can be used
      ((mu4e-message-contact-field-matches msg :to "me@@example.com")
        "/private")
      ;; messages with football or soccer in the subject go to /football
      ((string-match "football\\|soccer"
        (mu4e-message-field msg :subject))
        "/football")
      ;; messages sent by me go to the sent folder
      ((find-if
	 (lambda (addr)
	   (mu4e-message-contact-field-matches msg :from addr))
	 mu4e-user-mail-address-list)
	mu4e-sent-folder)
      ;; everything else goes to /archive
      ;; important to have a catch-all at the end!
      (t  "/archive"))))
@end lisp

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

Some notes:
@itemize
@item We set @code{mu4e-refile-folder} to an anonymous (@t{lambda}) function. This
function takes one argument, a message plist@footnote{a property list
describing a message}. The plist corresponds to the message at point. See
@ref{Message functions} for a discussion on how to deal with them.
@item In our function, we use a @t{cond} control structure; the function
returns the first of the clauses that matches. It's important to make the last
clause a catch-all, so we always return @emph{some} folder.
@item We use
the convenience function @code{mu4e-message-contact-field-matches}, which
evaluates to @code{t} if any of the names or e-mail addresses in a contact
field (in this case, the @t{To:}-field) matches the regular expression.
@end itemize

@node Other dynamic folders
@section Other dynamic folders

Using the same mechanism, you can create dynamic sent-, trash-, and
drafts-folders. The message-parameter you receive for the sent and drafts
folder is the @emph{original} message, that is, the message you reply to, or
forward, or edit. If there is no such message (for example when composing a
brand new message) the message parameter is @t{nil}.

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

@lisp
 (setq mu4e-trash-folder
    (lambda (msg)
       ;; the 'and msg' is to handle the case where msg is nil
       (if (and msg
             (mu4e-message-contact-field-matches msg :to "me@@work.com"))
        "/trash-work"
        "/trash")))
@end lisp

@noindent
Good to remember:
@itemize
@item The @var{msg} parameter you receive in the function refers to the
@emph{original message}, that is, the message being replied to or
forwarded. When re-editing a message, it refers to the message being
edited. When you compose a totally new message, the @var{msg} parameter is
@code{nil}.
@item When re-editing messages, the value of @code{mu4e-drafts-folder} is ignored.
@end itemize


@node Actions
@chapter Actions

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

You can invoke the actions with key @key{a} for actions on messages, and key
@key{A} for actions on attachments.

For general information extending @t{mu4e} and writing your own functions, see
@ref{Extending mu4e}.

@menu
* Defining actions::
* Adding an action in the headers view::
* Adding an action in the message view::
* Adding an attachment action::
* More example actions::
@end menu

@node Defining actions
@section Defining actions

Defining a new custom action comes down to writing an elisp-function to do the
work. Functions that operate on messages receive a @var{msg} parameter, which
corresponds to the message at point. Something like:
@lisp
(defun my-action-func (msg)
 "Describe my message function."
;; do stuff
)
@end lisp

@noindent
Messages that operate on attachments receive a @var{msg} parameter, which
corresponds to the message at point, and an @var{attachment-num}, which is the
number of the attachment as seen in the message view. An attachment function
looks like:
@lisp
(defun my-attachment-action-func (msg attachment-num)
 "Describe my attachment function."
;; do stuff
)
@end lisp

@noindent
After you have defined your function, you can add it to the list of
actions@footnote{Instead of defining the functions separately, you can
obviously also add a @code{lambda}-function directly to the list; however,
separate functions are easier to change}, either @code{mu4e-headers-actions},
@code{mu4e-view-actions} or @code{mu4e-view-attachment-actions}.  The
format@footnote{Note, the format of the actions has changed since version
0.9.8.4, and you must change your configuration to use the new format;
@t{mu4e} warns you when you are using the old format.} of each action is a
cons-cell, @code{(DESCRIPTION . VALUE)}; see below for some examples. If your
shortcut is not also the first character of the description, simply prefix the
description with that character.

Let's look at some examples.

@node Adding an action in the headers view
@section Adding an action in the headers view

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

@lisp
(defun show-number-of-recipients (msg)
  "Display the number of recipients for the message at point."
  (message "Number of recipients: %d"
     (+ (length (mu4e-message-field msg :to))
        (length (mu4e-message-field msg :cc)))))

;; define 'N' (the first letter of the description) as the shortcut
;; the 't' argument to add-to-list puts it at the end of the list
(add-to-list 'mu4e-headers-actions
   '("Number of recipients" . show-number-of-recipients) t)
@end lisp

After evaluating this, @kbd{a N} in the headers view shows the number of
recipients for the message at point.

@node Adding an action in the message view
@section Adding an action in the message view

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

@lisp
(defun search-for-sender (msg)
  "Search for messages sent by the sender of the message at point."
  (mu4e-headers-search
     (concat "from:" (cdar (mu4e-message-field msg :from)))))

;; define 'x' as the shortcut
(add-to-list 'mu4e-view-actions
   '("xsearch for sender" . search-for-sender) t)
@end lisp

@indent
If you wonder why we use @code{cdar}, remember that the @t{From:}-field is a
list of @code{(NAME . EMAIL)} cells; thus, @code{cdar} gets us the e-mail
address of the first in the list. @t{From:}-fields rarely contain multiple
cells.

@node Adding an attachment action
@section Adding an attachment action

Finally, let's define an attachment action. As mentioned, attachment-action
functions receive @emph{2} arguments, the message and the attachment number to
use.

The following example action counts the number of lines in an attachment, and
defines @key{n} as its shortcut key (the @key{n} is prefixed to the
description).

@lisp
(defun count-lines-in-attachment (msg attachnum)
  "Count the number of lines in an attachment."
  (mu4e-view-pipe-attachment msg attachnum "wc -l"))

;; defining 'n' as the shortcut
(add-to-list 'mu4e-view-attachment-actions
   '("ncount lines" . count-lines-in-attachment) t)
@end lisp

@node More example actions
@section More example actions

@t{mu4e} includes a number of example actions in the file
@file{mu4e-actions.el} in the source distribution (see @kbd{C-h f
mu4e-action-TAB}). For example, for viewing messages in an external web
browser, or listening to a message's body-text using text-to-speech.

@node Extending mu4e
@chapter Extending mu4e

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

@menu
* Extension points::
* Available functions::
* Message functions::
* Contact functions::
* Utility functions::
@end menu

@node Extension points
@section Extension points

There are a number of places where @t{mu4e} lets you plug in your own
functions:
@itemize
@item Custom functions for message headers in the message-view and
headers-view - see @ref{HV Custom headers}, @ref{MSGV Custom headers}
@item Using message-specific folders for drafts, trash, sent messages and
refiling, based on a function - see @ref{Dynamic folders}
@item Using an attachment-specific download-directory - see the
variable @code{mu4e-attachment-dir}.
@item Apply a function to a message in the headers view -
see @ref{Adding an action in the headers view}
@item Apply a function to a message in the message view - see @ref{Adding an
action in the message view}
@item Add a new kind of mark for use in the headers view
- see @ref{Adding a new kind of mark}
@item Apply a function to an attachment - see @ref{Adding an attachment
action}
@item Custom function to mark certain messages - see @ref{Custom mark functions}
@item Using various @emph{mode}-hooks, @code{mu4e-compose-pre-hook} (see
@ref{Compose hooks}), @code{mu4e-index-updated-hook} (see @ref{FAQ})
@end itemize

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

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

@node Available functions
@section Available functions

The whole of @t{mu4e} consists of hundreds of elisp functions. However, the
majority of those are for @emph{internal} use only; you can recognize them
easily, because they all start with @code{mu4e~}. These function make all
kinds of assumptions, and they are subject to change, and should therefore
@emph{not} be used. The same is true for @emph{variables} that start with
@code{mu4e~}; don't touch them.  Let me repeat that:
@verbatim
    Do not use mu4e~... functions or variables!
@end verbatim

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

@node Message functions
@section Message functions

Many functions in @t{mu4e} deal with message plist (property
lists). They contain information about messages, such as sender and
recipient, subject, date and so on. To deal with these plists, there are
a number of @code{mu4e-message-} functions (in @file{mu4e-message.el}),
such as @code{mu4e-message-field} and @code{mu4e-message-at-point}, and
a shortcut to combine the two, @code{mu4e-message-field-at-point}.

For example, to get the subject of the message at point, in either the headers
view or the message view, you could write:
@lisp
(mu4e-message-field (mu4e-message-at-point) :subject)
@end lisp
@noindent
Note that:
@itemize
@item The contact fields (To, From, Cc, Bcc) are lists of cons-pairs
@code{(name . email)}; @code{name} may be @code{nil}. So, for example:
@lisp
(mu4e-message-field some-msg :to)
;; => (("Jack" . "jack@@example.com") (nil . "foo@@example.com"))
@end lisp
If you are only looking for a match in this list (e.g., ``Is Jack one of the
recipients of the message?''), there is a convenience function
@code{mu4e-message-contact-field-matches} to make this easy.
@item The message body is only available in the message view, not in the
headers view.
@end itemize

Note that the message-functions work available to @t{mu4e} -- the
headers that are stored in the database and, in
@code{mu4e-message-view}-context, the message body.

If you need access to other parts of the message, it is possible to do
so by hand, using the raw-message and some third-party tool like
@t{procmail}'s @t{formail}:
@lisp
(defun my-mu4e-any-message-field-at-point (hdr)
  "Quick & dirty way to get an arbitrary header HDR at
point. Requires the 'formail' tool from procmail."
   (replace-regexp-in-string "\n$" ""
     (shell-command-to-string
       (concat "formail -x " hdr " -c < "
	 (shell-quote-argument (mu4e-message-field-at-point :path))))))
@end lisp


@node Contact functions
@section Contact functions

It can be useful to rewrite the contact information that @t{mu4e}
provides, for example to convert them to some standardized format, or
to fix spelling errors.

You can do this by setting @code{mu4e-contact-rewrite-function} to
your function, for example:

@lisp
(defun my-rewrite-function (contact)
   (let* ((name (plist-get contact :name))
	   (mail (plist-get contact :mail))
	   (actual-name
	     (cond
	       ((string= name "jonh smiht") "John Smith")
	       ;; other replacements
	       (t name))))
     (list :name actual-name :mail mail)))
(setq mu4e-contact-rewrite-function 'my-rewrite-function)
@end lisp

This function is called for each of your contacts.

@node Utility functions
@section Utility functions

@file{mu4e-utils} contains a number of utility functions; we list a few here;
see their docstrings for the details:
@itemize
@item @code{mu4e-read-option}: read one option from a list. For example:
@lisp
 (mu4e-read-option "Choose an animal: "
    '(("Monkey" . monkey) ("Gnu" . gnu) ("xMoose" . moose)))
@end lisp
The user is presented with:
@example
 Choose an animal: [M]onkey, [G]nu, [x]Moose
@end example
@item @code{mu4e-ask-maildir}: ask for a maildir; try one of the
shortcuts (@code{mu4e-maildir-shortcuts}), or the full set of available
maildirs.
@item @code{mu4e-running-p}: return @code{t} if the @t{mu4e} process is
running, @code{nil} otherwise.
@item @code{(mu4e-user-mail-address-p addr)}: return @code{t} if @var{addr} is
one of the user's e-mail addresses (as per @code{mu4e-user-mail-address-list}).
@item @code{mu4e-log} logs to the @t{mu4e} debugging log if it is enabled;
      see @code{mu4e-toggle-logging}.
@item @code{mu4e-message}, @code{mu4e-warning}, @code{mu4e-error} are the
@t{mu4e} equivalents of the normal elisp @code{message},
@code{user-error}@footnote{@code{user-error} only appears in @command{emacs}
24.2 and later; in older versions it falls back to @code{error}} and
@code{error} functions.
@end itemize


@node Interaction with other tools
@appendix Interaction with other tools

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

@menu
* Setting the default emacs mail program::
* Creating org-mode links::
* Rich-text messages with org-mode::
* Maintaining an address-book with org-contacts::
* Maintaining an address-book with BBDB::
* Getting new mail notifications with Sauron::
* Speedbar support::
* Citations with mu-cite::
* Attaching files with dired::
@end menu

@node Setting the default emacs mail program
@section Setting the default @command{emacs} mail program

@command{emacs} allows you to select an e-mail program as the default program
it uses when you press @key{C-x m} (@code{compose-mail}), call
@code{report-emacs-bug} and so on. If you want to use @t{mu4e} for this, you
do so by adding the following to your configuration:

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

@noindent
At the present time, support is @emph{experimental}.

@node Creating org-mode links
@section Creating @t{org-mode} links
It can be useful to include links to e-mail messages or even search queries in
your org-mode files. @t{mu4e} supports this with the @t{org-mu4e} module; you
can set it up by adding it to your configuration:

@lisp
(require 'org-mu4e)
@end lisp

this expects org-mode 8.x. If you have an older version, you can try:

@lisp
(require 'org-old-mu4e)
@end lisp

@noindent
After this, you can use the normal @t{org-mode} mechanisms to store
links: @kbd{M-x org-store-link} stores a link to a particular message
when you are in @ref{Message view}. When you are in @ref{Headers view},
@kbd{M-x org-store-link} links to the @emph{query} if
@code{org-mu4e-link-query-in-headers-mode} is non-@code{nil}, and to the
particular message otherwise.

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

@node Rich-text messages with org-mode
@section Rich-text messages with @t{org-mode} (deprecated)

It is possible to write rich-text messages using @t{org-mode}; see
@url{http://orgmode.org/worg/org-contrib/org-mime.html}.

Note, some earlier versions of @t{mu4e} had more elaborate support for
editing e-mail messages using @t{org-mode}; since this never worked very
well, this has now been deprecated; it might be replaced with something
better in some future version.

@node Maintaining an address-book with org-contacts
@section Maintaining an address-book with org-contacts

Note, @t{mu4e} supports built-in address autocompletion; @ref{Address
autocompletion}, and that is the recommended way to do this. However, it is
also possible to manage your addresses with @t{org-mode}, using
@t{org-contacts}@footnote{@url{http://julien.danjou.info/software/org-contacts.el}}.

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

@lisp
(setq mu4e-org-contacts-file  <full-path-to-your-org-contacts-file>)
(add-to-list 'mu4e-headers-actions
  '("org-contact-add" . mu4e-action-add-org-contact) t)
(add-to-list 'mu4e-view-actions
  '("org-contact-add" . mu4e-action-add-org-contact) t)
@end lisp

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

@node Maintaining an address-book with BBDB
@section Maintaining an address-book with BBDB

Note, @t{mu4e} supports built-in address autocompletion; @ref{Address
autocompletion}, and that is the recommended way to do this. However, it
is also possible to manage your addresses with the current (2015-06-23)
development release of @t{BBDB}, or releases of @t{BBDB} after
3.1.2.@footnote{@url{http://savannah.nongnu.org/projects/bbdb/}}.

To enable BBDB, add to your @file{~/.emacs} (or its moral equivalent,
such as @file{~/.emacs.d/init.el}) the following @emph{after} the
@code{(require 'mu4e)} line:

@lisp
;; Load BBDB (Method 1)
(require 'bbdb-loaddefs) 
;; OR (Method 2)
;; (require 'bbdb-loaddefs "/path/to/bbdb/lisp/bbdb-loaddefs.el")
;; OR (Method 3)
;; (autoload 'bbdb-insinuate-mu4e "bbdb-mu4e")
;; (bbdb-initialize 'message 'mu4e)
(setq bbdb-mail-user-agent (quote message-user-agent))
(setq mu4e-view-mode-hook (quote (bbdb-mua-auto-update visual-line-mode)))
(setq mu4e-compose-complete-addresses nil)
(setq bbdb-mua-pop-up t)
(setq bbdb-mua-pop-up-window-size 5)
@end lisp

@noindent
After this, you should be able to:
@itemize
@item In mu4e-view mode, add the sender of the email to BBDB with @key{C-u :}
@item Tab-complete addresses from BBDB when composing emails
@item View the BBDB contact while viewing a message
@end itemize

@node Getting new mail notifications with Sauron
@section Getting new mail notifications with Sauron

The @command{emacs}-package @t{sauron}@footnote{Sauron can be found at
@url{https://github.com/djcb/sauron}, or in the Marmalade package-repository
at @url{http://http://marmalade-repo.org/}} (by the same author) can be used
to get notifications about new mails. If you run something like the below
script from your @t{crontab} (or have some other way of having it execute
every @emph{n} minutes), you receive notifications in the @t{sauron}-buffer
when new messages arrive.

@verbatim
#!/bin/sh

# the mu binary
MU=mu

# put the path to your Inbox folder here
CHECKDIR="/home/$LOGNAME/Maildir/Inbox"

sauron_msg () {
    DBUS_COOKIE="/home/$LOGNAME/.sauron-dbus"
    if test "x$DBUS_SESSION_BUS_ADDRESS" = "x"; then
        if test -e $DBUS_COOKIE; then
                export DBUS_SESSION_BUS_ADDRESS="`cat $DBUS_COOKIE`"
        fi
    fi
    if test -n "x$DBUS_SESSION_BUS_ADDRESS"; then
        dbus-send --session                          \
            --dest="org.gnu.Emacs"                   \
            --type=method_call                       \
            "/org/gnu/Emacs/Sauron"                  \
            "org.gnu.Emacs.Sauron.AddMsgEvent"       \
            string:shell uint32:3 string:"$1"
    fi
}

#
# -mmin -5: consider only messages that were created / changed in the
# the last 5 minutes
#
for f in `find $CHECKDIR -mmin -5 -a -type f`; do
        subject=`$MU view $f | grep '^Subject:' | sed 's/^Subject://'`
        sauron_msg "mail: $subject"
done
@end verbatim

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

@node Speedbar support
@section Speedbar support

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

@t{mu4e} loads @t{mu4e-speedbar} automatically; all you need to do to activate
it is @kbd{M-x speedbar}. Then, when then switching to the @ref{Main view},
the speedbar-frame is updated with your bookmarks and maildirs. For speed
reasons, the list of maildirs is determined when @t{mu4e} starts; if the list
of maildirs changes while @t{mu4e} is running, you need to restart @t{mu4e} to
have those changes reflected in the speedbar and in other places that use this
list, such as auto-completion when jumping to a maildir.

@code{mu4e-speedbar} was contributed by @emph{Antono Vasiljev}.

@node Citations with mu-cite
@section Citations with @t{mu-cite}

@t{mu-cite}@footnote{Note, despite its name, @t{mu-cite} is a project
unconnected to @t{mu}/@t{mu4e}} is a package to control the way message
citations look like (i.e., the message you responded to when you reply to them
or forward them), with its latest version available at
@url{http://www.jpl.org/elips/mu/}.

After installing @t{mu-cite}, you can use something like the following to make
it work with @t{mu4e}:

@lisp
(require 'mu-cite)
(setq mu4e-cite-function 'mu-cite-original)
(setq mu-cite-top-format
    '("On " date ", " from " wrote:\n\n"))
(setq mu-cite-prefix-format '(" > ")))
@end lisp

@node Attaching files with dired
@section Attaching files with @t{dired}

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

To prepare for this, you need a special version of the
@code{gnus-dired-mail-buffers} function so it understands @t{mu4e} buffers as
well; so put in your configuration:

@lisp
(require 'gnus-dired)
;; make the `gnus-dired-mail-buffers' function also work on
;; message-mode derived modes, such as mu4e-compose-mode
(defun gnus-dired-mail-buffers ()
  "Return a list of active message buffers."
  (let (buffers)
    (save-current-buffer
      (dolist (buffer (buffer-list t))
	(set-buffer buffer)
	(when (and (derived-mode-p 'message-mode)
		(null message-sent-message-via))
	  (push (buffer-name buffer) buffers))))
    (nreverse buffers)))

(setq gnus-dired-mail-mode 'mu4e-user-agent)
(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode)
@end lisp

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

@node Example configurations
@appendix Example configurations

In this chapter, we show some example configurations. While it is very useful
to see some working settings, we'd like to warn against blindly copying such
things.

@menu
* Minimal configuration::
* Longer configuration::
* Gmail configuration::
* Some other useful settings::

@end menu


@node Minimal configuration
@section Minimal configuration

An (almost) minimal configuration for @t{mu4e} might look like this - as you
see most is commented-out.

@lisp
;; example configuration for mu4e

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

;; Only needed if your maildir is _not_ ~/Maildir
;; Must be a real dir, not a symlink
;;(setq mu4e-maildir "/home/user/Maildir")

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

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

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


@node Longer configuration
@section Longer configuration

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

@lisp
;; example configuration for mu4e
(require 'mu4e)

;; path to our Maildir directory
(setq mu4e-maildir "/home/user/Maildir")

;; the next are relative to `mu4e-maildir'
;; instead of strings, they can be functions too, see
;; their docstring or the chapter 'Dynamic folders'
(setq mu4e-sent-folder   "/sent"
      mu4e-drafts-folder "/drafts"
      mu4e-trash-folder  "/trash")

;; the maildirs you use frequently; access them with 'j' ('jump')
(setq   mu4e-maildir-shortcuts
    '(("/archive"     . ?a)
      ("/inbox"       . ?i)
      ("/work"        . ?w)
      ("/sent"        . ?s)))

;; a  list of user's e-mail addresses
(setq mu4e-user-mail-address-list '("foo@@bar.com" "cuux@@example.com")

;; when you want to use some external command for text->html
;; conversion, e.g. the 'html2text' program
;; (setq mu4e-html2text-command "html2text")

;; the headers to show in the headers list -- a pair of a field
;; and its width, with `nil' meaning 'unlimited'
;; (better only use that for the last field.
;; These are the defaults:
(setq mu4e-headers-fields
    '( (:date          .  25)    ;; alternatively, use :human-date
       (:flags         .   6)
       (:from          .  22)
       (:subject       .  nil))) ;; alternatively, use :thread-subject

;; program to get mail; alternatives are 'fetchmail', 'getmail'
;; isync or your own shellscript. called when 'U' is pressed in
;; main view.

;; If you get your mail without an explicit command,
;; use "true" for the command (this is the default)
(setq mu4e-get-mail-command "offlineimap")

;; general emacs mail settings; used when composing e-mail
;; the non-mu4e-* stuff is inherited from emacs/message-mode
(setq mu4e-reply-to-address "foo@@bar.com"
      user-mail-address "foo@@bar.com"
      user-full-name  "Foo X. Bar")
(setq mu4e-compose-signature
   "Foo X. Bar\nhttp://www.example.com\n")

;; smtp mail setting
(setq
   message-send-mail-function 'smtpmail-send-it
   smtpmail-default-smtp-server "smtp.example.com"
   smtpmail-smtp-server "smtp.example.com"
   smtpmail-local-domain "example.com"

   ;; if you need offline mode, set these -- and create the queue dir
   ;; with 'mu mkdir', i.e.. mu mkdir /home/user/Maildir/queue
   smtpmail-queue-mail  nil
   smtpmail-queue-dir  "/home/user/Maildir/queue/cur")

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


@node Gmail configuration
@section Gmail configuration

@emph{Gmail} is a popular e-mail provider; let's see how we can make it work
with @t{mu4e}. Since we are using @abbr{IMAP}, you must enable that in the
Gmail web interface (in the settings, under the ``Forwarding and
POP/IMAP''-tab).

Gmail users may also be interested in @ref{Including related messages,
skipping duplicates}.

@subsection Setting up offlineimap

First of all, we need a program to get the e-mail from Gmail to our local
machine; for this we use @t{offlineimap}; on Debian (and derivatives like
Ubuntu), this is as easy as:

@verbatim
$ sudo apt-get install offlineimap
@end verbatim

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

Then, we can configure @t{offlineimap} by editing @file{~/.offlineimaprc}:

@verbatim
[general]
accounts = Gmail
maxsyncaccounts = 3

[Account Gmail]
localrepository = Local
remoterepository = Remote

[Repository Local]
type = Maildir
localfolders = ~/Maildir

[Repository Remote]
type = IMAP
remotehost = imap.gmail.com
remoteuser = USERNAME@gmail.com
remotepass = PASSWORD
ssl = yes
maxconnections = 1
realdelete = no
@end verbatim

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

@verbatim
$ offlineimap
 OfflineIMAP 6.3.4
Copyright 2002-2011 John Goerzen & contributors.
Licensed under the GNU GPL v2+ (v2 or any later version).

Account sync Gmail:
 ***** Processing account Gmail
 Copying folder structure from IMAP to Maildir
 Establishing connection to imap.gmail.com:993.
Folder sync [Gmail]:
 Syncing INBOX: IMAP -> Maildir
 Syncing [Gmail]/All Mail: IMAP -> Maildir
 Syncing [Gmail]/Drafts: IMAP -> Maildir
 Syncing [Gmail]/Sent Mail: IMAP -> Maildir
 Syncing [Gmail]/Spam: IMAP -> Maildir
 Syncing [Gmail]/Starred: IMAP -> Maildir
 Syncing [Gmail]/Trash: IMAP -> Maildir
Account sync Gmail:
 ***** Finished processing account Gmail
@end verbatim

We can now run @command{mu} to make sure things work:

@verbatim
$ mu index
mu: indexing messages under /home/foo/Maildir [/home/foo/.mu/xapian]
| processing mail; processed: 520; updated/new: 520, cleaned-up: 0
mu: elapsed: 3 second(s), ~ 173 msg/s
mu: cleaning up messages [/home/foo/.mu/xapian]
/ processing mail; processed: 520; updated/new: 0, cleaned-up: 0
mu: elapsed: 0 second(s)
@end verbatim

We can run both the @t{offlineimap} and the @t{mu index} from within
@t{mu4e}, but running it from the command line makes it a bit easier to
troubleshoot as we are setting things up.

Note: when using encryption, you probably do @emph{not} want to
synchronize your Drafts-folder, since it contains the unencrypted
messages. You can use OfflineIMAP's @t{folderfilter} for that.

@subsection Settings

Next step: let's make a @t{mu4e} configuration for this:

@lisp
(require 'mu4e)

;; default
;; (setq mu4e-maildir "~/Maildir")

(setq mu4e-drafts-folder "/[Gmail].Drafts")
(setq mu4e-sent-folder   "/[Gmail].Sent Mail")
(setq mu4e-trash-folder  "/[Gmail].Trash")

;; don't save message to Sent Messages, Gmail/IMAP takes care of this
(setq mu4e-sent-messages-behavior 'delete)

;; (See the documentation for `mu4e-sent-messages-behavior' if you have
;; additional non-Gmail addresses and want assign them different
;; behavior.)

;; setup some handy shortcuts
;; you can quickly switch to your Inbox -- press ``ji''
;; then, when you want archive some messages, move them to
;; the 'All Mail' folder by pressing ``ma''.

(setq mu4e-maildir-shortcuts
    '( ("/INBOX"               . ?i)
       ("/[Gmail].Sent Mail"   . ?s)
       ("/[Gmail].Trash"       . ?t)
       ("/[Gmail].All Mail"    . ?a)))

;; allow for updating mail using 'U' in the main view:
(setq mu4e-get-mail-command "offlineimap")

;; something about ourselves
(setq
   user-mail-address "USERNAME@@gmail.com"
   user-full-name  "Foo X. Bar"
   mu4e-compose-signature
    (concat
      "Foo X. Bar\n"
      "http://www.example.com\n"))

;; sending mail -- replace USERNAME with your gmail username
;; also, make sure the gnutls command line utils are installed
;; package 'gnutls-bin' in Debian/Ubuntu

(require 'smtpmail)
(setq message-send-mail-function 'smtpmail-send-it
   starttls-use-gnutls t
   smtpmail-starttls-credentials '(("smtp.gmail.com" 587 nil nil))
   smtpmail-auth-credentials
     '(("smtp.gmail.com" 587 "USERNAME@@gmail.com" nil))
   smtpmail-default-smtp-server "smtp.gmail.com"
   smtpmail-smtp-server "smtp.gmail.com"
   smtpmail-smtp-service 587)

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

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

And that's it -- put the above in your @file{~/.emacs}, change @t{USERNAME}
etc. to your own, and restart @command{emacs}, and run @kbd{M-x mu4e}.

@node Some other useful settings
@section Some other useful settings

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

@lisp
;; use 'fancy' non-ascii characters in various places in mu4e
(setq mu4e-use-fancy-chars t)

;; save attachment to my desktop (this can also be a function)
(setq mu4e-attachment-dir "~/Desktop")

;; attempt to show images when viewing messages
(setq mu4e-view-show-images t)
@end lisp

@node FAQ
@appendix FAQ - Frequently Asked Questions

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

@menu
* General::
* Reading messages::
* Writing messages::
* Known issues::
@end menu

@node General
@section General

@enumerate
@item @emph{How can I quickly delete/move/trash a lot of messages?} You can
select ('mark' in @command{emacs}-speak) the messages like you would select
text in a buffer; the actions you then take (e.g., @key{DEL} for delete,
@key{m} for move and @key{t} for trash) apply to all selected messages. You
can also use functions like @code{mu4e-headers-mark-thread} (@key{T}),
@code{mu4e-headers-mark-subthread} (@key{t}) to mark whole threads at the same
time, and @code{mu4e-headers-mark-pattern} (@key{%}) to mark all messages
matching a certain regular expression.
@item @emph{@t{mu4e} seems to return a subset of all matches - how can I get
all?} For speed reasons, @t{mu4e} returns only up to the value of the variable
@code{m4ue-search-result-limit} (default: 500) matches. To show @emph{all},
use @kbd{M-x mu4e-headers-toggle-full-search} (@key{Q}), or customize the
variable @code{mu4e-headers-full-search}. This applies to all search commands.
@item @emph{How can I get notifications when receiving mail?} There is
@code{mu4e-index-updated-hook}, which gets triggered when the indexing process
triggered sees an update (not just new mail though). To use this hook, put
something like the following in your setup (assuming you have @t{aplay} and
some soundfile, change as needed):
@lisp
(add-hook 'mu4e-index-updated-hook
  (defun new-mail-sound ()
    (shell-command "aplay ~/Sounds/boing.wav&")))
@end lisp
@item @emph{It seems my headers-buffer is automatically updated when new
  messages are found during the indexing process -- can I disable this
  somehow?} Yes - set @code{mu4e-headers-auto-update} to @code{nil}.
@item @emph{I don't use @t{offlineimap}, @t{fetchmail} etc., I get my mail
through my own mailserver. What should I use for
@code{mu4e-get-mail-command}}? Use @t{"true"} (or don't do anything, it's the
default). This makes getting mail a no-op, but the messages are still
re-indexed.
@item @emph{How can I re-index my messages without getting new mail?}
Use @kbd{M-x mu4e-update-index}
@item @emph{When I try to run @t{mu index} while @t{mu4e} is running I get
errors like:}
@verbatim
mu: mu_store_new_writable: xapian error
  'Unable to get write lock on ~/.mu/xapian: already locked
@end verbatim
@emph{What to do about this?}  You get this error because the underlying
Xapian database is locked by some other process; it can be opened only once in
read-write mode. There is not much @t{mu4e} can do about this, but if is
another @command{mu} instance that is holding the lock, you can ask it to
(gracefully) terminate:
@verbatim
   pkill -2 -u $UID mu # send SIGINT
   sleep 1
   mu index
@end verbatim
@t{mu4e} automatically restarts @t{mu} when it needs it. In practice, this
seems to work quite well.
@item @emph{I don't like the @t{Indexing...} messages that the indexing process
gives me. Can I turn them off?}. Yes: set the variable
@code{mu4e-hide-index-messages} to non-@t{nil}.
@item @emph{Can I automatically apply the marks on messages when
leaving the headers buffer?} Yes you can -- see the documentation for the
variable @t{mu4e-headers-leave-behavior}.
@item @emph{Is there context-sensitive help available?} Yes - pressing @key{H}
should take you to the right place in this manual.
@item @emph{How can I set @t{mu4e} as the default e-mail client in @command{emacs}?}
See @ref{Setting the default emacs mail program}.
@item @emph{Can @t{mu4e} use some fancy Unicode characters instead of these
boring plain-ASCII ones?} Glad you asked! Yes, if you set
@code{mu4e-use-fancy-chars} to @t{t}, @t{mu4e} uses such fancy characters in a
number of places.
@item @emph{Can I start @t{mu4e} in the background?} Yes - if you provide a
prefix-argument (@key{C-u}), @t{mu4e} starts, but does not show the
main-window.
@item @emph{Some IMAP-synchronization programs such as @t{mbsync} (but not
@t{offlineimap}) don't like it when message files do not change their names
when they are moved to different folders. Can @t{mu4e} somehow accommodate
this?} Yes - you can set the variable @code{mu4e-change-filenames-when-moving}
to non-nil.
@item @emph{@command{offlineimap} uses IMAP's UTF-7 for encoding
non-ascii folder names, while @t{mu} expects UTF-8 (so, e.g. @t{/まりもえ
お}@footnote{some Japanese characters, invisible in the UTF-8 version of this
manual} becomes @t{/&MH4wijCCMEgwSg-}). How can display such folders
correctly?} This is best solved by telling @command{offlineimap} to use UTF-8
instead -- see
@url{https://github.com/djcb/mu/issues/68#issuecomment-8598652}.
@item @emph{How can I customize the function to select a folder?} 
The @t{mu4e-completing-read} variable can be customized to select a
folder in any way. The variable can be set to a function that receives
five arguments, following @t{completing-read}. The default value is
@t{ido-completing-read}; to use emacs's default behaviour, set the
variable to @t{completing-read}. Helm users can use the same value, and
by enabling @t{helm-mode} use helm-style completion.
@end enumerate

@node Reading messages
@section Reading messages

@enumerate
@item @emph{How can I view attached images in my message view buffers?} See
@ref{Viewing images inline}.
@item @emph{How can I word-wrap long lines in when viewing a
message?} You can toggle between wrapped and non-wrapped states using
@key{w}. If you want to do this automatically, invoke @code{visual-line-mode} in
your @code{mu4e-view-mode-hook}.
@item @emph{What about hiding cited parts?} Toggle between hiding and showing
of cited parts with @key{h}. If you want to hide parts automatically, call
@code{mu4e-view-toggle-hide-cited} in your @code{mu4e-view-mode-hook}.
@item @emph{How can I perform custom actions on messages and attachments?} See
@ref{Actions}.
@item @emph{Does @t{mu4e} support crypto (i.e., decrypting messages and
verifying signatures)?}  Yes -- if @t{mu} was built with @t{GMime} 2.6 or
later, it is possible to do both (note, only PGP/MIME is supported). In the
@ref{Main view} the support is indicated by a big letter @t{C} on the right
hand side of the @t{mu4e} version. See @ref{Decryption} and @ref{Verifying
signatures}. For encryption and signing messages, see the @ref{Writing
messages}.
@item @emph{Does @t{mu4e} support including all related messages in a thread,
like Gmail does?} Yes -- see @ref{Including related messages}.
@item @emph{There seem to be a lot of duplicate messages -- how can I get rid
of them?} See @ref{Skipping duplicates}.
@item @emph{How can I use the @t{eww} browser to view rich-text messages?} See @ref{Html2text functions}.
@item @emph{Some messages are almost unreadable in emacs - can I view them in
an external web browser?} Indeed, airlines often send messages that
heavily depend on html and are hard to digest inside emacs. Fortunately,
there's an @emph{action} (@ref{Adding an action in the message view})
defined for this. Simply add to your configuration:
@lisp
(add-to-list 'mu4e-view-actions
  '("ViewInBrowser" . mu4e-action-view-in-browser) t)
@end lisp
Now, when viewing such a difficult message, type @kbd{aV}, and the message
opens inside a webbrowser. You can influence the browser with
@code{browse-url-generic-program}.
@item @emph{How can read encrypted messages that I sent?}. Since you do not own the 
recipient's key you typically cannot read those mails - so the trick is
to encrypt outgoing mails with your key, too. This can be automated by
adding the following snippet to your configuration (courtesy of user
@t{kpachnis}):
@lisp
(require 'epg-config)
(setq mml2015-use 'epg
      epg-user-id "gpg_key_id"
      mml2015-encrypt-to-self t
      mml2015-sign-with-sender t)
@end lisp
@end enumerate

@node Writing messages
@section Writing messages

@enumerate
@item @emph{What's the deal with replies to messages I wrote myself?} Like
many other mail-clients, @t{mu4e} treats replies to messages you wrote
yourself as special -- these message keep the same @t{To:} and @t{Cc:}
as the original message. This is to ease the common case of following up
to a message you wrote earlier.
@item @emph{How can I automatically set the @t{From:}-address for a
reply-message, based on some field in the original?} See @ref{Compose hooks}.
@item @emph{And what about customizable folders for draft messages, sent
messages, trashed messages, based on e.g. the @t{From:} header?} See
@ref{Dynamic folders}.
@item @emph{Can I define aliases for (groups of) e-mail addresses?} Sure - 
see @ref{(emacs) Mail Aliases}.
@item @emph{How can I automatically add some header to an outgoing message?}
Once more, see @ref{Compose hooks}.
@item @emph{How can I influence the way the original message looks when
replying or forwarding?} Since @code{mu4e-compose-mode} derives from
@code{message-mode}, you can re-use many of its facilities.
@inforef{Insertion Variables,,message}.
@item @emph{How can I easily include attachments in the messages I write?}
You can drag-and-drop from your desktop; alternatively, you can use @t{dired}
-- see @ref{Attaching files with dired}.
@item @emph{@t{mu4e} seems to remove myself from the @t{Cc:}-list; how can I
prevent that?}  Set @code{mu4e-compose-keep-self-cc} to @t{t} in your
configuration.
@item @emph{How can I sign or encrypt messages?} You can do so using @command{emacs}'
MIME-support -- check the @t{Attachments}-menu while composing a message. Also
see @ref{Signing and encrypting}.
@item @emph{Can I use @t{BBDB} with @t{mu4e}?} Yes, with the current
(2015-06-23) development release of BBDB
@url{http://savannah.nongnu.org/projects/bbdb/}, or releases of BBDB
after 3.1.2.
@ref{Maintaining an address-book with BBDB}.
@item @emph{After sending some messages, it seems the buffer for these
messages stay around. How can I get rid of those?}
@lisp
(setq message-kill-buffer-on-exit t)
@end lisp
@item @emph{Sending big messages is slow and blocks emacs - what can I do
about it?} For this, there's @url{https://github.com/jwiegley/emacs-async}
(also available from the Emacs package repository); add the following snippet
to your configuration:
@lisp
(require 'smtpmail-async)
(setq
  send-mail-function 'async-smtpmail-send-it
  message-send-mail-function 'async-smtpmail-send-it)
@end lisp
With this, messages are sent using 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, that is, message are not sent but there is no indication of that.

You can check the progress of the background by checking the
@t{*Messages*}-buffer, which should show something like:
@verbatim
Delivering message to "William Shakespeare" <will@example.com>...
Mark set
Saving file /home/djcb/Maildir/sent/cur/20130706-044350-darklady:2,S...
Wrote /home/djcb/Maildir/sent/cur/20130706-044350-darklady:2,S
Sending...done
@end verbatim
The first and final messages are the most important, and there may be
considerable time between them, depending on the size of the message.
@item @emph{Is it possible to compose messages in a separate frame?} 
Yes - set the variable @code{mu4e-compose-in-new-frame} to @code{t}.
@item @emph{How can I apply format=flowed to my outgoing messages, enabling
receiving clients that support this feature to reflow my paragraphs?}
Plain text emails with @t{Content-Type: text/plain; format=flowed} can
be reflowed (i.e. line endings removed, paragraphs refilled) by
receiving clients that support this standard. Clients that don't support
this, show them as is, which means this feature is truly non-invasive.

Here's an explanatory blog post which also shows why this is a desirable
feature: @url{https://mathiasbynens.be/notes/gmail-plain-text} (if you
don't have it, your mails mostly look quite bad especially on mobile
devices) and here's the RFC with all the details:
@url{http://www.ietf.org/rfc/rfc2646.txt}.

To add this to outgoing mu4e emails, activate @t{use-hard-newlines} and
use only @t{M-q} or @t{fill-paragraph} for your paragraphs, Emacs will
indicate intra-paragraph breaks with soft newlines and inter-paragraph
breaks with hard newlines. When the Gnus code sees these on outgoing
emails, it will automatically set @t{format=flowed}.

To enable this, you can use something like this in your init.el:

@lisp
;; tip submitted by mu4e user cpbotha
(add-hook 'mu4e-compose-mode-hook
          (defun cpb-compose-setup ()
            "Outgoing mails get format=flowed."
            (use-hard-newlines t 'guess)))
@end lisp
@end enumerate

@node Known issues
@section Known issues

Although they are not really @emph{questions}, we end this chapter with a list
of known issues and/or missing features in @t{mu4e}. Thus, users won't have to
search in vain for things that are not there (yet), and the author can use it
as a todo-list.

@itemize
@item @emph{mu4e does not work well if the @command{emacs} language environment is not
UTF-8}; so, if you encounter problems with encodings, be sure to have
@code{(set-language-environment "UTF-8")} in your @file{~/.emacs}.
@item @emph{Thread handling is incomplete.} While threads are calculated and are
visible in the headers buffer, you cannot collapse/open them.
@item @emph{The key-bindings are @emph{somewhat} hard-coded.} That is, the main
menu assumes the default key-bindings, as do the clicks-on-bookmarks.
@item @emph{The @t{emacs} front-end of the @t{notmuch} e-mail indexer
conflicts with @t{mu4e}}. @t{notmuch} running in parallel with
@t{mu4e} leads to
@verbatim
error in process filter: mu4e-error-handler: Error 70: cannot read
~/Maildir/...
@end verbatim
when sending a reply to some e-mail. This seems to be caused by
@t{notmuch} changing the name of the original message file while
@t{mu4e} is working on it. To prevent this, deactivate @t{notmuch} in
your Emacs setup.
@item @emph{The PDF-version of the manual does not show any of the non-ASCII
characters} - this is because the @t{texi2pdf} documentation system does
not support those. There is not much we can do about that.
@end itemize

For a more complete list, please refer to the issues-list in the
github-repository.


@node Tips and Tricks
@appendix Tips and Tricks

@menu
* Multiple accounts::
* Refiling messages::
* Saving outgoing messages::
* Fancy characters and Inconsolata::
* Confirmation before sending::
@end menu

@node Multiple accounts
@section Multiple accounts

Using mu4e with multiple email accounts is fairly easy. Although
variables such as @code{user-mail-address}, @code{mu4e-sent-folder},
@code{message-*}, @code{smtpmail-*}, etc. typically only take one value,
it is easy to change their values using @code{mu4e-compose-pre-hook}.
The setup described here is one way of doing this (though certainly not
the only way).

This setup assumes that you have multiple mail accounts under
@code{mu4e-maildir}. As an example, we'll use @t{~/Maildir/Account1}
and @t{~/Maildir/Account2}, but the setup works just as well if
@code{mu4e-maildir} points to something else.

First, you need to make sure that all variables that you wish to change
based on user account are set to some initial value. So set up your
environment with e.g., your main account:

@lisp
(setq mu4e-sent-folder "/Account1/Saved Items"
      mu4e-drafts-folder "/Account1/Drafts"
      user-mail-address "my.address@@account1.tld"
      smtpmail-default-smtp-server "smtp.account1.tld"
      smtpmail-local-domain "account1.tld"
      smtpmail-smtp-server "smtp.account1.tld"
      smtpmail-stream-type starttls
      smtpmail-smtp-service 25)
@end lisp

Then create a variable @code{my-mu4e-account-alist}, which should
contain a list for each of your accounts. Each list should start with
the account name, (which @emph{must} be identical to the account's
directory name under @t{~/Maildir}), followed by @code{(variable
value)} pairs:

@lisp
(defvar my-mu4e-account-alist
  '(("Account1"
     (mu4e-sent-folder "/Account1/Saved Items")
     (mu4e-drafts-folder "/Account1/Drafts")
     (user-mail-address "my.address@@account1.tld")
     (smtpmail-default-smtp-server "smtp.account1.tld")
     (smtpmail-local-domain "account1.tld")
     (smtpmail-smtp-user "username1")
     (smtpmail-smtp-server "smtp.account1.tld")
     (smtpmail-stream-type starttls)
     (smtpmail-smtp-service 25))
    ("Account2"
     (mu4e-sent-folder "/Account2/Saved Items")
     (mu4e-drafts-folder "/Account2/Drafts")
     (user-mail-address "my.address@@account2.tld")
     (smtpmail-default-smtp-server "smtp.account2.tld")
     (smtpmail-local-domain "account2.tld")
     (smtpmail-smtp-user "username2")
     (smtpmail-smtp-server "smtp.account2.tld")
     (smtpmail-stream-type starttls)
     (smtpmail-smtp-service 587))))
@end lisp

You can put any variable you want in the account lists, just make sure
that you put in @emph{all} the variables that differ for each account.
Variables that do not differ need not be included. For example, if you
use the same smtp server for both accounts, you don't need to include
the smtp-related variables in @code{my-mu4e-account-alist}.

Note that some SMTP servers (such as Gmail) require the SMTP username to
match the user mail address. In this case your mail will appear to
originate from whichever SMTP account you use. Thus unless you are
certain your SMTP server does not have this requirement, you should
generally use different SMTP account credentials for each mail account.

Now, the following function can be used to select an account and set the
variables in @code{my-mu4e-account-alist} to the correct values:

@lisp
(defun my-mu4e-set-account ()
  "Set the account for composing a message."
  (let* ((account
          (if mu4e-compose-parent-message
              (let ((maildir (mu4e-message-field mu4e-compose-parent-message :maildir)))
                (string-match "/\\(.*?\\)/" maildir)
                (match-string 1 maildir))
            (completing-read (format "Compose with account: (%s) "
                                     (mapconcat #'(lambda (var) (car var))
                                                my-mu4e-account-alist "/"))
                             (mapcar #'(lambda (var) (car var)) my-mu4e-account-alist)
                             nil t nil nil (caar my-mu4e-account-alist))))
         (account-vars (cdr (assoc account my-mu4e-account-alist))))
    (if account-vars
        (mapc #'(lambda (var)
                  (set (car var) (cadr var)))
              account-vars)
      (error "No email account found"))))
@end lisp

This function then needs to be added to @code{mu4e-compose-pre-hook}:

@lisp
(add-hook 'mu4e-compose-pre-hook 'my-mu4e-set-account)
@end lisp

This way, @code{my-mu4e-set-account} will be called every time you edit
a message. If you compose a new message, it simply asks you for the
account you wish to send the message from (TAB completion works). If
you're replying or forwarding a message, or editing an existing draft,
the account is chosen automatically, based on the first component of the
maildir of the message being replied to, forwarded or edited (i.e., the
directory under @t{~/Maildir}).

@node Refiling messages
@section Refiling messages

By setting @code{mu4e-refile-folder} to a function, you can dynamically
determine where messages are to be refiled. If you want to do this based
on the subject of a message, you can use a function that matches the
subject against a list of regexes in the following way. First, set up a
variable @code{my-mu4e-subject-alist} containing regexes plus associated
mail folders:

@lisp
(defvar my-mu4e-subject-alist '(("kolloqui\\(um\\|a\\)" . "/Kolloquium")
                                ("Calls" . "/Calls")
                                ("Lehr" . "/Lehre")
                                ("webseite\\|homepage\\|website" . "/Webseite"))
  "List of subjects and their respective refile folders.")
@end lisp

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

@lisp
(defun my-mu4e-refile-folder-function (msg)
  "Set the refile folder for MSG."
  (let ((subject (mu4e-message-field msg :subject))
        (folder (or (cdar (member* subject my-mu4e-subject-alist
                                   :test #'(lambda (x y)
                                             (string-match (car y) x))))
                    "/General")))
    folder))
@end lisp

Note the @t{"/General"} folder: it is the default folder in case the
subject does not match any of the regexes in
@code{my-mu4e-subject-alist}.

In order to make this work, you'll of course need to set
@code{mu4e-refile-folder} to this function:

@lisp
(setq mu4e-refile-folder 'my-mu4e-refile-folder-function)
@end lisp

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

@lisp
(defun my-mu4e-refile-folder-function (msg)
  "Set the refile folder for MSG."
  (let ((maildir (mu4e-message-field msg :maildir))
        (subject (mu4e-message-field msg :subject))
        folder)
    (cond
     ((string-match "Account1" maildir)
      (setq folder (or (catch 'found
                         (dolist (mailing-list my-mu4e-mailing-lists)
                           (if (mu4e-message-contact-field-matches
                             msg :to (car mailing-list))
                               (throw 'found (cdr mailing-list)))))
                       "/Account1/General")))
     ((string-match "Gmail" maildir)
      (setq folder "/Gmail/All Mail"))
     ((string-match "Account2" maildir)
      (setq folder (or (cdar (member* subject my-mu4e-subject-alist
                                      :test #'(lambda (x y)
                                                (string-match
                                                   (car y) x))))
                       "/Account2/General"))))
    folder))
@end lisp

This function actually uses different methods to determine the refile
folder, depending on the account: For @emph{Account2}, it uses
@code{my-mu4e-subject-alist}, for the @emph{Gmail} account it simply uses the
folder "All Mail". For Account1, it uses another method: it files the
message based on the mailing list to which it was sent. This requires
another variable:

@lisp
(defvar my-mu4e-mailing-lists
  '(("mu-discuss@@googlegroups.com" . "/Account1/mu4e")
    ("pandoc-discuss@@googlegroups.com" . "/Account1/Pandoc")
    ("auctex@@gnu.org" . "/Account1/AUCTeX"))
  "List of mailing list addresses and folders where
   their messages are saved.")
@end lisp

@node Saving outgoing messages
@section Saving outgoing messages

Like @code{mu4e-refile-folder}, the variable @code{mu4e-sent-folder} can also
be set to a function, in order to dynamically determine the save folder. One
might, for example, wish to automatically put messages going to mailing lists
into the trash (because you'll receive them back from the list anyway). If you
have set up the variable @code{my-mu4e-mailing-lists} as mentioned, you can
use the following function to determine a save folder:

@lisp
(defun my-mu4e-sent-folder-function (msg)
  "Set the sent folder for the current message."
  (let ((from-address (message-field-value "From"))
        (to-address (message-field-value "To")))
    (cond
     ((string-match "my.address@@account1.tld" from-address)
      (if (member* to-address my-mu4e-mailing-lists
                   :test #'(lambda (x y)
                             (string-match (car y) x)))
          "/Trash"
        "/Account1/Sent"))
     ((string-match "my.address@@gmail.com" from-address)
      "/Gmail/Sent Mail")
     (t (mu4e-ask-maildir-check-exists "Save message to maildir: ")))))
@end lisp

Note that this function doesn't use @code{(mu4e-message-field msg
:maildir)} to determine which account the message is being sent from.
The reason is that that the function in @code{mu4e-sent-folder} is
called when you send the message, but before mu4e has created the
message struct from the compose buffer, so that
@code{mu4e-message-field} cannot be used. Instead, the function uses
@code{message-field-value}, which extracts the values of the headers in
the compose buffer. This means that it is not possible to extract the
account name from the message's maildir, so instead the from address is
used to determine the account.

Again, the function shows three different possibilities: for the first
account (@t{my.address@@account1.tld}) it uses
@code{my-mu4e-mailing-lists} again to determine if the message goes to a
mailing list. If so, the message is put in the trash folder, if not, it
is saved in @t{/Account1/Sent}. For the second (Gmail) account, sent
mail is simply saved in the Sent Mail folder.

If the from address is not associated with Account1 or with the Gmail
account, the function uses @code{mu4e-ask-maildir-check-exists} to ask
the user for a maildir to save the message in.

@node Fancy characters and Inconsolata
@section Fancy characters and Inconsolata

When using 'fancy characters' (@code{mu4e-use-fancy-chars}) with the
@emph{Inconsolata}-font (and likely others as well), the display may be
slightly off; the reason for this issue is that Inconsolata does not
contain the glyphs for the 'fancy' arrows and the glyphs that are used
as replacements are too high.

To fix this, you can use something like the following workaround (in your
@t{.emacs}-file):
@lisp
(if (equal window-system 'x)
    (progn
      (set-fontset-font "fontset-default" 'unicode "Dejavu Sans Mono")
      (set-face-font 'default "Inconsolata-10")))
@end lisp

@node Confirmation before sending
@section Confirmation before sending

To protect yourself from sending messages too hastily, you can add a
final confirmation, which you can of course make as elaborate as you
wish.

@lisp
(add-hook 'message-send-hook
  (lambda ()
    (unless (yes-or-no-p "Sure you want to send this?")
      (signal 'quit nil))))
@end lisp

@node How it works
@appendix How it works

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

@menu
* High-level overview::
* mu server::
* Reading from the server::
* The message s-expression::
@end menu

@node High-level overview
@section High-level overview

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

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

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

@node mu server
@section @t{mu server}

@t{mu4e} is based on the @t{mu} e-mail searching/indexer. The latter is a
C-program; there are different ways to communicate with a client that is
emacs-based.

One way to implement this, would be to call the @t{mu} command-line tool with
some parameters and then parse the output. In fact, that was the first
approach -- @t{mu4e} would invoke e.g., @t{mu find} and process the output in
@command{emacs}.

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

@node Reading from the server
@section Reading from the server

In the design, the next question was what format @t{mu} should use for its
output for @t{mu4e} (@command{emacs}) to process. Some other programs use
@abbr{JSON} here, but it seemed easier (and possibly, more efficient) just to
talk to @command{emacs} in its native language: @emph{s-expressions}, and
interpret those using the @command{emacs}-function
@code{read-from-string}. See @ref{The message s-expression} for details on the
format.

So, now let's look how we process the data from @t{mu server} in
@command{emacs}. We'll leave out a lot of detail, @t{mu4e}-specifics, and look
at a bit more generic approach.

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

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

Note, the process sentinel is invoked when the process is terminated -- so
there you can clean things up. The function @code{my-process-filter} is a
user-defined function that takes the process and the chunk of output as
arguments; in @t{mu4e} it looks something like (pseudo-lisp):

@lisp
(defun my-process-filter (proc str)
  ;; mu4e-buf: a global string variable to which data gets appended
  ;; as we receive it
  (setq mu4e-buf (concat mu4e-buf str))
  (when <we-have-received-a-full-expression>
      <eat-expression-from mu4e-buf>
      <evaluate-expression>))
@end lisp

@code{<evaluate-expression>} de-multiplexes the s-expression we got. For
example, if the s-expression looks like an e-mail message header, it is
processed by the header-handling function, which appends it to the header
list. If the s-expression looks like an error message, it is reported to the
user. And so on.

The language between frontend and backend is documented in the @t{mu-server}
man-page. @t{mu4e} can log these communications; you can use @kbd{M-x
mu4e-toggle-logging} to turn logging on and off, and you can view the log
using @kbd{M-x mu4e-show-log} (@key{$}).

@node The message s-expression
@section The message s-expression

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

@lisp
(:docid 32461
 :from (("Nikola Tesla" . "niko@@example.com"))
 :to (("Thomas Edison" . "tom@@example.com"))
 :cc (("Rupert The Monkey" . "rupert@@example.com"))
 :subject "RE: what about the 50K?"
 :date (20369 17624 0)
 :size 4337
 :message-id "C8233AB82D81EE81AF0114E4E74@@123213.mail.example.com"
 :path  "/home/tom/Maildir/INBOX/cur/133443243973_1.10027.atlas:2,S"
 :maildir "/INBOX"
 :priority normal
 :flags (seen)
 :parts ( (:index 1 :mime-type "text/plain" :size 12345 :attachment nil)
          (:index 2 :name "photo.jpg" :mime-type "image/jpeg"
           :size 147331 :attachment t)
          (:index 3 :name "book.pdf" :mime-type "application/pdf"
           :size 192220 :attachment t))
 :references  ("C8384574032D81EE81AF0114E4E74@@123213.mail.example.com"
 "38203498230942D81EE81AF0114E4E74@@123213.mail.example.com")
 :in-reply-to "38203498230942D81EE81AF0114E4E74@@123213.mail.example.com"
 :body-txt "Hi Tom,
 ....
")
@end lisp

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

Some notes on the format:
@itemize
@item The address fields are @emph{lists} of pairs @code{(name . email)},
where @t{name} can be nil.
@item The date is in format @command{emacs} uses (for example in
@code{current-time}).@footnote{Emacs 32-bit integers have only 29 bits
available for the actual number; the other bits are use by @command{emacs} for
internal purposes. Therefore, we need to split @t{time_t} in two numbers.}
@item Attachments are a list of elements with fields @t{:index} (the number of
the MIME-part), @t{:name} (the file name, if any), @t{:mime-type} (the
MIME-type, if any) and @t{:size} (the size in bytes, if any).
@item Messages in the @ref{Headers view} come from the database and do not have
@t{:attachments}. @t{:body-txt} or @t{:body-html} fields. Message in the
@ref{Message view} use the actual message file, and do include these fields.
@end itemize

@subsection Example: ping-pong

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

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

@verbatim
-> cmd:ping
<- (pong "mu" :version "x.x.x" :doccount 10000)
@end verbatim

When we receive such a @t{pong} (in @file{mu4e-proc.el}), the lambda function
we registered is called, and it compares the version we got from the @t{pong}
with the version we expected, and raises an error, if they differ.

@node Logging and debugging
@appendix Logging and debugging

As explained in @ref{How it works}, @t{mu4e} communicates with its backend
(@t{mu server}) by sending commands and receiving responses (s-expressions).

For debugging purposes, it can be very useful to see this data. For this
reason, @t{mu4e} can log all these messages. Note that the 'protocol' is
documented to some extent in the @t{mu-server} manpage.

You can enable (and disable) logging with @kbd{M-x mu4e-toggle-logging}. The
log-buffer is called @t{*mu4e-log*}, and in the @ref{Main view}, @ref{Headers
view} and @ref{Message view}, there's a keybinding @key{$} that takes you
there. You can quit it by pressing @key{q}.

Logging can be a bit resource-intensive, so you may not want to leave it on
all the time. By default, the log only maintains the most recent 1200
lines. @t{mu} itself keeps a log as well, you can find this it in
@t{<MUHOME>/log/mu.log}, typically @t{~/.mu/log/mu.log}.

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

@include fdl.texi

@bye