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

@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} (@emph{mu-for-emacs}) is an @t{emacs}-based e-mail client, based on
the @t{mu} e-mail search engine. @t{mu4e} supports GNU Emacs 23 and later. It
assumes a Unix-like system and mail stored in a maildir; it has been tested on
Debian GNU/Linux.

@menu
* Introduction::
* Getting started::
* Running mu4e::
* Searching mail::
* Org-mode support::
* Example configuration::
* FAQ - Frequently Anticipated Questions::
* Known issues / missing features::

Appendices
* How it works:: Some notes about the implementation of 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 and doesn't do::
@end menu

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

Why would the world need another e-mail client?  Well, I'm not sure the world
needs another one, but maybe @emph{I} do; I spend a @emph{lot} of time, both
professionally and privately, dealing with e-mail -- so having an efficient
e-mail client is essential for me.

A secondary goal for me was to write some bigger program in Emacs Lisp
(@t{elisp}), to better understand the language and its idioms.

@node Other mail clients
@section Other mail clients

@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/}}. The way this is presented
to the user is quite a bit different 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} with respect to being
search-based.

@t{mu4e} tries to keep all the 'state' in the maildirs, so I can switch
between clients, synchronize over @abbr{IMAP} or backup with @t{rsync} -- if
you delete the database, you don't lose any information.

@node What mu4e does and doesn't do
@section What mu4e does and doesn't do

@t{mu}, and, by extension, @t{mu4e}, do @emph{not} deal with getting your
e-mail messages from a mail server; instead, this 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}/@t{mu} are happy to deal with them.

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

Thus, many of the traditional things an e-mail client needs to do are
subcontracted to other tools. This leaves @t{mu4e} to concentrate on what it
does best: quick message searching, reading mails, replying them, moving
messages around and so on.

@node Getting started
@chapter Getting started

In this chapter, we see how you can install @t{mu4e} and how to set it
up. After we have succeeded in @ref{Getting mail}, and @ref{Indexing your
messages}, we discuss @ref{Basic configuration}. After going through these
steps, @t{mu4e} should be ready for use.

@menu
* Installation::
* Getting mail::
* Indexing your messages::
* Sending mail::
* Queuing mail::
* Basic configuration::
@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
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.}, a be available from the command line and emacs
(respectively). You may need to restart @t{emacs} so it can pick up @t{mu4e}.

There is 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 working example 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 other way.

If you are using some external @abbr{IMAP} or @abbr{POP} server, you can use
tools like @t{getmail}, @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}.

@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 this first time, it's better to run it from the command
line, as it may be easier to recognize problems.

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} and fill the database, and give
progress information while doing so. The first time you index your mail may
take a few minutes (for thousands of e-mails), afterwards it is much faster
since it only has to scan the differences.

Note that indexing is discussed at length in the @t{mu-index} man page.

After the indexing is 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 "hello". The @t{mu-find} man
page describes the various things you can do with @t{mu find}, and the
@t{mu-easy} man page has some examples as well.

If all of this worked well, we are almost ready to start @t{mu4e}; we only
need set up @ref{Sending mail}.

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

For sending mail using @abbr{SMTP}, @t{mu4e} uses Emacs built-in @t{smtpmail}
package -- @inforef{smtpmail}. This package support many different ways to
send mail, please refer to its documentation. Here we provide some simple
examples - and @ref{Example configuration}.

A very minimal setup could look something like:

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

Note, since @t{mu4e} uses the same @t{message mode} and @t{smtpmail}
that Gnus uses, any setting for those will also work for @t{mu4e}.

@node Queuing mail
@section 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} @xref{Main
view}.

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

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

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 can be handy here,
so for example:

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

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.

Also, see the @t{mu-mkdir} and @t{mu-index} man pages.

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


@node Basic configuration
@section Basic configuration

The last thing to do before running @t{mu4e} is setting up some basic
configuration. A good place to put this would be in your @file{~/.emacs} file.
First some more extensive configuration, @xref{Example configuration}.

