mu/emacs/mu4e.texi

\input texinfo.tex    @c -*-texinfo-*-
@c %**start of header
@setfilename mu4e.info
@settitle mu4e user manual
@documentencoding utf-8
@c %**end of header
@include version.texi

@titlepage
@title @t{mu4e} - an e-mail client for emacs
@author{Dirk-Jan C. Binnema}
@end titlepage


@dircategory Emacs
@direntry
* mu4e: (mu4e).        An email client for emacs based on mu.
@end direntry
@copying
Copyright @copyright{} 2012 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

@node Top
@top mu4e Manual

Welcome to @t{mu4e}!

@t{mu4e} (mu-for-emacs) is an e-mail client for GNU-Emacs version 23 and
later. It is built on top of the @t{mu} e-mail search engine, and it focuses
on quickly dealing with large amounts of e-mail.

This manual goes through the installation of @t{mu4e}, discusses the basic
configuration, and explains its daily use. It also shows how you can customize
@t{mu4e} for your needs.

At the end of the manual, there are a number of example configurations, which
should help you to get up to speed quickly.

This manual has been updated for @t{mu}/@t{mu4e} version
@emph{@value{mu4e-version}}.

@menu
* Introduction::
* Getting started::
* Running mu4e::
* Searching::
* Actions::
* Interaction with other tools::
* Example configuration::
* FAQ - Frequently Anticipated Questions::
* Known issues / missing features::

Appendices
* How it works:: Some notes about the implementation of 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

Let's get started!

@menu
* Why another e-mail client?::
* Other mail clients::
* What mu4e does and does not do::
@end menu

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

Why does the world need another e-mail client?  Well, I'm not sure the world
@emph{needs} another one, but maybe @emph{I} do! I spend a @emph{lot} of time,
professionally and privately, dealing with e-mail and therefore, having an
efficient e-mail client is essential for me. Since none of the existing ones
worked the way I wanted, I created my own.

Even while having been created for such selfish motives, @t{mu4e} tries hard
to be as useful as possible for all its users - suggestions are very welcome
and are acted upon.

@node Other mail clients
@section Other mail clients

