\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 mail client: (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 User Manual

@emph{Mu-For-Emacs} (or for short, @code{mu4e}), is an @code{emacs} based
e-mail client, based on the @code{mu} e-mail search engine. @code{mu4e}
supports GNU Emacs 23 and later, and may work with other versions as well.
 
@menu
* Introduction::
* Overview::
* Installation::
* Getting mail::
* Searching mail::
* Reading mail::
* Processing mail::
* Sending mail::
* Example configuration::
@end menu

@node Introduction
@chapter Introduction

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

@code{mu4e} (and @code{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 @code{fetchmail} and @code{offlineimap}. As long as the messages
end up in a Maildir, @code{mu4e}/@code{mu} are happy to deal with them.

@code{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, @code{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 @code{mu4e} to concentrate on what it
does best: quick message searching, reading mails, replying them, moving
messages around and so on.

@subsection Acknowledgments

@code{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!

@code{mu4e} has taken inspiration from many places. First, there are @code{sup}
and @code{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 @code{dired} interaction model. 

@node Installation
@chapter Installation

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

At the time of writing, there are no distribution packages for @code{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, but @code{mu} and @code{mu4e} should be installed.

Note, there's a hard dependency between versions of @code{mu4e} and @code{mu}
- you cannot combine different versions.

There is experimental support for the @code{emacs} customization system in
@code{mu4e}, but for now we recommend setting the values by - please
@xref{Example configuration} for an example of this.

@node Overview
@chapter Overview

@section Elements
Without going into too much technical detail, here we describe the elements in
a @code{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,
 @code{~/Maildir}), and new mail comes in using tools like @code{fetchmail},
 @code{offlineimap} etc., or through a local mail servers (such as
 @code{qmail} or @code{Postfix}).

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

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

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

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


@node Getting mail

@chapter Getting mail
@code{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.

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

@node Searching mail
@chapter Searching mail

@section Everything is search

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

@node Reading mail
@chapter Reading mail


@node Processing mail
@chapter Processing mail

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


@node Sending mail
@chapter 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