First, we need to load @t{mu4e}:

@example
(require 'mu4e)
@end example

Then, we need to tell @t{mu4e} where it can find your Maildir, and some
special folders. So, for example:
@example
  (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 example

@code{mu4e-maildir} take an actual filesystem-path, the other folder names are
all relative to @code{mu4e-maildir}.


@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]^                \
   /                |                 \
+-------+ [sjb] +---------+  [RET] +---------+
| main  | <---> | headers | <----> | message |
+-------+  [q]  +---------+ [qbjs] +---------+
                  [sbj]                 ^
                                    [.] | [q]
                                        V
                                      +-----+
                                      | raw |
                                      +-----+

Default bindings
----------------
R: Reply      s: search            .: raw view
F: Forward    j: jump-to-maildir
C: Compose    b: bookmark-search
E: Edit       q: quit
@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
--

We assume the default key bindings here.

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

Next come the @emph{Bookmarks}.These are set in 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}.

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}. This is a synchronous command - you
have to wait for it to finish.
@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. @xref{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              Flags  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     Eric Schulte        + Re: [O] A presentation tool for org-mode
  2011-12-17 01:53  usaN   Gaspard Caderousse    \ Re: [O] A presentation tool for org-mode
  2011-12-16 16:31  uN     Baron Danglars      | [O] imaxima?
End of search results
@end verbatim
--

It should be fairly obvious what this means, but some notes:
@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

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
---          -----------
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
U            unmark *all* messages
x            execute actions for the marked messages
RET          open the message at point in the message view
R,F,C        reply/forward/compose
E            edit (only allowed for draft messages)
H            get help
q            leave the headers buffer
@end verbatim

Note, all 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 for example @t{dired}
does; @inforef{(emacs) Dired} - it tries to be as fast as possible while still
trying to protect the user from accidents.

@node Message view
@section Message view

After selecting a message in the Headers view (see @ref{Headers view}), the
message will be show in the message view.

This might look something like the following:

--
@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 customize which header fields are shown using
@t{mu4e-view-fields}.
@item You can customize the date format by setting
@code{mu4e-date-format-long}, using the format that @code{format-time-string}
uses.
@end itemize

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

@verbatim
key          description
---          -----------
n,p          go to next, previous 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
R,F,C        reply/forward/compose
E            edit (only allowed for draft messages)

.            show the raw message view. '.'/'q' takes you back
|            pipe the message through a shell command

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)
w            toggle line wrapping
h            toggle showing cited parts

H            get help
q            leave the headers buffer
@end verbatim

Note that @key{x}, which means 'execute actions on marked messages' is not
available in this view, to reduce the risk of accidents. You need to go back
to the headers view to effectuate the actions.