Under the hood, @t{mu4e} is fully search-based, similar to programs such as
@t{notmuch}@footnote{@url{http://notmuchmail.org}},
@t{md}@footnote{@url{https://github.com/nicferrier/md}} and
@t{sup}@footnote{@url{http://sup.rubyforge.org/}}. @t{mu4e}'s user-interface
is quite different from those programs though.

@t{mu4e}'s mail handling (deleting, moving etc.) is inspired by
@emph{Wanderlust}@footnote{@url{http://www.gohome.org/wl/}} (another
emacs-based e-mail client), @t{mutt}@footnote{@url{http://www.mutt.org/}} and
@t{dired}, while it takes some cues from @emph{GMail}.

@t{mu4e} tries to keep all the 'state' in your maildirs, so you can easily
switch between clients, synchronize over @abbr{IMAP} or backup with @t{rsync}
-- if you delete the database, you won't lose any information, and there is no
@emph{lock-in}.

@node What mu4e does and does not do
@section What mu4e does and does not do

@t{mu} and @t{mu4e} do @emph{not} deal with getting 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}@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.

@t{mu4e} also does @emph{not} implement sending of messages; instead, it
depends on the tried-and-tested @inforef{Top,smtpmail,smtpmail}, which is part
of @t{emacs}. In addition, @t{mu4e} piggybacks on Gnus' message editor;
@inforef{Top,Gnus message editor,message}.

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


@node Getting started
@chapter Getting started

In this chapter, we go through the installation of @t{mu4e} and show how you
can set it up. After we have succeeded in @ref{Getting mail}, and
@ref{Indexing your messages}, we discuss @ref{Basic configuration}.

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

@menu
* Installation::
* Getting mail::
* Indexing your messages::
* Basic configuration::
* Folders::
* Sending mail::

@end menu

@node Installation
@section Installation

@t{mu4e} is part of @t{mu} - by installing the latter, the former will
be installed as well.

At the time of writing, there are no distribution packages for @t{mu4e} yet,
so we are assuming installation from source packages.

First, you need make sure you have the necessary dependencies. On a Debian or
Ubuntu system, you can get these with:

@example
sudo apt-get install libgmime-2.4-dev libxapian-dev
# emacs if you don't have it yet, mu4e works with GNU-Emacs 23 and 24
sudo apt-get install emacs23
# optional
sudo apt-get install guile-2.0-dev html2text xdg-utils
@end example

Installation follows the normal sequence of:

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

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.}, and be available from the command line and emacs
(respectively).

You may need to restart @t{emacs}.

@subsection mu4e and emacs customization

There is @emph{experimental} support for using the @t{emacs} customization
system in @t{mu4e}, but for now we recommend setting the values
manually. Please refer to @ref{Example configuration} for a couple of examples
of this.

@node Getting mail
@section Getting mail

In order for @t{mu} (and, by extension, @t{mu4e}) to work, we need to have our
e-mail messages stored in a Maildir. If you were already using Maildirs, you
are lucky; otherwise, you will need to get your mail there in some way.

If you are using some external @abbr{IMAP} or @abbr{POP} server, you can use
tools like @t{getmail}, @t{fetchmail} @t{offlineimap} or @t{isync} to download
your message into a maildir-directory (@file{~/Maildir}, usually). If you are
using a local mail-server (such as @emph{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; also there is full example of setting @t{mu4e} up with
@t{offlineimap} and Gmail; @pxref{Gmail configuration}.

You can do all of the mail retrieval @emph{outside} of @t{emacs}/@t{mu4e}, but
you can also do it from within @t{mu4e}. For that, set the variable
@code{mu4e-get-mail-command} to the program or shell command you want to use
for retrieving mail. You can then retrieve your e-mail from the @ref{Main
view}.

You can also have this command run 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 will not update at all. If you make
changes to @code{mu4e-update-interval}, @code{mu4e} must be restarted before
the change will take effect.

@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 Maildir and store the information
about the mails into a special database. We can do that from @code{mu4e} --
@ref{Main view}, but the first time, it is better to run it from the command
line, as it is easier to recognize any problems that might occur.

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

This should scan your @file{~/Maildir}@footnote{In most cases, you do not even
have to provide the @t{--maildir=~/Maildir}; 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 it only has to scan
the differences. Indexing is discussed in more 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 should list all messages that match @t{hello}. For more examples of
searches @xref{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 up @t{mu4e}; the
next step is to do some basic configuration.

@node Basic configuration
@section Basic configuration

The first thing we need to do before we can start using @t{mu4e} is to tell
@t{emacs} to load @t{mu4e}, and tell @t{mu4e} where it can find specific
maildir folders.

So, add to your @file{~/.emacs} (or equivalent) something like:

@example
(require 'mu4e)
@end example

@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:
@lisp
  (setq
    mu4e-maildir       "~/Maildir"   ;; top-level Maildir
    mu4e-sent-folder   "/sent"       ;; where do i keep sent mail?
    mu4e-drafts-folder "/drafts"     ;; where do i keep half-written mail?
    mu4e-trash-folder  "/trash")     ;; where do i move deleted mail?
@end lisp

@code{mu4e-maildir} take an actual filesystem-path, the other folder names are
all relative to @code{mu4e-maildir}. The next step is telling @t{mu4e} how we
want to send mail.

@node Sending mail
@section Sending mail

@t{mu4e} re-uses Gnu's @inforef{Top,,message}, for writing mail and inherits
the setup for @emph{sending} mail from that.

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

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

A very minimal setup could look something like:

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

By default, @t{mu4e} puts a copy of any messages you sent in the folder you
set for @code{mu4e-sent-folder}. In some case, this may not be what you want -
for example, when using GMail+@abbr{IMAP} (but @emph{not} with
GMail+@abbr{POP3}), this interferes with GMail's handling of the sent messages
folder, and you may end up with duplicate messages.

Since @t{mu4e} 0.9.8.3, there is the variable
@code{mu4e-sent-messages-behavior} for, which takes a symbol. The default is
@code{'sent} which, as mentioned, causes the message to be copied to your
sent-messages folder. Other possible values are @code{'trash} (so the sent
message is copied to the trash-folder (@code{mu4e-trash-folder}), and
@code{'delete} to simply discard the message altogether.

For GMail-IMAP you could add the following to your settings:

@verbatim
;; don't save message to Sent Messages, GMail/IMAP will take care of this
(setq mu4e-sent-messages-behavior 'trash)
@end verbatim

And that's it! We should be ready to go now.


@node Running mu4e
@chapter Running mu4e

After the following the steps in @ref{Getting started}, we should now have a
working @t{mu4e} setup. In this chapter, we'll give a tour of the @t{mu4e}
program, and show its use.

@t{mu4e} consists of a number of views; the diagram shows how they relate to
each other, and the default key-bindings to get from one view to the next. In
the next sections we will describe what these keys actually @emph{do}.

@menu
* Main view::
* Headers view::
* Message view::
* Editor view::
@end menu


@example
----------------------------------------------------------------------------

        [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: bookmark-search (edit-first)

----------------------------------------------------------------------------
@end example

@node Main view
@section Main view

After you have installed @t{mu4e} (@pxref{Getting started}), you can start it
with @code{M-x mu4e}. This will do some checks to ensure everything is set up
correctly, and then show the @t{mu4e} main view.

This looks something like the following:

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

  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

        * [H]elp
	* [q]uit mu4e
----------------------------------------------------------------------------
@end verbatim

In the below, we assume the default key bindings here. If you've changed
those, well, mutatis mutandis.

@subsection Basic actions

First, the @emph{Basics}:
@itemize
@item @t{[j]ump to some maildir} means that after pressing @key{j},
@t{mu4e} will ask you for a maildir to jump to. These are the maildirs you
set in @ref{Basic configuration}.
@item @t{enter a [s]earch query} means that after pressing @key{s} you will
be asked for a search query, and after entering one, the results will be
shown. @xref{Searching}.
@item @t{[C]ompose a new message} means that after pressing @key{C}, you
will be thrown in a message-editing buffer, where you can compose a new message.
@end itemize

@subsection Bookmarks

Next come the @emph{Bookmarks}.These are set with the variable
@code{mu4e-bookmarks}; what you see in the above example are the
@emph{default} bookmarks - you can add your own and/or replace the default
ones. @xref{Bookmarks}. In short, you can view the list of messages matching a
bookmark by pressing @key{b} followed by the shortcut for this bookmark. If
you'd like to edit the bookmarked query first, use @key{B}.

@subsection Miscellaneous

Finally, there are some @emph{Misc} actions:
@itemize
@item @t{[U]pdate email & database} will execute whatever is in
the variable @code{mu4e-get-mail-command}, and afterwards update the @t{mu}
database; @pxref{Indexing your messages}. See @ref{Getting mail} for details.
@item @t{toggle [m]ail sending mode (direct)} will toggle between sending
mail directly, and queuing it first (for example, when you are offline), and
@t{[f]lush queued mail} will flush any queued mail. This item is visible only
if you have actually set up mail-queuing. @ref{Queuing mail}.
@item @t{[H]elp} will show help information for this view.
@item Finally, @t{[q]uit mu4e} will quit @t{mu4e}.
@end itemize

@node Headers view
@section Headers view

The headers view shows the results of search queries. There is a line for each
matching message, each showing a number of fields describing the corresponding
message.

This looks something like the following:

@verbatim
----------------------------------------------------------------------------------
  Date              Flgs   From/To             Subject
  2011-12-16 18:38  uN     To Edmund Dantès    + Re: Extension security?
  2011-12-16 21:44  uN     Abbé Busoni             + Re: Extension security?
  2011-12-17 03:14  uN     Pierre Morrel           + Re: Extension security?
  2011-12-17 04:04  uN     Jacopo                    + Re: Extension security?
  2011-12-17 14:36  uN     Mercédès                    + Re: Extension security?
  2011-12-18 06:05  uN     Beachamp                      \ Re: Extension security?
  2011-12-16 18:23  uN     Albert de Moncerf   + Re: [O] A presentation tool
  2011-12-17 01:53  usaN   Gaspard Caderousse    \ Re: [O] A presentation tool
  2011-12-16 16:31  uN     Baron Danglars      | [O] imaxima?
End of search results
----------------------------------------------------------------------------------
@end verbatim

@subsection Some notes

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 @t{mu4e-headers-fields}
@item You can change the date format by customizing
@t{mu4e-headers-date-format}
@item The letters in the 'Flags' field correspond to the following: D=draft,
F=flagged, N=new, P=passed (i.e.., forwarded), R=replied, S=seen, T=trashed,
a=has-attachment, x=encrypted, s=signed, u=unread.
@item The From/To field shows the sender of the message unless the sender
matches the regular expression in @t{mu4e-user-mail-address-regexp}, in
which the header will show @t{To} followed by the recipient.
@item The subject field displays the discussion threads according to the @emph{JWZ mail
threading algorithm}@footnote{@url{http://www.jwz.org/doc/threading.html}}.
@end itemize

@subsection Keybindings

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

@verbatim
key          description
---          -----------
n,p          go to next, previous message
y            select the message view (if it's visible)
j            jump to maildir
b,B          jump to bookmark (/ edit first)
a            execute some action on header

d            mark for moving to the trash folder
DEL,D        mark for immediate deletion
m            mark for moving to another maildir folder
u            unmark message at point
%            mark based on a regular expression
T,t          mark whole thread, subthread

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

|            pipe message through shell command

d            mark for moving to the trash folder
DEL,D        mark for immediate deletion
m            mark for moving to another maildir folder
o            mark message as unread
r            mark message as read
u            unmark message at point
U            unmark *all* messages
x            execute actions for the marked messages
RET          open the message at point in the message view

H            get help
q,z          leave the headers buffer
@end verbatim

@subsection Marking messages
@anchor{Marking messages}

The mark/unmark commands support the current @emph{region} (i.e., selection)
-- so, for example, if you the select a number of message and then press
@key{DEL}, all selected message will be marked for deletion.

The two-step mark-execute sequence is similar to what @t{dired} and a number
of other emacs-based programs do. @t{mu4e} tries to be as quick as possible
while still trying to protect you from accidents.

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

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


@subsection Actions

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

@t{mu4e} defines some default actions - one is @t{capture} - @key{a c} will
'capture' the current message. Next, when you're editing some message, you can
include the previously captured message as an attachment, using
@code{mu4e-insert-captured-message-as-attachment}.

@subsection Split view

Using the @emph{Split view} means viewing the @ref{Headers view} and the
@ref{Message view} next to each other, with the message that is selected in
the former, visible in the latter.

Earlier versions of @t{mu4e} only showed one of the views at a time, but split
view has become the default after version 0.8.9.3.

You can influence the way the splitting works by setting the variable
@code{mu4e-split-view} in your configuration to one of 3 values:
@itemize
@item @t{horizontal} (this is the default): display the message view below the
header view
@item @t{vertical}: display the message view on the
right side of the header view
@item anything else: don't do any splitting
@end itemize

When splitting horizontally, you can determine the number of visible header
lines with with the variable @t{mu4e-headers-visible-lines} (default value:
8). When split vertically you can use @t{mu4e-headers-visible-columns}
(default value: 30) to set the number of visible columns.

When the message view window is selected, you cannot use the arrow keys for
moving to the next / previous message (like you can in the headers view),
since those are already assigned to cursor movement in the message.  However,
instead can use the @key{p} (or @key{M-up}) and @key{n} (or @key{M-down}) keys
for moving to the previous and the next message, respectively. These keys also
work in the headers view.

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

@node Message view
@section Message view

After selecting a message in the @ref{Headers view}, it will be shown in the
message view, for example:

@verbatim
----------------------------------------------------------------------------
From: info@galatians.net
To: "Paul" paul@hotmail.com
Subject: Re: some thoughts
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 Paul,

How are you? Sorry we didn't get back to you sooner and sorry for the
top-quoting. We're still debating your last message; anyway, here are some
recent pics. And here's a link: http://example.com[1]

All the best!

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

[....]
----------------------------------------------------------------------------
@end verbatim

Some notes:
@itemize
@item You can determine which header fields are shown by setting the
variable @code{mu4e-view-fields}.
@item You can customize the date format by setting the variable
@code{mu4e-date-format-long}, using the same format that
@code{format-time-string} uses.
@item If you only want to see the name and not the e-mail address of the
contacts in address fields, you can set @option{mu4e-view-show-addresses} to
@t{nil}. This will hide the addresses for contacts that also have a name. The
e-mail address is still available as a tool-tip.
@item The body text can be line-wrapped (toggle between wrapped/not-wrapped with
@key{w}) and/or cited parts can be hidden (toggle between hidden/not-hidden
with @key{h}. If you want to do this by default when viewing messages, you can
set, respectively, @code{mu4e-view-wrap-lines} and @code{mu4e-view-hide-cited}
to @code{t}. @footnote{If you have installed the @t{filladapt} package
(@url{http://www.wonderworks.com/download/filladapt.el}), @t{mu4e} will use it
for line-wrapping, as it generally does a better job than the default
mechanism emacs provides.}

@end itemize

@subsection 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          go to next, previous message
y            select the headers view (if it's visible)

j            jump to maildir
b,B          jump to bookmark (/ edit first)

a            execute some action on the message

d            mark for moving to the trash folder
DEL,D        mark for immediate deletion
m            mark for moving to another maildir folder
u            unmark message at point
%            mark based on a regular expression
T,t          mark whole thread, subthread

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

.            show the raw message view. 'q' takes you back.

g            go to (visit) numbered URL (using `browse-url')
             (or: <mouse-2> or RET with point on url)
e            extract (save) attachment (asks for number)
             (or: <mouse-2> or RET with point on attachment)
o            open attachment (asks for number)
             (or: <S-mouse-2> or S-RET with point on attachment)
A            execute some action on an attachment
w            toggle line wrapping
h            toggle showing cited parts

H            get help
q,z          leave the message view
@end verbatim

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

@subsection Opening and saving attachments

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

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

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

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

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

By default, @t{mu4e} already offers a few useful actions for attachments:

@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, @t{A w 1 RET gimp RET} will open that attachment in 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: @t{A | 1 RET diffstat -b RET}.
@item @t{emacs} (@key{e}): open the attachment in your running @t{emacs}
. For example, if you receive some text file you'd like to open in @t{emacs}:
@t{A e 1 RET}.
@end itemize

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

For more information about actions and how to define your own, see
@ref{Actions}.

@subsection Displaying rich-text messages

For displaying messages, @t{mu4e} normally prefers the plain-text version for
messages consisting of both a plain-text and an html (rich-text) version of
its body-text. 

If there is only an html-version, or if the plain-text version is too short in
comparison with the html part, @t{mu4e} tries to convert the html into
plain-text for display. The default way to do that is to use the Emacs
built-in @code{html2text} function, but if you set the variable
@code{mu4e-html2text-command} to some external program, that program will be
used. This program is expected to take html from standard input and write
plain text in @t{utf-8} encoding on standard output.

An obvious choice for this is the program that is actually @emph{called}
@t{html2text}@footnote{@url{http://www.mbayer.de/html2text/}}, which you could
set up with something like the following in your initialization files:

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

An alternative to this is to use 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

As mentioned, by default @t{mu4e} prefers the text-version of an e-mail
message over the html version. You can change this by setting
@code{mu4e-view-prefer-html} to @t{t}.

@node Editor view
@section Editor view

For its editor, @t{mu4e} re-uses Gnu's @t{message-mode}. For example, when
replying to a message, the editor view looks something like the following:

@verbatim
----------------------------------------------------------------------------
From: Rupert the Monkey <rupert@example.com>
Reply-To: rupert@example.com
To: Wally the Walrus <wally@example.com>
In-reply-to: <201201160918.47080.ssdfz@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

Since @t{mu4e} uses @t{gnu}'s message editor, for documentation
@inforef{Message}. Also, @pxref{Sending mail}. There are many key-bindings
available, here are some of the essential ones (you can use the menu to find
more):

@subsection Some useful keybindings

@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-w      insert signature
C-c C-a      attach a file (pro-tip: drag & drop works as well)
@end verbatim

If you want use @t{mu4e} as the default program for sending mail, please see
@ref{Setting the default emacs mail program}. With respect to sending mail,
other interesting topics: @ref{Citations with mu-cite} and @ref{Maintaining an
address-book with org-contacts}.


@subsection Queuing mail
@anchor{Queuing mail}

If you cannot send mail directly, 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 @t{mu4e} @ref{Main
view}.

To allow for queuing, you need to tell @t{smtpmail} where you want to do
this. For example:

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

For convenience, we locate 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 will not reach
their destination until you switch it off again; so, be careful not to do this
accidentally.


@node Searching
@chapter Searching

@t{mu4e} is fully search-based; this means that all the lists of messages you
see, are the result of some query. Even if you 'jump to a folder', in fact you
are executing a search query for messages that happen to have the property of
being in a certain folder.

Queries normally return only up to @code{mu4e-search-results-limit} (which
defaults to 1000) results. You get @emph{all} results when you prefix your
search commands (such as with @code{mu4e-search}, @code{mu4e-search-bookmark},
@code{mu4e-search-bookmark-edit-first} and @code{mu4e-jump-to-maildir} with
@kbd{C-u}.

This limit was introduced in earlier versions of @t{mu4e}, where @t{emacs}
could become slow when there were many matches. This is no longer the case
(post @t{mu4e} version 0.9.8.3), but since it is still faster to limit the
number of matches, the limit remains.

@menu
* Queries::
* Bookmarks::
* Maildir searches::
@end menu

@node Queries
@section Queries

The queries you can execute are the same ones that @code{mu find}
understands. Please refer to the @code{mu-find} and @code{mu-easy} man pages
for details and more examples.

@verbatim
# get all messages about bananas
bananas

# get all messages about bananas from john with an attachment
from:john flag:attach bananas

# get all messages with subject wombat in June 2009
subject:wombat date:20090601..20090630

# get all messages with PDF attachments in the /projects folder
maildir:/projects mime:application/pdf

# get all important messages which are signed:
flag:signed prio:high

# get all messages from Jim without an attachment:
from:jim AND NOT flag:attach

# get all unread messages where the subject mentions Ångström:
subject:angstrom flag:unread

# get all unread messages between Mar-2002 and Aug-2003 about some bird
date:20020301..20030831 nightingale flag:unread

# get today's messages
date:today..now

# get all messages we got in the last two weeks regarding emacs
date:2w..now emacs

# get mails with a subject soccer, Socrates, society...
# note: the '*' wildcard can only appear as the rightmost character in the term
subject:soc*

# get all mails with attachment with filenames starting with 'pic'
# note: the '*' wildcard can only appear as the rightmost character in the term
file:pic*

# get all messages with PDF attachments:
mime:application/pdf

# get all messages with image attachments:
# note: the '*' wildcard can only appear as the rightmost character in the term
mime:image/*
@end verbatim

@node Bookmarks
@section Bookmarks

If you have queries that you use often, you may want to store them as
@emph{bookmarks}. These bookmarks then show up in the main view, and you can
invoke them in other places as well. 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}
(@code{mu4e-search-bookmark}).

@subsection Setting up bookmarks

@code{mu4e} provides some default bookmarks, which you can override. The
definition of the default bookmarks is instructive here:

@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 will 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 will
show up in the UI), and KEY is a shortcut key for the query.")
@end lisp

You can replaces 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} will list 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 @key{bb}.

@subsection Editing bookmarks before searching

There is also @code{mu4e-search-bookmark-edit-first} (key @key{B}), which lets
you edit the search query with some bookmark already filled in. This can be
useful if you have many similar queries, but need to change some
parameter. For example, you could have a bookmark @t{"NOT maildir:/Trash
AND"}@footnote{Not a valid search query by itself} and add whatever you want
to search for to that. Or, to do a query limited to the messages of today, all
you need to type is @key{Bt} (using the @t{Today's messages}-bookmark, see
above).

@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 do Maildir searches manually (e.g. with a query like
@code{maildir:/myfolder}) but since it is so common, @t{mu4e} offers a quicker
way to do this.

To enable this, you need to set the variable @t{mu4e-maildir-shortcuts} to
list of maildirs you'd like 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 would set @key{i} as a shortcut for the @t{/inbox} folder; so effectively
a query @t{maildir:/inbox}. There is a special shortcut @key{o} for
@emph{other} (so don't use that one for your own shortcuts!), which allows you
to choose from @emph{all} maildirs.

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

Having these shortcuts allows you to jump around your folder very quickly -
for example, getting to the @t{/lists} folder only requires you to type
@key{jl}.

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


@node Actions
@chapter Actions

@t{mu4e} allows you to 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{a} for actions on messages, and @key{A}
for actions on attachments. In the following, we'll gives some examples of
defining actions.

@subsection Functions for actions

Defining a new custom action means that you need to write an elisp-function to
do the work. Functions that operate on messages look like:
@lisp
(defun my-action-func (msg)
 "Describe my func."
;; do stuff
)
@end lisp

Messages that operate on attachments look like:
@lisp
(defun my-attachment-action-func (msg attachment-num)
 "Describe my func."
;; do stuff
)
@end lisp

After you have defined your function, you can add it to the list of actions,
either @code{mu4e-headers-actions}, @code{mu4e-view-actions} or
@code{mu4e-view-attachment-actions}.

Let's now look at some simple examples.

@subsection Example: adding an action in the headers view

Suppose we would like to inspect the number of recipients for a message in the
@ref{Headers view}.  We could define the following function in our configuration:

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

(add-to-list 'mu4e-headers-actions
   '("Number of recipients" ?n show-number-of-recipients) t)
@end lisp

After activating this, @key{a n} in the headers view will show the number of
recipients for the message at point.

@subsection Example: adding an action in the message view

As another example, suppose we would like to search for messages by the sender
of this message.
@lisp
(defun search-for-sender (msg)
  "Search for messages sent by the sender of the current one."
  (mu4e-search (concat "from:" (cdar (mu4e-msg-field msg :from)))))

(add-to-list 'mu4e-view-actions
   '("search for sender" ?s search-for-sender) t)
@end lisp

@subsection Example: adding an attachment action

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

The following will count the number of lines in an attachment.

@lisp
(defun count-lines-in-attachment (msg attachnum)
  "Count the number of lines in an attachment."
  (mu4e-view-pipe-attachment msg attachnum "wc -l"))
(add-to-list 'mu4e-view-attachment-actions
   '("count lines" ?n count-lines-in-attachment) t)
@end lisp

@subsection What functions are available?

@t{elisp} does not have a module-system, so it can be hard to see what
functions are internal, and which are usable for others as well.

To help a bit with this, all functions and variables in @t{mu4e} marked for
@emph{internal} use have the prefix @t{mu4e~}, while all the public ones use
@t{mu4e-}. The @t{~} was chosen because its ascii-code is after all the
letters, so they will only appear at the end of completion buffers and the
like.

Functions that start with @t{mu4e-view-} and @t{mu4e-hdrs-} should be called
only with that particular context (the message view and the headers view,
respectively).


@node Interaction with other tools
@chapter 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::
* Maintaining an address-book with org-contacts::
* Getting new mail notifications with Sauron::
* Speedbar support::
* Citations with mu-cite::
@end menu

@node Setting the default emacs mail program
@section Setting the default emacs mail program

@t{emacs} allows you to select an e-mail program as the default program it
will use 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

At the present time, support is still experimental.

@node Creating org-mode links
@section Creating 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

After this, you can use the normal @t{org-mode} mechanisms to store links:
@t{M-x org-store-link} will store a link to a particular message when you're
in @ref{Message view}, and a link to a query when you are in @ref{Headers
view}.

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

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

To manage your addresses using @t{org-mode}, there is
@t{org-contacts}@footnote{@url{http://julien.danjou.info/software/org-contacts.el}}.

@t{mu4e-actions} defines a useful action (@ref{Actions}) for this to add a
contact based on the @t{From:}-address in the current mail (current header or
view). 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" ?o mu4e-action-add-org-contact) t)
(add-to-list 'mu4e-view-actions
  '("org-contact-add" ?o mu4e-action-add-org-contact) t)
@end lisp

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.

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

The emacs-package 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 put something like the below script in your @t{crontab} (or have some
other way of having it execute every @emph{n} minutes, you will receive
notifications in the sauron-buffer when new messages arrive.

@verbatim
#!/bin/sh
# 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"        \
            "/org/gnu/Emacs/Sauron"                \
            "org.gnu.Emacs.Sauron.AddMsgEvent"      \
            string:shell uint32:3 string:"$1"
    fi
}

for f in `find $CHECKDIR -mmin -2 -a -type f`; do
        subject=`$MU view $f | grep '^Subject:' | sed 's/^Subject://'`
        sauron-msg "mail: $subject"
done
@end verbatim

Note, you should put something like:
@lisp
(setq sauron-dbus-cookie t)
@end lisp
in your setup, which allows the script to find the D-Bus session bus.

@node Speedbar support
@section Speedbar support

@code{speedbar} is an emacs-extension that shows navigational information for
an 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 @code{M-x speedbar}. Then, when then going to the @ref{Main view}, the
speedbar-frame will be updated with your bookmarks and maildirs.

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

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

Note, apart from its name @t{mu-cite} is a project totally unconnected to
@t{mu}/@t{mu4e}.

@t{mu-cite} 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 installation of the @t{mu-cite}, you can use something like the
following to make it work with @t{mu4e}:

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


@node Example configuration
@chapter Example configuration

In this chapter, we show some example configurations.

@menu
* Minimal configuration::
* Longer configuration::
* Gmail configuration::
@end menu


@node Minimal configuration
@section Minimal configuration

An (almost) minimal configuration for @t{mu4e} might look something like this:

@lisp
;; example configuration for mu-for-emacs (mu4e)
(require 'mu4e)

;; happily, below settings are all /optional/

;; Only needed if your maildir is _not_ ~/Maildir
;;(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 will offer to
;; create them
;; (setq mu4e-sent-folder   "/sent")
;; (setq mu4e-drafts-folder "/drafts")
;; (setq mu4e-trash-folder  "/trash")

;; for the settings for outgoing mail consult the section 'Longer configuration'
@end lisp


@node Longer configuration
@section Longer configuration

@lisp
;; example configuration for mu-for-emacs (mu4e)
(require 'mu4e)

(setq
   ;; a regular expression that matches all email address uses by the user;
   ;; this allows us to correctly determine if user is the sender of some message
   mu4e-user-mail-address-regexp
      "foo@@bar\.com\\|cuux@@example\.com"

   ;; path to our Maildir directory
   mu4e-maildir       "/home/user/Maildir"
   ;; the next are relative to `mu4e-maildir'
   mu4e-sent-folder   "/sent"
   mu4e-drafts-folder "/drafts"
   mu4e-trash-folder  "/trash"

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

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

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

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

   ;; general emacs mail settings; used when composing e-mail
   mu4e-reply-to-address "foo@@bar.com"
   user-mail-address "foo@@bar.com"
   user-full-name  "Foo X. Bar"

   ;; include in message with C-c C-w
   message-signature
    (concat
      "Foo X. Bar\n"
      "http://www.example.com\n")

   ;; smtp mail setting
   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")
@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}.

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

Then, we need to create a configuration for @t{offlineimap}, i.e. a file
@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 @t{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

Note that 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 see
what is going on.

Now, let's make a @t{mu4e} configuration for this:

@lisp
(require 'mu4e)

;; default
;; (setq mu4e-maildir (expand-file-name "~/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 will take care of this
(setq mu4e-sent-messages-behavior 'delete)

;; setup some handy shortcuts
(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"
   message-signature
    (concat
      "Foo X. Bar\n"
      "http://www.example.com\n"))

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

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

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

Using these settings, you can quickly switch to your Inbox -- press
@kbd{ji}. Then, when you want archive some messages, move them to the 'All
Mail' folder by pressing @kbd{ma}.


@node FAQ - Frequently Anticipated Questions
@chapter FAQ - Frequently Anticipated Questions

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

@itemize
@item @emph{How can I quickly delete/move/trash a lot of messages?} You can
select ('mark' in emacs-speak) the messages; the actions you then take (e.g.,
@key{DEL} for delete, @key{m} for move and @key{t} for trash) will apply to
@emph{all} selected messages. You can also use functions like
@code{mu4e-hdrs-mark-thread} (@key{T}), @code{mu4e-hdrs-mark-subthread}
(@key{t}) to mark whole threads at the same time, and
@code{mu4e-hdrs-mark-matches} (@key{%}) to mark all messages matching a
certain regular expression.
@item @emph{How can I use @t{BBDB}?} Currently, there is no built-in for
address management with @t{BBDB}; instead, we recommend @ref{Maintaining an
address-book with org-contacts} for now.
@item @emph{mu4e only seems to return a subset of all matches - how can I get
all?}. Yes, for speed reasons (and because, if you are like the author, you
usually don't need thousands of matches), @t{mu4e} returns only up to the
value of the variable @code{m4ue-search-result-limit} matches. You can
customize that variable, or simply press the emacs prefix @kbd{C-u} before your
search command to get all matches. In other words, when you press @t{C-u s
hello} you will get all matches, while @t{s hello} only gets you
up-to-a-limited-number matches. Same for the other search based commands,
@code{mu4e-jump-to-maildir} (default: @key{j}) and @code{mu4e-search-bookmark}
(default: @key{b}).
@item @emph{How can I easily include attachments in the messages I write?}
Drag-and-drop.
@item @emph{When I try do run @t{mu index} while @t{mu4e} is running I get
errors like @t{mu: mu_store_new_writable: xapian error 'Unable to get write
lock on ~/.mu/xapian: already locked'}. What can I do about this?} You get
this error because the underlying Xapian database allows itself to be opened
in read-write mode only once. There is not much @t{mu4e} can do about this,
but what you can do is telling @t{mu} to (gracefully) terminate:
@verbatim
   pkill -2 -u $UID mu # send SIGINT
   sleep 1
   mu index
@end verbatim
@t{mu4e} will automatically restart @t{mu} when it needs it. In practice, this
seems to work quite well.
@item @emph{Can I automatically execute the actions on marked messages when
leaving the headers buffer?} Yes you can -- see the documentation on
@t{mu4e-headers-leave-behavior}.
@item @emph{Can I automatically apply word-wrapping (and hiding cited parts)
when viewing a message?} Yes -- see the documentation on
@t{mu4e-view-wrap-lines} (and @t{mu4e-view-hide-cited}). You can always toggle
between the two states with @key{w} and @key{h}, respectively.
@item @emph{Is there context-sensitive help available?} Yes - pressing @key{H}
in most cases should point you to the right spot in this manual.
@item @emph{How can I set @t{mu4e} as the default e-mail client in emacs?}
See @ref{Setting the default emacs mail program}.
@item @emph{How can I perform custom actions on messages and attachments?} See
@ref{Actions}.
@end itemize

@node Known issues / missing features
@chapter Known issues / missing features

In this chapter we list a number of known issue 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{Thread handling is incomplete.} While threads are calculated and are
visible in the headers buffer, you can now collapse/open them.
@item @emph{No support for crypto when reading mail}. Currently, you cannot
conveniently read encrypted mail or check signatures. For outgoing messages,
it should work though, using the built-in mechanisms.
@item @emph{One cannot influence the sorting of messages}. Messages are sorted
according to thread, then descending by date. It would be nice if it could be
sorted in other ways as well.
@item @emph{@t{mu4e} gets confused when there are multiple windows showing the
headers.}. Yes -- don't do that.
@item @emph{Messages in the sent-folder do not include the attachments you
sent.} Same for the drafts-folder.
@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.
@end itemize


@node How it works
@appendix How it works

While not necessarily interesting for all users of @t{mu4e}, for some it may
be interesting to know how @t{mu4e} does its job.

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

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

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

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

In words:
@itemize

 @item Your e-mail messages are stored in a Maildir-directory (typically,
 @file{~/Maildir}), and new mail comes in using tools like @t{fetchmail},
 @t{offlineimap}, or through a local mail servers (such as @t{qmail} or
 Postfix).

 @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 @t{emacs} is such a client; it communicates
 with @t{mu} (in its @t{server}-mode to search for messages, and manipulate
 them.

 @item @t{mu4e} uses the facilities offered by @t{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 is how some tools do
it, and it was the first approach -- @t{mu4e} would invoke e.g., @t{mu find}
and process the output in emacs.

However, with 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}, you get a
sort-of shell, in which you can give commands to @t{mu}, which will then spit
out the results/errors. @t{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} (@t{emacs}) to process. Some other programs use
@abbr{JSON} here, but it seemed easier (and possibly, more efficient) just to
talk to @t{emacs} in its native language: @emph{s-expressions} (to be precise:
@emph{plists}), and interpret those using the @t{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 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 will
be 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 =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 will be
processed by the header-handling function, which will append it to the header
list. If the s-expression looks like an error message, it will be 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 @code{M-x
mu4e-toggle-logging} to turn logging on and off, and you can view the log
using @code{M-x mu4e-show-log}.

@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 "6BDC23465F79238C8233AB82D81EE81AF0114E4E74@@123213.mail.example.com"
 :path  "/home/tom/Maildir/INBOX/cur/133443243973_1.10027.atlas:2,S"
 :maildir "/INBOX"
 :priority normal
 :flags (seen)
 :attachments ((:index 2 :name "photo.jpg" :mime-type "image/jpeg" :size 147331)
               (:index 3 :name "book.pdf" :mime-type "application/pdf" :size 192220))
 :references  ("6BDC23465F79238C8384574032D81EE81AF0114E4E74@@123213.mail.example.com"
 "6BDC23465F79238203498230942D81EE81AF0114E4E74@@123213.mail.example.com")
 :in-reply-to "6BDC23465F79238203498230942D81EE81AF0114E4E74@@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-msg-field} to shield you from some of the implementation details
that are subject to change.

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 emacs uses (for example in
@code{current-time}).@footnote{Emacs 32-bit integers have only 29 bits
available for the actual number; the other bits are use by emacs for internal
purposes. Therefore, we need to split @t{time_t} in two numbers.}
@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 this, let's look at the @t{ping-pong}-sequence. When @t{mu4e}
starts, it sends a command @t{ping} to the 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 call @t{mu4e-proc-ping}, and registers a (lambda) function for
@t{mu4e-proc-pong-func}, so it will retrieve the response.

@verbatim
-> 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 will be called, and it check 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 @t{M-x mu4e-toggle-logging}. The
log-buffer is called @t{*mu4e-log-buffer*}, and in the @ref{Main view},
@ref{Headers view} and @t{Message view}, there's a keybinding @key{$} that
will take 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.

Note, @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