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{} 2011 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.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.
@end quotation
@end copying

@node Top
@top mu4e Manual

@emph{Mu-For-Emacs} (or for short, @command{mu4e}), is an @command{emacs} based
e-mail client, based on the @command{mu} e-mail search engine. @command{mu4e}
supports GNU Emacs 23 and later.
 
@menu
* Introduction::
* Getting started::
* Running mu4e::
@c * Getting mail::
@c * Searching mail::
@c * Reading mail::
@c * Processing mail::
@c * Sending mail::
* Example configuration::
@end menu

@node Introduction
@chapter Introduction

@command{mu4e} is an e-mail program for GNU Emacs; it uses the @command{mu}
e-mail search engine as its backend, making @command{mu} fully search-based.

@command{mu4e} (and @command{mu}) does @emph{not} deal with getting your
e-mail messages from some e-mail server; instead, this task is delegated to
other tools, such as @command{offlineimap}. As long as the messages end up in
a Maildir, @command{mu4e}/@command{mu} are happy to deal with them.

@command{mu4e} does @emph{not} implement sending messages either; instead, it
depends on the true-and-tested @emph{smtpmail} which is part of emacs. In
fact, @command{mu4e} piggybacks on @ref{Top, Gnus} for its message editor.

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

It's important to note the @command{mu4e} requires your mail to be in
Maildir-format, typically stored in @file{~/Maildir}.

@c @section Acknowledgments

@command{mu} has been helped tremendously by users who helped to isolate and fix
bugs, and (maybe even more so) by providing suggestions. Thanks to all!

@command{mu4e} has taken inspiration from many places. First, there are @command{sup}
and @command{notmuch} which showed that one can write a search-based e-mail
client. Aspects of the Wanderlust e-mail client can be seen in the UI, as well
as the @command{dired} interaction model. 

@node Getting started
@chapter Getting started

Getting started. 


@c @section Installation

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

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

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, @command{mu} and @command{mu4e} should be
installed @footnote{there's a hard dependency between versions of
@command{mu4e} and @command{mu} - you cannot combine different versions.}, a
be available from the command line and emacs (respectively). For emacs, you
may to restart it so it can pick up @command{mu4e}.

There is experimental support for using the @command{emacs} customization
system in @command{mu4e}, but for now we recommend setting the values by
manually. Please @ref{Example configuration} for a working example of this.

@c @node Getting mail
@c @section Getting mail

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

If you are using some external @acronym{IMAP} or @acronym{POP} server, you can
use tools like @command{getmail} and @command{offlineimap} to download your
message into a Maildir-directory (@file{~/Maildir}, usually). If you are using
a local mailserver (such as Postfix or @command{qmail}), you can teach them to
deliver into a Maildir as well, maybe in combination with @command{qmail}.

For the exact details on how to do this, please consult the documentation of
the products you are using.

@c @node Indexing your messages
@c @section Indexing your messages
@c @ref{Getting mail}
After you have succeeded in Getting mail, we need to @emph{index}
it. 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}, but for now
it's better to do it from the command line, because it's easier to spot any
problems then.

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 might
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 @command{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 @command{mu-find} man
page describes the various things you can do with @command{mu find}.

If all of this worked well, we are almost ready to start @command{mu4e}.


@c @node Basic configuration
@c @section Basic configuration

The last thing to do before running @command{mu4e} is setting up some basic
configuration. A good place to put this would be in your @file{~/.emacs} file.

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

@example
(require 'mu4e)
@end example

Then, we need to tell @command{mu4e} where it can find your Maildir, and some
special folders. So for example:
@example
  (setq
    mu4e-maildir       "~/Maildir"
    mu4e-inbox-folder  "/inbox"      ;; where do i receive mail?
    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
The folder names are all relative to @code{mu4e-maildir}.


Without going into too much technical detail, here we describe the elements in
a @command{mu4e}-setup, and how they work together. Using some ascii-art:

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

So:
@itemize

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

 @item @command{mu} indexes these messages periodically, so you can quickly
 search for them. @command{mu} can run in a special @command{server}-mode, where it
 provides services to client software.

 @item @command{mu4e}, which runs inside @command{emacs} is such a client; it
 communicates with @command{mu} to search for messages, and manipulate them.

 @item @command{mu4e} uses the facilities offered by @command{emacs} (the
 @command{Gnus} message editor and @command{smtpmail}) to send messages.
 
@end itemize


@example
+-----------+       +--------------+        +--------------+
| main view | <---> | headers view |  <---> | message view |
+-----------+       +--------------+        +--------------+
                                                     |
                                             +----------+
                                             | raw view |
                                             +----------+
@end example


@node Running mu4e
@chapter Running mu4e

After you've installed @command{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 @command{mu4e} main view.

@verbatim
* mu4e - mu for emacs version 0.9.8pre

  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

	* [q]uit mm

@end verbatim

First, the @emph{Basics}:
@itemize
@item @code{[j]ump to some maildir} means that after pressing @key{j},
@command{mu4e} will ask you for a maildir to jump to.
@end itemize





@c @node Getting mail
@c @section Getting mail

@command{mu} works with whatever it finds in your Maildir, without caring much
how the mail got there. Typical ways to do so are using @code{fetchmail} or
@code{offlineimap}, but mail servers like @code{qmail} or @code{Postfix} can
deliver mail in a Maildir as well. Please refer to the documentation for these
tools.

@command{mu4e} checks the setting of the @env{MAILDIR} environment variable to
locate the Maildir; if that is not set, if falls back to @code{~/Maildir}. If
you want to use some other directory, you can customize @code{mu4e-mu-home}.

To invoke some mail-getting command from the @command{mu4e} main screen, you can
call @code{mu4e-retrieve-mail-update-db} (by default @kbd{u}); to use it, you
should set @code{mu4e-get-mail-command} to some shell command.

@c @node Searching mail
@c @section Searching mail

@command{mu4e} is full 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.

@c @node Reading mail
@c @section Reading mail

@c @node Processing mail
@c @section Processing mail

@c Processing mail is the act of moving mails around (in folders), viewing them

@c @node Sending mail
@c @section Sending mail


@node Example configuration
@chapter Example configuration

@example
@verbatim
;; example configuration for mu-for-emacs (mu4e)

(require 'mu4e)
(load-library "smtpmail")

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

  mu4e-maildir       "/home/user/Maildir"
  ;; the next are relative to `mu4e-maildir'
  mu4e-outbox-folder "/outbox"
  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))

    ;; program to get mail
   mu4e-get-mail-command "fetchmail"

   ;; general emacs mail settings
   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 "smtpa.example.com"
    smtpmail-smtp-server ""smtpa.example.com"
    smtpmail-local-domain "example.com"

    ;; for offline mode
    smtpmail-queue-mail  nil
    smtpmail-queue-dir   "/home/user/Maildir/queue/cur")
@end verbatim
@end example


@bye