Also note that opening of an attachment uses the @t{xdg-open} program to
determine the right program to use for a certain attachment. @t{xdg-open} is
part of the FreeDesktop
@t{xdg-utils}.@footnote{@url{http://portland.freedesktop.org/wiki/}}.

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 plaint-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 will be
used. This program is expected to take html from standard input and write
plain text on standard output. An obvious choice for this is the program that
is actually called
@t{html2text}@footnote{@url{http://www.mbayer.de/html2text/}}.

@node Editor view
@section Editor view

For its editor, @t{mu4e} re-uses Gnu's @t{message-mode}, and all its bells and
whistles are available.

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

Currently, @t{mu4e} uses Gnu's message editor, and so for documentation
@inforef{Message}. Also, @pxref{Sending mail}. There are many key-bindings
available, here are some of the essential ones (and you can use the menu to
find many 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-w      insert signature
C-c C-a      attach a file (pro-tip: drag & drop works as well)
@end verbatim

@node Searching mail
@chapter Searching mail

@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 have the property of being
in a certain folder.

Note, all queries normally return only up to @code{mu4e-search-results-limit}
results; if you need more than that, prefix your search command with
@kbd{C-u}.

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

@node Queries
@section Queries

The queries you can execute are the same that @code{mu find}
understands. Please refer to the @code{mu-find} and @code{mu-easy} man pages
for details. Here, we just provide a few 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 all messages today (well, all messages today in their Date:)
date:today..now

# get all messages we got in the last two weeks about 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. By default, bookmark searches are
available in the main view @ref{Main view}, header view @xref{Headers view},
and message view @xref{Message view}, with the key @key{b} for the function
@code{mu4e-search-bookmark}.

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

@example
(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 example

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

This prepend your bookmark to the list, and assign 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 highlight. So, to invoke your
bookmark (get the list of "Big Messages"), all you need to type is @key{bb}.


@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 main view
@ref{Main view}, header view @ref{Headers view}, and message view
@ref{Message view}, with the key @key{j} for @code{mu4e-jump-to-maildir}.

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:

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

This would set @key{i} as a shortcut for the @t{/inbox} folder; so effectively
a query @t{maildir:/inbox}. There's one 'built-in' shortcut @key{o} for
'other' (so don't use that one for your own shortcuts!), which allows you to
choose from @emph{all} maildirs.

Each of the folder name is relative to your top-level maildir directory; so if
you keep your maildir 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 same shortcuts are used by the function @code{mu4e-mark-for-move}; so for
example, if you want to move a message the @t{/archive} folder, you can mark
it for that using @key{ma}.

@node Org-mode support
@chapter Org-mode support

Many emacs-users use @t{org-mode} for their note-taking, agenda, to-do list
and many other things, and it is very useful to integrate e-mail with this as
well.

@t{mu4e} support @t{org-mode}-links, and the @t{org-mode}-address book,
@t{org-contact}.

@menu
* Org-mode links::
* Org-contacts::
@end menu

@node Org-mode links
@section Org-mode links
When using @t{org-mode}, it can be very useful to include link to
individual e-mail messages or even queries.

@t{mu4e} supports this with the @t{org-mu4e} module; setting it up is easy:

@verbatim
(require 'org-mu4e}
@end verbatim

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 Message view (@ref{Message view}), and a link to a query when your in
Headers view (@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 Org-contacts
@section 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}}.
You can use it with a @t{capture}-template:
@verbatim
("c" "contacts" entry (file "contacts.org")
"* %(mu4e-view-snarf-from 'name)
:PROPERTIES:
:EMAIL %(mu4e-view-snarf-from 'email)
:NICK:
:BIRTHDAY:
:END:\n\n")
@end verbatim

After setting this up, you can use @t{M-x org-capture RET c} to get a template
for a new contact based on the 'From:' address.


@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} could look something like this:

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


@node Longer configuration
@section Longer configuration

@verbatim
;; 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
   mail-reply-to "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 verbatim


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

Of course, you need replace @t{USERNAME} and @t{PASSWORD} with your actual
Gmail username and password.

After this, you can download your mail, it should look something like the
following:
@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:

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

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

   ;; include in message with C-c C-w
   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 verbatim

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 setting 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 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
@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.
@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, there is no functionality to manipulate them
(e.g., collapse the thread, or delete a whole thread at once). But note that
you can manipulate a number of consecutive messages at once by selecting
them, and then using one of the manipulation commands, such as
@code{mu4e-mark-for-move} or @code{mu4e-mark-for-delete}.
@item @emph{No support for crypto when reading mail}. Currently, you cannot
conveniently read encrypted mail or check signatures (it should be possible
with e.g. EPA though, @inforef{Top, EasyPG Assistant, epa}.) 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{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{Difficulties with attachments in messages with complex
MIME-hierarchy.} While dealing with attachments usually works fine, we have
found some problems with specific mails. This is an issue in @t{mu}, and it is
under investigation.
@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::
* 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}.

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 is to create a process with, for example, @code{start-process}, and
then register a filter function for it, which will be invoked whenever the
process has some chunk of output. Something like:

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

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

@verbatim
(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 verbatim

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

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

@include fdl.texi


@bye