Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
3011 lines (2406 sloc) 110 KB
\input texinfo.tex @c -*-texinfo-*-
@c %**start of header
@setfilename mu4e.info
@settitle mu4e user manual
@c Use proper quote and backtick for code sections in PDF output
@c Cf. Texinfo manual 14.2
@set txicodequoteundirected
@set txicodequotebacktick
@documentencoding utf-8
@c %**end of header
@include version.texi
@copying
This manual is for @t{mu4e} version @value{mu4e-version}.
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
@titlepage
@title @t{mu4e} - an e-mail client for emacs
@subtitle{version @value{mu4e-version}}
@author Dirk-Jan C. Binnema
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@dircategory Emacs
@direntry
* mu4e: (mu4e). An email client for emacs.
@end direntry
@contents
@ifnottex
@node Top
@top mu4e manual
@end ifnottex
@iftex
@node Welcome to mu4e
@unnumbered Welcome to mu4e
@end iftex
Welcome to @t{mu4e}!
@t{mu4e} (mu-for-emacs) is an e-mail client for GNU-Emacs version 23 and
later, built on top of the
@t{mu}@footnote{@url{http://www.djcbsoftware.nl/code/mu}} e-mail search
engine. @t{mu4e} is optimized for fast handling of large amounts of e-mail.
Some of its key characteristics include:
@itemize
@item Fully search-based there are no folders@footnote{that is, instead of
folders, you can use queries that match all messages in a folder}, only
queries
@item Fully documented, with example configurations
@item User-interface optimized for speed with quick key strokes for common actions
@item Asynchronous; heavy actions don't block @t{emacs}@footnote{currently,
the only exception to this is @emph{sending mail}}
@item Support for crypto
@item Writing rich-text e-mails using @t{org-mode}
@item Address auto-completion based on your messages
@item Easily extendable
@end itemize
This manual goes through the installation of @t{mu4e}, discusses the basic
configuration, and explains its daily use. It also shows you how you can
customize @t{mu4e} for your needs.
At the end of the manual, there are some example configurations, which should
help you to get up to speed quickly.
Also of note is the @xref{FAQ - Frequently Anticipated Questions}, which may
save you some time, and the appendices that try to shed some light on
@t{mu4e}'s internals.
This manual has been updated for @t{mu}/@t{mu4e} version
@emph{@value{mu4e-version}}.
@menu
* Introduction:: How it all began
* Getting started:: Setting things up
* Main view:: Where we go when starting @t{mu4e}
* Headers view:: Lists of message headers
* Message view:: Viewing specific messages
* Editor view:: Creating / editing messages
* Searching:: Some more background on searching/queries
* Marking:: Marking messages and performing actions
* Dynamic folders:: Folders that depend on the context
* Actions:: Defining and using custom actions
Appendices
* Interaction with other tools:: mu4e and the rest of the world
* Example configurations:: Some examples to set you up quickly
* FAQ - Frequently Anticipated Questions:: Common questions and answers
* Extending mu4e:: Writing code for @t{mu4e}
* How it works:: Some notes about the implementation of @t{mu4e}
* Logging and debugging:: How to debug problems in @t{mu4e}
* GNU Free Documentation License:: The license of this manual
@end menu
@node Introduction
@chapter Introduction
@menu
* Why another e-mail client::
* Other mail clients::
* What mu4e does not do::
@end menu
@node Why another e-mail client
@section Why another e-mail client?
Fair question.
I'm not sure the world needs yet another e-mail client, but perhaps @emph{I}
do! I (the author) spend a @emph{lot} of time dealing with e-mail, both
professionally and privately. Having an efficient e-mail client is essential.
Since none of the existing ones worked the way I wanted, I created my own.
As @t{emacs} is an integral part of my workflow, it made a lot of sense to use
it for e-mail as well. And as I already had written an e-mail search engine
(@t{mu}), it seemed only logical to use that as a basis.
Even though I created it for such selfish reasons, @t{mu4e} tries hard to be
as useful as possible for all its users - suggestions are very welcome and
many have already made it to @t{mu4e}.
@node Other mail clients
@section Other mail clients
Under the hood, @t{mu4e} is fully search-based, similar to programs like
@t{notmuch}@footnote{@url{http://notmuchmail.org}},
@t{md}@footnote{@url{https://github.com/nicferrier/md}} and
@t{sup}@footnote{@url{http://sup.rubyforge.org/}}. However, @t{mu4e}'s
user-interface is rather different from those programs.
@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 also takes some ideas 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}, backup with @t{rsync}
and so on. If you delete the database, you won't lose any information.
@node What mu4e does not do
@section What mu4e 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 @t{smptmail} (@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 traditionally needs to do, are
delegated to other tools. This leaves @t{mu4e} to concentrate on what it does
best: quickly finding the mails you are looking for, and handle them as
efficiently as possible.
@node Getting started
@chapter Getting started
In this chapter, we go through the installation of @t{mu4e} and its basic
setup. After we have succeeded in @ref{Getting mail}, and @ref{Indexing your
messages}, we discuss @ref{Basic configuration}.
After these steps, @t{mu4e} should be ready to go!
@menu
* Installation:: How to install @t{mu} and @t{mu4e}
* Getting mail:: Getting mail from a server
* Indexing your messages:: Creating and maintaining the index
* Basic configuration:: Settings for @t{mu4e}
* Folders:: Setting up standard folders
* Retrieval and indexing:: Doing it from mu4e
* Sending mail:: How to send mail
* Running mu4e:: Overview of the @t{mu4e} views
@end menu
@node Installation
@section Installation
@t{mu4e} is part of @t{mu} - by installing the latter, the former is installed
as well. Some Linux distributions provide packaged versions of
@t{mu}/@t{mu4e}; if you can use those, there is no need to compile anything
yourself. However, if there are no packages for your distribution, or if you
want to use the latest development versions, you can follow the steps below.
First, you need make sure you have the necessary dependencies. On a Debian or
Ubuntu system, you can get these with the following commands:
@example
$ sudo apt-get install libgmime-2.6-dev libxapian-dev
# if libgmime-2.6-dev is not available, try libgmime-2.4-dev
# get macs if you don't have it yet, mu4e works with GNU-Emacs 23 and 24
# emacs 24 works better; it may be available as 'emacs-snapshot'
$ sudo apt-get install emacs23
# optional
$ sudo apt-get install guile-2.0-dev html2text xdg-utils
# optional: only needed for msg2pdf and mug (toy gtk+ frontend)
$ sudo apt-get install libwebkit-dev
@end example
Using a release-tarball (as available from
GoogleCode@footnote{@url{http://code.google.com/p/mu0/downloads/list}},
installation follows the normal steps:
@example
$ tar xvfz mu-<version>.tar.gz # use the specific version
$ cd mu-<version>
$./configure && make
$ sudo make install
@end example
Alternatively, if you build from the git repository or use a tarball like the
ones that @t{github} produces, the instructions are slightly different, and
require you to have @t{autotools} installed:
@example
# get from git (alternatively, use a github tarball)
$ git clone git://github.com/djcb/mu.git
$ cd mu
$ autoreconf -i && ./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} on your system, and be available from the command line and
emacs.
You may need to restart @t{emacs}, so it can find @t{mu4e} in its
@code{load-path}.
@subsection mu4e and emacs customization
There is some 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 configurations} for a couple of examples of this; here we go
through things step-by-step.
@node Getting mail
@section Getting mail
In order for @t{mu} (and, by extension, @t{mu4e}) to work, you need to have
your e-mail messages stored in a
@emph{maildir}@footnote{@url{http://en.wikipedia.org/wiki/Maildir}} - a
specific directory structure with one-file-per-message. If you are already
using a maildirs, you are lucky; otherwise, you need to get your mail there in
some way.
If you are using an @abbr{IMAP} or @abbr{POP} server, you can use tools like
@t{getmail}, @t{fetchmail}, @t{offlineimap} or @t{isync} to download your
messages into a maildir (@file{~/Maildir}, often). Because it is such a common
case, there is a full example of setting @t{mu4e} up with @t{offlineimap} and
Gmail; @pxref{Gmail configuration}.
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.
@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 message in 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 a good idea to run
it from the command line, to make sure everything works correctly.
Assuming that your maildir is at @file{~/Maildir}, we 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
need to provide the @t{--maildir=~/Maildir} since it is the default; see the
@t{mu-index} man-page for details} and fill the database, and give progress
information while doing so.
The indexing process may take a few minutes the first time you do it (for
thousands of e-mails); afterwards it is much faster, since @t{mu} only scans
messages that are new or have changed. Indexing is discussed in full detail in
the @t{mu-index} man page.
After the indexing process has finished, you can quickly test if everything
worked, by trying some command line searches, for example
@example
$ mu find hello
@end example
which 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{mu}; the next
step is to do some basic configuration for @t{mu4e}.
@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 it, and tell @t{mu4e} where it can find specific maildir
folders.
So, add to your @file{~/.emacs} (or its moral equivalent, such as
@file{~/.emacs.d/init.el}) something like:
@lisp
(require 'mu4e)
@end lisp
@node Folders
@section Folders
The next step is to tell @t{mu4e} where it can find your Maildir, and some
special folders. So, for example@footnote{Note that the folders
(@t{mu4e-sent-folder}, @t{mu4e-drafts-folder}, @t{mu4e-trash-folder} and
@t{mu4e-refile-folder}) can also be @emph{functions} that are evaluated at
runtime. This allows for dynamically changing them depending on context. See
@ref{Dynamic folders} for details.}:
@lisp
(setq
mu4e-maildir "~/Maildir" ;; top-level Maildir
mu4e-sent-folder "/sent" ;; folder for sent messages
mu4e-drafts-folder "/drafts" ;; unfinished messages
mu4e-trash-folder "/trash" ;; trashed messages
mu4e-refile-folder "/archive") ;; saved messages
@end lisp
@code{mu4e-maildir} takes an actual filesystem-path, the other folder names
are all relative to @code{mu4e-maildir}. The ones above are also the defaults.
Now, let's see how we can get the messages into our system.
@node Retrieval and indexing
@section Retrieval and indexing
As we have seen, we can do all of the mail retrieval @emph{outside} of
@t{emacs}/@t{mu4e}. However, 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 set the shell command to @t{"true"}, in
which case @t{mu4e} won't try to get new mail, but still re-index your
messages.
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 won't update at all. If you make
changes to @code{mu4e-update-interval}, @code{mu4e} must be restarted before
the changes take effect.
A simple setup could look something like:
@lisp
(setq
mu4e-get-mail-command "offlineimap" ;; or fetchmail, or ...
mu4e-update-interval 300) ;; update every 5 minutes
@end lisp
It is possible to get notifications when the indexing process does any updates
- for example when receiving new mail. See @code{mu4e-index-updated-hook} and
the tips on its use in the @ref{FAQ - Frequently Anticipated Questions}.
Now that we have setup
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 @t{message-mode} (@inforef{Top,,message}) for writing
mail and inherits the setup for @emph{sending} mail as well.
For sending mail using @abbr{SMTP}, @t{mu4e} uses @t{smtpmail}
(@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
configurations}.
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} (re)uses the same @t{message mode} and @t{smtpmail} that Gnus
uses, many settings for those also apply to @t{mu4e}.
@subsection Dealing with sent messages
By default, @t{mu4e} puts a copy of any messages you sent in the folder you
set for @code{mu4e-sent-folder}. some case, this may not be what you want -
for example, when using Gmail-over-@abbr{IMAP} (but @emph{not} with
Gmail-overo-@abbr{POP3}), this interferes with Gmail's handling of the sent
messages folder, and you may end up with duplicate messages.
You can use the the variable @code{mu4e-sent-messages-behavior} (which takes a
symbol) to customize what happens with sent messages. 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} (the sent
message is moved to the trash-folder (@code{mu4e-trash-folder}), and
@code{'delete} to simply discard the sent message altogether (so GMail can
deal with it).
For Gmail-IMAP, you could add the following to your settings:
@verbatim
;; don't save messages to Sent Messages, Gmail/IMAP takes care of this
(setq mu4e-sent-messages-behavior 'trash)
@end verbatim
And that's it! We should now be ready to go.
@node Running mu4e
@section Running mu4e
After following the steps in this chapter, we should now have a working
@t{mu4e} setup. Great!
In the next chapters, we walk through the various views in @t{mu4e}.
@c @menu
@c * Main view:: This is where we start
@c * Headers view:: Lists of message headers
@c * Message view:: Viewing specific messages
@c * Editor view:: Creating / editing messages
@c @end menu
For your orientation, the diagram below shows how the views relate to each
other, and the default key-bindings to get from one view to the next.
@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: edit bookmark-search
-----------------------------------------------------------
@end example
@node Main view
@chapter The main view
After you have installed @t{mu4e} (@pxref{Getting started}), you can start it
with @code{M-x mu4e}. @t{mu4e} does some checks to ensure everything is set up
correctly, and then show you the glorious @t{mu4e} main view.
@menu
* MV Overview::
* Basic actions::
* MV Bookmarks::
* Miscellaneous::
@end menu
@node MV Overview
@section Overview
The main view looks something like the following:
@verbatim
----------------------------------------------------------------------------
* mu4e - mu for emacs version x.x C
Basics
* [j]ump to some maildir
* enter a [s]earch query
* [C]ompose a new message
Bookmarks
* [bu] Unread messages
* [bt] Today's messages
* [bw] Last 7 days
* [bp] Messages with images
Misc
* [U]pdate email & database
* toggle [m]ail sending mode (direct)
* [f]lush queued mail
* [A]bout mu4e
* [H]elp
* [q]uit mu4e
----------------------------------------------------------------------------
@end verbatim
If you see a @t{C} on the right hand side of @t{version x.x}, your @t{mu4e}
has support for decryption of encrypted messages, and verifying
signatures. See @ref{Decryption} and @ref{Verifying signatures} in the
@ref{Message view}.
Below, we assume the default key bindings.
@node Basic actions
@section Basic actions
First, the @emph{Basics}:
@itemize
@item @t{[j]ump to some maildir}: after pressing @key{j} (``jump''),
@t{mu4e} asks you for a maildir to visit. These are the maildirs you set in
@ref{Basic configuration} and any of your own. If you choose @key{o}
(``other'') or @key{/}, you can choose from all maildirs under
@code{mu4e-maildir}. After choosing a maildir, the message in that maildir are
shown in the @ref{Headers view}.
@item @t{enter a [s]earch query}: after pressing @key{s}, @t{mu4e} asks
you for a search query, and after entering one, shows the results in the
@ref{Headers view}.
@item @t{[C]ompose a new message}: after pressing @key{C}, you start
@end itemize
@node MV Bookmarks
@section Bookmarks
Next come @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
certain 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}.
@node Miscellaneous
@section Miscellaneous
Finally, there are some @emph{Misc} (miscellaneous) actions:
@itemize
@item @t{[U]pdate email & database} executes 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)} toggles between sending
mail directly, and queuing it first (for example, when you are offline), and
@t{[f]lush queued mail} flushes any queued mail. This item is visible only
if you have actually set up mail-queuing. @ref{Queuing mail}.
@item @t{[A]bout mu4e} provides general information about @t{mu4e}.
@item @t{[H]elp} shows help information for this view.
@item Finally, @t{[q]uit mu4e} unsurprisingly quits @t{mu4e}.
@end itemize
@node Headers view
@chapter The headers view
The headers view shows the results of a search query. There is a line for each
matching message, showing information about it.
@menu
* HV Overview::
* Keybindings::
* Marking messages::
* Sort order and threading::
* HV Actions::
* Split view::
@end menu
@node HV Overview
@section Overview
@verbatim
---------------------------------------------------------------------------
Date Flgs From/To Subject
2011-12-16 18:38 S To Edmund Dantès + Re: Extensions?
2011-12-16 21:44 S Abbé Busoni + Re: Extensions?
2011-12-17 03:14 SR Pierre Morrel + Re: Extensions?
2011-12-17 04:04 uN Jacopo + Re: Extensions?
2011-12-17 14:36 uN Mercédès + Re: Extensions?
2011-12-18 06:05 uN Beachamp \ Re: Extensions?
2011-12-16 18:23 Ss Albert de Moncerf + Re: [O] A cool tool
2011-12-17 01:53 Sa Gaspard Caderousse \ Re: [O] A cool tool
2011-12-16 16:31 uN Baron Danglars | [O] imaxima?
End of search results
---------------------------------------------------------------------------
@end verbatim
Some notes to explain what you see in the example:
@itemize
@item The fields shown in the headers view can be influenced by customizing
the variable @code{mu4e-headers-fields}; see @code{mu4e-header-info} for the
list of available fields.
@item Instead of showing the @t{From:} and @t{To:} fields separately, you
can use From/To (@t{:from-or-to} in @code{mu4e-headers-fields} as a more
compact way to convey the most important information: it shows @t{From:}
@emph{except} when the e-mail was sent by the user (i.e., you) - in that case
it shows @t{To:} (prefixed by @t{To}@footnote{You can customize this by
changing the variable @code{mu4e-headers-from-or-to-prefix} (a cons cell)}, as
in the example above). To determine whether a message was sent by you,
@t{mu4e} uses the variable @code{mu4e-user-mail-address-regexp}, which should
be a regular expression matching all the e-mail addresses that you use.
@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. The tooltip for this field
also contains this information.
@item You can customize the date format with the variable
@t{mu4e-headers-date-format}
@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
@node Keybindings
@section 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)
RET open the message at point in the message view
searching
---------
s search
S edit last query
/ narrow the search
b search bookmark
B edit bookmark before search
j jump to maildir
M-left previous query
M-right next query
O change sort order
P toggle threading
Q toggle full-search
marking
-------
d mark for moving to the trash folder
DEL,D mark for complete deletion
m mark for moving to another maildir folder
r mark for refiling
+,- mark for flagging/unflagging
?,! mark message as unread, read
u unmark message at point
U unmark *all* messages
% mark based on a regular expression
T,t mark whole thread, subthread
* deferred mark (decide what to mark for later)
# resolve deferred marks
x execute actions for the marked messages
composition
-----------
R,F,C reply/forward/compose
E edit (only allowed for draft messages)
misc
----
a execute some custom action on a header
| pipe message through shell command
C-+,C-- increase / decrease the number of headers shown
H get help
q,z leave the headers buffer
@end verbatim
@node Marking messages
@section Marking messages
When working with messages, usually the first step is @emph{marking} them for
a certain action, such as deleting them or moving them. Then, after one or
more marks are set, you execute (@key{x}) these marks. The two-step
mark-execute sequence is similar to what @t{dired} and som other emacs-based
programs do. This way, @t{mu4e} tries to be as quick as possible while
avoiding accidents.
The mark/unmark commands support the current @emph{region} (i.e., selection)
-- so, for example, if you the select ('mark' in emacs lingo) a number of
message (like you would select text in a buffer) and then press @key{DEL}, all
selected message is marked for deletion.
You can mark all messages that match a certain pattern with @key{%}. In
addition, you can mark all messages in the current thread (@key{T}) or
sub-thread (@key{t}).
When you try to do a new search, or refresh the headers buffer while you still
have marked messages, normally you are asked what to do with those marks
-- whether to @emph{apply} them before leaving, or @emph{ignore} them. This
behavior can be influenced with the variable
@code{mu4e-headers-leave-behavior} -- see its documentation.
For more information about marking, @xref{Marking}.
@node Sort order and threading
@section Sort order and threading
By default, @t{mu4e} sorts messages by date, in descending order: the most
recent messages are shown at the top. In addition, the messages are
@emph{threaded}, i.e., shown in the context of a message thread; this also
affects the sort order.
You can change the sort order with @t{M-x mu4e-headers-change-sorting} or
@key{O}, and you can toggle threading on/off using @t{M-x
mu4e-headers-toggle-threading} or @key{P}. For both of these functions, unless
you provide a prefix argument (@key{C-u}), the current search is updated
immediately using the new parameters. You can toggle full-search
(@ref{Searching}) using @t{M-x mu4e-headers-toggle-full-search} or @key{Q}.
If you want to change the defaults for these settings, you can use the
variables @code{mu4e-headers-sortfield} and @code{mu4e-headers-show-threads}.
Note that you can see the current settings in the emacs modeline; it shows the
current query, followed by the shortcut character for sortfield (the same
character you'd use in @code{mu4e-headers-change-sorting}. The next character
is either @t{a} (for ascending, @emph{A->Z} order), or @t{d} (for descending,
@emph{Z->A} order). If threading is enabled, the next character is a @t{T}, and
finally, if we're doing an unlimited, full search, the last character is an
@t{F}.
To illustrate this, suppose our query is @t{subject:foo maildir:/bar}, we're
sorting by subject in ascending order with threads enabled, and it's a full
search. The corresponding mode-line string then is: @t{subject:foo
maildir:/bar(saTF)}.
@node HV Actions
@section Actions
@code{mu4e-headers-action} (@key{a}) lets you pick custom actions to perform
on the message at point. You can specify these actions using the variable
@code{mu4e-headers-actions}. Refer to @ref{Actions} for details.
@t{mu4e} defines some default actions. One of this those is for
@emph{capturing} a message: @key{a c} 'captures' the current
message. Next, when you're editing some message, you can include the
previously captured message as an attachment, using
@code{mu4e-compose-attach-captured-message}.
The file @file{mu4e-actions.el} in the @t{mu4e} source distribution contains a
number of example actions.
@node Split view
@section Split view
Using the @emph{Split view}, we can see the @ref{Headers view} and the
@ref{Message view} next to each other, with the message that is selected in
the former, visible in the latter.
You can influence the way the splitting is done by customizing the variable
@code{mu4e-split-view} 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
@chapter The message view
@menu
* MSGV Overview::
* MSGV Keybindings::
* Opening and saving attachments::
* Viewing images inline::
* Displaying rich-text messages::
* MSGV Crypto::
* MSGV Actions::
@end menu
@node MSGV Overview
@section Overview
After selecting a message in the @ref{Headers view}, it appears 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 By default, @t{mu4e} shows only the names of contacts in address fields,
and not the e-mail addresses. You can see the e-mail addresses by clicking on
the name, or pressing @key{M-RET}. Furthermore, you can compose a message for
the contact at point by either @key{[mouse-2]} or pressing @key{C}. If you
always want to see the addresses, you can set
@option{mu4e-view-show-addresses} to @t{t}.
@item The body text can be line-wrapped using @t{longlines-mode}. @t{mu4e}
defines @key{w} to toggle between the wrapped and unwrapped state. If you want
to do this for every message, invoke @code{longlines-mode} in your
@code{mu4e-view-mode-hook}.
@item You can hide cited parts in messages (the parts starting with @t{ > })
using @code{mu4e-view-hide-cited}, bound to @key{h}. If you want to do this
automatically for every message, invoke the function in your
@code{mu4e-view-mode-hook}.
@item For search-related operations, see @ref{Searching}.
@end itemize
@node MSGV Keybindings
@section Keybindings
You can find most things you can do with this message in the @emph{View} menu,
or by using the keyboard; the default bindings are:
@verbatim
key description
==============================================================
n,p go to next, previous message
y select the headers view (if it's visible)
RET scroll down
M-RET open URL at point / attachment at point
searching
---------
s search
e edit last query
/ narrow the search
b search bookmark
B edit bookmark before search
j jump to maildir
M-left previous query
M-right next query
marking
-------
d mark for moving to the trash folder
DEL,D mark for complete deletion
m mark for moving to another maildir folder
r mark for refiling
+,- mark for flagging/unflagging
u unmark message at point
U unmark *all* messages
% mark based on a regular expression
T,t mark whole thread, subthread
SPC deferred mark (decide what to mark for later)
* resolve deferred marks
x execute actions for the marked messages
composition
-----------
R,F,C reply/forward/compose
E edit (only allowed for draft messages)
actions
-------
g go to (visit) numbered URL (using `browse-url')
(or: <mouse-1> or M-RET with point on url)
e extract (save) attachment (asks for number)
(or: <mouse-2> or S-RET with point on attachment)
C-u e extracts multiple attachments
o open attachment (asks for number)
(or: <mouse-1> or M-RET with point on attachment)
a execute some custom action on the message
A execute some custom action on an attachment
misc
----
w toggle line wrapping
h toggle showing cited parts
v show details about the cryptographic signature
. show the raw message view. 'q' takes you back.
C-+,C-- increase / decrease the number of headers shown
H get help
q,z leave the message view
@end verbatim
For the marking commands, please refer to @ref{Marking messages}.
@node Opening and saving attachments
@section Opening and saving attachments
By default, @t{mu4e} uses the @t{xdg-open}-program
@footnote{@url{http://portland.freedesktop.org/wiki/}} or (on MacOS) the
@t{open} program for opening attachments. If you want to use another program,
you do so by setting the @t{MU_PLAY_PROGRAM} environment variable to the
program to be used.
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 "~/Downloads")
@end lisp
For more flexibility, @code{mu4e-attachment-dir} can also be a user-provided
function. This function receives two parameters: the file-name and the
mime-type@footnote{sadly, often @t{application/octet-stream} is used for the
mime-type, even if a better type is available} of the attachment, either or
both of which can be @t{nil}. For example:
@lisp
(setq mu4e-attachment-dir
(lambda (fname mtype)
(cond
;; docfiles go to ~/Desktop
((and fname (string-match "\\.doc$" fname)) "~/Desktop")
;; other cases ...
(t "~/Downloads")))) ;; everything else
@end lisp
If you want to extract multiple attachments at once, you can do so by
prefixing the extracting command by @key{C-u}; so @key{C-u e} asks you for
a range of attachments to extract (for example, 1 3-6 8). Range @t{a} is a
shortcut for @emph{all} attachments.
@node Viewing images inline
@section Viewing images inline
It is possible to show images inline in the message view buffer if you run
@t{emacs} in GUI-mode. You can enable this by setting the variable
@code{mu4e-view-show-images} to @t{t}.
Since @t{emacs} does not always handle images correctly, this is not enabled
by default. Note, if you are using @t{emacs} 24 and build it yourself, you
probable want to build it with @emph{Imagemagick} support -- in that case,
also make sure you call @code{imagemagick-register-types} in your
configuration, so it is used for images.
@lisp
;; enable inline images
(setq mu4e-view-show-images t)
;; use imagemagick, if available
(when (fboundp 'imagemagick-register-types)
(imagemagick-register-types))
@end lisp
@node Displaying rich-text messages
@section Displaying rich-text messages
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 @t{emacs}
built-in @code{html2text} function. However, you can set the variable
@code{mu4e-html2text-command} to some external program, which is then used
instead. 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 can
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 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 MSGV Crypto
@section Crypto
The @t{mu4e} message view supports decryption of encrypted messages, as well
as verification of signatures. For signing/encrypting messages your outgoing
messages, see @ref{Signing and encrypting}.
Currently, only PGP/MIME is supported; PGP-inline and S/MIME are not.
@subsection Decryption
@anchor{Decryption}
If you receive messages that are encrypted (using PGP/MIME), @t{mu4e} can try
to decrypt them@footnote{Decryption is only available if @t{mu} was built with
crypto-support; see the @ref{FAQ - Frequently Anticipated Questions}}. In
addition, @t{gnupg-agent} must be running; thankfully, in most mainstream
Linux/Unix desktop environments, this should work automatically.
You can influence how @t{mu4e} should deal with encrypted messages using
@code{mu4e-decryption-policy}. If you set it to @t{t}, @t{mu4e} attempts to
decrypt messages automatically; this is the default. If you set it to @t{nil},
@t{mu4e} won't @emph{not} attempt to decrypt anything, and finally if you set
it to @t{'ask}, it asks you what to do, each time an encrypted message is
encountered.
When opening an encrypted message, @t{mu} consults @t{gpg-agent} to see
whether it already has unlocked the key needed to decrypt the message; if not,
it prompts us for a password (typically with a separate top-level
window). This is only needed once per session.
@subsection Verifying signatures
@anchor{Verifying signatures}
Some e-mail messages are cryptographically signed, and @t{mu4e} can check the
validity of the signatures@footnote{Signature verification is only available
if @t{mu} was built with crypto-support; see the @ref{FAQ - Frequently
Anticipated Questions}}.
If a message has a signature, the message view shows an extra header
@t{Signature:} (assuming it is part of your @code{mu4e-view-fields}), and one
or more 'verdicts' of the signatures found; either @t{verified},
@t{unverified} or @t{error}. For instance:
@verbatim
Signature: unverified (Details)
@end verbatim
You can see the details of the signature verification by activating the
@t{Details} or pressing @key{v}. This pops up a little window with the
details of the signatures found and whether they could be verified or not.
For more information, please see the @t{mu-verify} manual page.
@node MSGV Actions
@section 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} opens that attachment in @emph{The
Gimp}.
@item @t{pipe} (@key{|}: process the attachment with some Unix shell-pipe and
see the results. Suppose you receive a patch file, and would like to get an
overview of the changes, using the @t{diffstat} program. You can use something
like: @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 a @emph{temporary copy} of the attachment.
For more information on setting up actions and how to define them, see
@ref{Actions}.
@node Editor view
@chapter The editor view
Writing e-mail messages takes place in the Editor View. @t{mu4e}'s editor view
builds on top of Gnu's @t{message-mode}. Most of the @t{message-mode}
functionality is available, as well some @t{mu4e}-specifics.
@menu
* EV Overview::
* Some useful keybindings::
* Address autocompletion::
* Compose hooks::
* Signing and encrypting::
* Queuing mail::
@end menu
@node EV Overview
@section Overview
@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
@node Some useful keybindings
@section Some useful keybindings
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):
@verbatim
key description
--- -----------
C-c C-c send message
C-c C-d save to drafts and leave
C-c C-k kill the message
C-c C-a attach a file (pro-tip: drag & drop works as well)
@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}.
Normally, @t{mu4e} @emph{buries} the message buffer after sending; if you
want to kill the buffer instead, add something like the following to your
configuration:
@lisp
(setq message-kill-buffer-on-exit t)
@end lisp
@node Address autocompletion
@section Address autocompletion
Since @t{mu}/@t{mu4e} version 0.9.8.5, there is support for autocompleting
addresses using @key{TAB} when composing e-mail messages. As the source for
the addresses to complete, @t{mu4e} uses the e-mail addresses in its database
-- addresses you sent messages to or received messages from. @emph{Note:}
auto-completion should work with emacs versions 23.2 and later.
Address auto-completion is enabled by default. If you want to disable it for
some reason, set @t{mu4e-compose-complete-addresses} to @t{nil}.
Emacs 24 also supports cycling through the alternatives. When there are more
than @emph{5} matching addresses, they are shown in a @t{*Completions*}
buffer. Once the number of matches gets below this number, one is selected
(put in the address field) and you can cycle through the alternatives using
@key{TAB}.
@subsection Limiting the number of addresses
If you have a lot of mail, especially from mailing lists and the like, there
are @emph{many} e-mail addresses, most of which are unlikely to be useful when
auto-completing.
So, @t{mu4e} attempts to limit the number of e-mail addresses in the
completion pool by filter the ones that are most likely to be relevant. The
following variables are available to tune this:
@itemize
@item @code{mu4e-compose-complete-only-personal} - when set to @t{t},
only consider addresses that were seen in @emph{personal} messages -- that is,
messages in which one of my e-mail addresses was seen in one of the address
fields. This is to exclude mailing list posts. You can define what is
considered 'my e-mail address' using @code{mu4e-my-email-addresses}, a list of
e-mail address (defaults to @t{(user-mail-address)}), and when indexing from
the command line, the @t{--my-address} parameter for @t{mu index}.
@item @code{mu4e-compose-complete-only-after} - only consider e-mail
addresses seen after some date. Parameter is a string, parseable by
@code{org-parse-time-string}. This excludes very old e-mail addresses. The
default is @t{"2010-01-01"}, i.e., only consider e-mail addresses used since
the start of 2010.
@item @code{mu4e-compose-complete-ignore-address-regexp} - a regular expression to
filter out other 'junk' e-mail addresses; defaults to @t{noreply}.
@end itemize
@node Compose hooks
@section Compose hooks
If you want to execute some custom action before message composition starts,
you can define a @emph{hook function}. @t{mu4e} offers two hooks:
@itemize
@item @code{mu4e-compose-pre-hook}: this hook is run @emph{before} composition
starts; if you are composing a @emph{reply}, @emph{forward} a message, or
@emph{edit} an existing message, the variable
@code{mu4e-compose-parent-message} points to the message being replied to,
forwarded or edit, and you can use @code{mu4e-message-field} to get the value of
various properties (and see @ref{The message s-expression}).
@item @code{mu4e-compose-mode-hook}: this hook is run just before composition
starts, when the whole buffer has already been set up. This is a good place
for editing-related settings. @code{mu4e-compose-parent-message} (see above)
is also at your disposal.
@end itemize
Let's look at some examples.
First, suppose we want to set the @t{From:}-address for a reply message based
on the receiver of the original:
@lisp
;; 1) messages to me@@foo.com should be replied with From:me@@foo.com
;; 2) messages to me@@bar.com should be replied with From:me@@bar.com
;; 3) all other mail should use From:me@@cuux.com
(add-hook 'mu4e-compose-pre-hook
(defun my-set-from-address ()
"Set the From address based on the To address of the original."
(let ((orig-to
(cdar
(mu4e-message-field mu4e-compose-parent-message :to))))
(setq user-mail-address
(cond
((string= "me@@foo.com" orig-to) "me@@foo.com")
((string= "me@@bar.com" orig-to) "me@@bar.com")
(t "me@@cuux.com"))))))
@end lisp
Second, as mentioned, @code{mu4e-compose-mode-hook} is especially useful for
editing-related settings. For example:
@lisp
(add-hook 'mu4e-compose-mode-hook
(defun my-do-compose-stuff ()
"My settings for message composition."
(set-fill-column 72)
(flyspell-mode)))
@end lisp
This hook is also useful for adding headers or changing headers, since the
message is fully formed when this hook runs. For example, to add a
@t{Bcc:}-header, you could add something like the following:
@lisp
(add-hook 'mu4e-compose-mode-hook
(defun my-add-bcc ()
"Add a Bcc: header."
(message-add-header "Bcc: me@@example.com\n")))
@end lisp
@node Signing and encrypting
@section Signing and encrypting
Signing and encrypting of messages is possible using @t{emacs-mime}
(@inforef{Composing,,emacs-mime Composing}), most easily accessed through the
@t{Attachments}-menu while composing a message, or functions like
@code{mml-secure-message-encrypt-pgp}, @code{mml-secure-message-sign-pgp}.
The support for encryption and signing is @emph{independent} of the support
for their counterparts, decrypting and signature verification (as discussed in
@ref{MSGV Crypto}); even if your @t{mu4e} does have support for the latter
two, you can still sign/encrypt messages.
Currently, decryption and signature verification only works for PGP/MIME;
inline-PGP and S/MIME are not supported.
@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} @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 put the queue directory somewhere in our normal
maildir. If you want to use queued mail, you should create this directory
before starting @t{mu4e}. The @command{mu mkdir} command may be useful here,
so for example:
@verbatim
$ mu mkdir ~/Maildir/queue
$ touch ~/Maildir/queue/.noindex
@end verbatim
The file created by the @command{touch} command tells @t{mu} to ignore this
directory for indexing, which makes sense since it contains @t{smtpmail}
meta-data rather than 'normal' messages; see the @t{mu-mkdir} and @t{mu-index}
man pages for details.
@emph{Warning}: when you switch on queued-mode, your messages won't 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', you are
actually executing a query for messages that happen to have the property of
being in a certain folder.
By default, queries return up to @code{mu4e-search-results-limit} (default:
500) results. That is usually more than enough, and it helps performance quite
a bit to limit the number of results. However, sometimes you may want to show
@emph{all} results; you can enable this with @t{M-x
mu4e-headers-toggle-full-search}, or by customizing the variable
@code{mu4e-headers-full-search}. This applies to all search commands.
You can also influence the sort order and whether threads are shown or not;
see @ref{Sort order and threading}.
@menu
* Queries::
* Bookmarks::
* Maildir searches::
* Other search functionality::
@end menu
@node Queries
@section Queries
The queries you can execute are the same ones that @code{mu find}
understands@footnote{with the caveat that command-line queries are subject to
the shell's interpretation before @t{mu} sees them}. 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 messages about Rupert in the Sent Items folder
# note that terms with spaces need quotes
maildir:"/Sent Items" rupert
# 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 term's rightmost character
subject:soc*
# get all mails with attachment with filenames starting with 'pic'
# note: the '*' wildcard can only appear as the term's rightmost character
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 term's rightmost character
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 show up in the main
screen. Each of the list elements is a three-element list of the
form (QUERY DESCRIPTION KEY), where QUERY is a string with a mu
query, DESCRIPTION is a short description of the query (this
shows up in the UI), and KEY is a shortcut key for the query.")
@end lisp
You can 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} lists all the bookmarks
defined in the echo area, with the shortcut key highlighted. So, to invoke the
bookmark we just defined (to get the list of "Big Messages"), all you need to
type is @key{bb}.
@subsection Editing bookmarks before searching
There is also @code{mu4e-headers-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. There is support for autocompletion; note
that the list of maildirs is determined when @t{mu4e} starts; if there are
changes in the maildirs while @t{mu4e} is running, you need to restart
@t{mu4e}.
Each of the folder names is relative to your top-level maildir directory; so if
you keep your mail in @file{~/Maildir}, @file{/inbox} would refer to
@file{~/Maildir/inbox}.
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 Other search functionality
@section Other search functionality
@subsection Navigating through search queries
You can navigate through previous/next queries using
@code{mu4e-headers-query-prev} and @code{mu4e-headers-query-next}, which are
bound, respectively, to @key{M-left} and @key{M-right}, just like the way you
can navigate to previous and next pages in many web browsers.
The functions try to be smart as to not record duplicate queries. Also, the
number of queries remembered has a fixed limit, so long-running @t{mu4e} won't
use too much memory.
If you want to forget previous/next queries, you can use
@code{mu4e-headers-forget-queries}.
@subsection Narrowing search results
Sometimes, it is useful to narrow existing search results, i.e., add some
clauses to the current query to match fewer messages.
As an example of this, suppose you're looking at the some mailing list,
perhaps by jumping to a maildir (@code{mu4e-headers-jump-to-maildir},
@key{j}) or because you followed some bookmark
(@code{mu4e-headers-search-bookmark}, @key{b}). Now, of the messages in that
search, you want to narrow things down to only those messages that have
attachments.
Now, @code{mu4e-headers-search-narrow} (@key{/}) comes in handy. That function
asks for an additional search pattern, which is appended to the current search
query, in effect getting you the subset of the currently shown headers that
also match this extra search pattern. @key{\} takes you back to the previous
query, so, effectively 'widens' the search if you have just narrowed it.
Technically, narrowing the results of query @t{x} with expression @t{y}
implies doing a search @t{(x) AND y}.
Note, messages that were not in your in your original search results because
of @code{mu4e-search-results-limit}, may still show up in the narrowed query.
@node Marking
@chapter Marking
The common way in @t{mu4e} to do things with messages is a two-step process -
first you @emph{mark} them for a certain action, then you @emph{execute}
(@key{x})the marks. This works in a way somewhat similar to @t{dired}.
Marking can happen in both the @ref{Headers view} and the @ref{Message view}.
@menu
* Selecting messages for marking::
* What to mark for::
* Executing the marks::
* Leaving the headers buffer::
* Built-in marking functions::
* Custom mark functions::
@end menu
@node Selecting messages for marking
@section Selecting messages for marking
There are a couple of ways to select messages for marking:
@itemize
@item @emph{message at point}: you can put a mark on the message-at-point in
either the @ref{Headers view} or @ref{Message view}
@item @emph{region}: you can put a mark on all messages in the current region
(selection) in the @ref{Headers view}
@item @emph{Pattern}: you can put a mark on all messages in the @ref{Headers
view} matching a certain pattern with @code{mu4e-headers-mark-pattern}
(@key{%})
@item You can put a mark on all the messages in the thread/subthread at point
with @code{mu4e-headers-mark-thread} and @code{mu4e-headers-mark-subthread},
respectively
@end itemize
@node What to mark for
@section What to mark for
@t{mu4e} supports a number of different marks - i.e., different actions to
apply to messages:
@verbatim
| mark for/as | keybinding | description |
|--------------+-------------+--------------------------|
| deferred | * | mark now, decide later |
| delete | D, <delete> | delete |
| flag | + | mark as 'flagged' |
| move | m | move to some maildir |
| read | ! | mark as read |
| refile | r | mark for refiling |
| trash | d | move to the trash folder |
| unflag | - | remove 'flagged' mark |
| unmark | u | remove mark at point |
| unmark all | U | remove all marks |
| unread | ? | marks as unread |
@end verbatim
After marking a header for something, the left-most columns shows a character
to remind you what you marked it with. Next to that, @t{mu4e} displays the
name of the mark, on top of the beginning of the header line. This latter
display is informative, but if you often mark many (thousands) messages, this
may slow down things significantly@footnote{this uses an emacs feature called
@emph{overlays}, which are slow when used a lot in a buffer}. For this reason,
you can disable this by setting @code{mu4e-headers-show-target} to @code{nil}.
@t{deferred} is a special kind of mark; you can use it to mark some messages,
and then decide later what mark to use for them. At any time, you can set the
actual mark with @code{mu4e-mark-resolve-deferred-marks} (@key{#}), or
@t{mu4e} asks you for it when you execute the marks (@key{x}).
@node Executing the marks
@section Executing the marks
After you have marked some messages, you can execute them with @key{x}
(@code{mu4e-mark-execute-all}).
@node Leaving the headers buffer
@section Leaving the headers buffer
When you quit or update a headers buffer (for example, by doing a new search)
that has marked messages, @t{mu4e} asks you what to do with them, depending on
the value of the variable @code{mu4e-headers-leave-behavior} -- see its
documentation.
@node Built-in marking functions
@section Built-in marking functions
Some examples of @t{mu4e}'s built-in marking functions.
@itemize
@item @emph{Mark the message at point for trashing}: press @key{d}
@item @emph{Mark all messages in the buffer as unread}: press @key{C-x h o}
@item @emph{Delete the messages in the current thread}: press @key{T D}
@item @emph{Mark messages with a subject matching ``hello'' for flagging}:
press @key{% + s hello RET}. Note, the menu system helps you here; all you
need to remember is @key{%} for @code{mu4e-headers-mark-pattern}.
@end itemize
@node Custom mark functions
@section Custom mark functions
Sometimes, the built-in functions to mark messages may not be sufficient for
your needs. For this, @t{mu4e} offers an easy way to define your own custom
mark functions. You can choose one of the custom marker functions using
@key{&} in @ref{Headers view} and @ref{Message view}.
Custom mark functions should be appended to the list
@code{mu4e-headers-custom-markers}. Each of the elements of this list
('markers') is a list with three (or two) elements:
@itemize
@item The name of the marker - a short string describing this marker. The
first character of this string determines its shortcut, so these should be
unique. If necessary, simply prefix the name with a unique character.
@item a predicate function taking two arguments @t{msg} and @t{param}. @t{msg} is the message
plist (see @ref{The message s-expression} and @t{param} is a parameter
provided by the third of the marker elements (see the next item). The
predicate function should return non-nil if the message matches.
@item (optionally) a function that is evaluated once, and the result is passed as a
parameter to the predicate function. This is useful when user-input is needed.
@end itemize
So, let's look at an example: suppose we want to match all messages that have
more than @emph{n} recipients. We could do it like this:
@lisp
(add-to-list 'mu4e-headers-custom-markers
'("More than n recipients"
(lambda (msg n)
(> (+ (length (mu4e-message-field msg :to))
(length (mu4e-message-field msg :cc))) n))
(lambda ()
(read-number "Match messages with more recipients than: "))) t)
@end lisp
After evaluating this, pressing @key{&} lets you choose the custom marker
function, and ask you for the parameters.
As you can see, it's not very hard to define simple functions to match
messages. There are some more examples in the defaults for
`mu4e-headers-custom-markers'; see @file{mu4e-headers.el}.
@node Dynamic folders
@chapter Dynamic folders
@ref{Folders} showed how to set the standard folders:
@lisp
(setq
mu4e-sent-folder "/sent" ;; folder for sent messages
mu4e-drafts-folder "/drafts" ;; unfinished messages
mu4e-trash-folder "/trash" ;; trashed messages
mu4e-refile-folder "/archive") ;; saved messages
@end lisp
In some cases, having such static folders may not suffice - you may want to
change the folders depending on the context. For example, the folder for
refiling could vary, based on the sender of the message.
For this, instead of setting the standard folders to a string, you can set
them to be a @emph{function} that takes a message as parameter, and returns
the desired folder name.
This chapter shows how to do that.
@menu
* Smart refiling::
* Other dynamic folders::
@end menu
@node Smart refiling
@section Smart refiling
It is sometimes convenient to move messages to some specific folder, based on
some of the message details -- @emph{refiling}(@key{r}).
We can make this 'smart' with a dynamic refiling folder - each message
automatically figures out the right folder to move to. For example, you could
put something like the following in your setup:
@lisp
(setq mu4e-refile-folder
(lambda (msg)
(cond
;; messages to the mu mailing list go to the /mu folder
((mu4e-message-contact-field-matches msg :to
"mu-discuss@@googlegroups.com")
"/mu")
;; messages sent directly to me go to /archive
;; also `mu4e-user-mail-address-regexp' can be used
((mu4e-message-contact-field-matches msg :to
"me@@example.com")
"/private")
;; messages with football or soccer in the subject go to /football
((string-match "football\\|soccer"
(mu4e-message-field msg :subject))
"/football")
;; everything else goes to /archive
;; important to have a catch-all at the end!
(t "/archive"))))
@end lisp
This can be very powerful; you can mark (select) all the messages in the
headers view, then press @key{r}, and have them all marked for refiling to
their particular folders.
Some notes:
@itemize
@item we set @code{mu4e-refile-folder} to an anonymous (@t{lambda}) function. This
function takes one argument, a message. @file{mu4e-message.el} contains
various convenience functions to deal which such messages.
@item In this function, we use a @t{cond} control structure; the function
returns the first of the clauses that matches
@item Especially useful are the function @file{mu4e-message.el}; here we use
the convenience function @code{mu4e-message-contact-field-matches}, which
evaluates to @code{t} if any of the names or e-mail addresses in the @t{To:}
matches the regular expression.
@end itemize
@node Other dynamic folders
@section Other dynamic folders
Using the same mechanism, you can set special sent-, trash-, and draft-folders
for messages. The message-parameter you receive for sent and draft folder is
the @emph{original} message, that is, the message you reply to, forward. If
there is no such message (for example when composing a brand new message) the
message parameter is @t{nil}.
Let's look at an example of this. Suppose you want a different trash folder
for work-email. You can do so with something like the following:
@lisp
(setq mu4e-sent-folder
(lambda (msg)
;; the 'and msg' is to handle the case where there msg is nil
(if (and msg (mu4e-message-contact-field-matches msg :to "me@@work.com"))
"/trash-work"
"/trash")))
@end lisp
Good to remember:
@itemize
@item The @code{msg} parameter you receive in the function refers to the
@emph{original message}, that is, the message being replied to or
forwarded. When re-editing a message, it refers to the message being
edited. When you compose a totally new message, the @code{msg} parameter is
@code{nil}.
@item When re-editing messages, the value of @code{mu4e-drafts-folder} is ignored.
@end itemize
@node Actions
@chapter Actions
@t{mu4e} 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.
@menu
* Defining actions::
* Adding an action in the headers view::
* Adding an action in the message view::
* Adding an attachment action::
* What functions are available?::
* More example actions::
@end menu
@node Defining actions
@section Defining 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}.
Note, the format of the actions has changed since version 0.9.8.4, and you
must change your configuration to use the new format; @t{mu4e} warns you when
you are using the old format.
The older format was: @code{(DESCRIPTION SHORTCUT [VALUE])}, while the new
format is a cons-cell, @code{(DESCRIPTION . VALUE)}; see below for some
examples. If your shortcut is not also the first character of the description,
simply prefix the description with that character.
Let's take a at some simple examples.
@node Adding an action in the headers view
@section 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-message-field msg :to))
(length (mu4e-message-field msg :cc)))))
;; define 'N' (the first letter of the description) as the shortcut
(add-to-list 'mu4e-headers-actions
'("Number of recipients" . show-number-of-recipients) t)
@end lisp
After activating this, @key{a n} in the headers view shows the number of
recipients for the message at point.
@node Adding an action in the message view
@section Adding an action in the message view
As another example, suppose we would like to search for messages by the sender
of this message.
@lisp
(defun search-for-sender (msg)
"Search for messages sent by the sender of the current one."
(mu4e-headers-search
(concat "from:" (cdar (mu4e-message-field msg :from)))))
;; define 'x' as the shortcut
(add-to-list 'mu4e-view-actions
'("xsearch for sender" . search-for-sender) t)
@end lisp
@node Adding an attachment action
@section 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 counts the number of lines in an attachment, and define
@key{n} as the shortcut key (the 'n' is prefixed to the description).
@lisp
(defun count-lines-in-attachment (msg attachnum)
"Count the number of lines in an attachment."
(mu4e-view-pipe-attachment msg attachnum "wc -l"))
(add-to-list 'mu4e-view-attachment-actions
'("ncount lines" . count-lines-in-attachment) t)
@end lisp
@node What functions are available?
@section 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 appear only at the end of completion buffers and the like.
Functions that start with @t{mu4e-view-} and @t{mu4e-headers-} should be
called only from that particular context (the message view and the headers
view, respectively).
@node More example actions
@section More example actions
@t{mu4e} includes a number of example actions in @file{mu4e-actions.el} in the
source distribution (see @key{C-h f mu4e-action-TAB}). For example, for
viewing messages in an external web browser, or listening to a message's
body-text using text-to-speech.
If you have come up with any interesting actions that may be useful for
others, you are invited to contribute those.
@node Interaction with other tools
@appendix Interaction with other tools
In this chapter we discuss some ways in ways in which @t{mu4e} can cooperate
with other tools.
@menu
* Setting the default emacs mail program::
* Creating org-mode links::
* Rich-text messages with org-mode::
* Maintaining an address-book with org-contacts::
* Getting new mail notifications with Sauron::
* Speedbar support::
* Citations with mu-cite::
* Attaching files with dired::
@end menu
@node Setting the default emacs mail program
@section Setting the default emacs mail program
@t{emacs} allows you to select an e-mail program as the default program it
uses when you press @key{C-x m} (@code{compose-mail}), call
@code{report-emacs-bug} and so on.
If you want to use @t{mu4e} for this, you do so by adding the following to
your configuration:
@lisp
(setq mail-user-agent 'mu4e-user-agent)
@end lisp
At the present time, support is 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} stores 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 Rich-text messages with org-mode
@section Rich-text messages with org-mode
@t{org-mode} has some nice facilities for editing texts -- creating lists,
tables, mathematical formulae etc. In addition, it can convert them to
@abbr{HTML}.
An @emph{experimental} @t{mu4e} feature lets you edit your messages with
@t{org-mode}, and (optionally) convert them on the fly (when sending them) to
messages with an HTML-part containing the rich-text version of your messages.
To enable all this, make sure you have
@lisp
(require 'org-mu4e)
@end lisp
somewhere in your setup, and also make sure that the @t{dvipng} program is
available in your path.
Then, when composing a message, you can use @t{M-x org-mu4e-compose-org-mode}
to enable this mode.
@t{org-mu4e-compose-org-mode} behaves more or less like a minor-mode. When it
is active, editing the message body takes place in @t{org-mode}, while editing
the headers uses the normal message editing mode, @t{mu4e-compose-mode}.
Now, if you want to automatically convert the @t{org-mode} markup to rich-text
when sending messages, you need to set the variable
@code{org-mu4e-convert-to-html} to non-nil:
@lisp
(setq org-mu4e-convert-to-html t)
@end lisp
To send the message or execute other @t{mu4e-compose-mode}/@t{message-mode}
commands on the message, first press @key{M-m}. Thus, for example, to send the
message, you'd press @key{M-m C-c}.
The code for doing the conversion is based on Eric Schultze's
@t{org-mime}@footnote{@url{http://orgmode.org/worg/org-contrib/org-mime.php}},
but has been customized for use with @t{mu4e}. In particular, the
mode-switching between @t{org-mode} and @t{mu4e-compose-mode} is
@t{mu4e-specific}.
@subsection Some caveats
It is better @emph{not} to put @t{org-mu4e-compose-org-mode} in a mode-hook
for @t{mu4e-compose-mode}, since that makes it impossible to shut it off again
for the particular message@footnote{This is because @t{mu4e-compose-mode} in
invoked again internally when switching, which re-triggers the
hook-function.}.
In addition, currently the rich-text code does not work well with the
MIME-functionality, such as adding attachments or signing/encrypting
messages. If you want to do that, you are recommended to use plain-text e-mail
messages.
@node Maintaining an address-book with org-contacts
@section Maintaining an address-book with org-contacts
Note, @t{mu4e} supports built-in address autocompletion; @ref{Address
autocompletion}, and that is the recommended way to do this.
However, it is also possible to manage your addresses with @t{org-mode}, using
@t{org-contacts}@footnote{@url{http://julien.danjou.info/software/org-contacts.el}}.
@t{mu4e-actions} defines a useful action (@ref{Actions}) for 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" . mu4e-action-add-org-contact) t)
(add-to-list 'mu4e-view-actions
'("org-contact-add" . 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. Note, the
@key{o} is because of the first character of @t{org-contact-add}.
@node Getting new mail notifications with Sauron
@section Getting new mail notifications with Sauron
The emacs-package @t{sauron}@footnote{Sauron can be found at
@url{https://github.com/djcb/sauron}, or in the Marmalade package-repository
at @url{http://http://marmalade-repo.org/}} (by the same author) can be used
to get notifications about new mails.
If you put something like the below script in your @t{crontab} (or have some
other way of having it execute every @emph{n} minutes) you 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" \
--type=method_call \
"/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, even
when running outside its context.
@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 switching to the @ref{Main view},
the speedbar-frame is updated with your bookmarks and maildirs. For speed
reasons, the list of maildirs is determined when @t{mu4e} starts; if the list
of maildirs changes while @t{mu4e} is running, you need to restart @t{mu4e} to
have those changes reflected in the speedbar and in other places that use this
list, such as auto-completion when jumping to a maildir.
@code{mu4e-speedbar} was contributed by Antono Vasiljev.
@node Citations with mu-cite
@section Citations with @t{mu-cite}
@t{mu-cite}@footnote{Note, despite its name, @t{mu-cite} is a project
unconnected to @t{mu}/@t{mu4e}} is a package to control the way message
citations look like (i.e., the message you responded to when you reply to them
or forward them), with its latest version available at
@url{http://www.jpl.org/elips/mu/}.
After 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 ", " from " wrote:\n\n"))
(setq mu-cite-prefix-format '(" > ")))
@end lisp
@node Attaching files with dired
@section Attaching files with @t{dired}
It's possible to attach files to @t{mu4e} messages using @t{dired}
(@inforef{Dired,,emacs}), using the following steps (based on a post on the
@t{mu-discuss} mailing list by Stephen Eglen).
To prepare for this, you need a special version of the
@code{gnus-dired-mail-buffers} function so it understands @t{mu4e} buffers as
well; so put in your configuration:
@lisp
(require 'gnus-dired)
;; make the `gnus-dired-mail-buffers' function also work on message-mode derived
;; modes, such as mu4e-compose-mode
(defun gnus-dired-mail-buffers ()
"Return a list of active message buffers."
(let (buffers)
(save-current-buffer
(dolist (buffer (buffer-list t))
(set-buffer buffer)
(when (and (derived-mode-p 'message-mode)
(null message-sent-message-via))
(push (buffer-name buffer) buffers))))
(nreverse buffers)))
(setq gnus-dired-mail-mode 'mu4e-user-agent)
(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode)
@end lisp
Then, mark the file(s) in @t{dired} you would like to attach and press @t{C-c
RET C-a}, and you'll be asked whether to attach them to an existing message,
or create a new one.
@node Example configurations
@appendix Example configurations
In this chapter, we show some example configurations. While it is very useful
to see some working settings, we'd like to warn against blindly copying such
things.
@menu
* Minimal configuration::
* Longer configuration::
* Gmail configuration::
* Some other useful settings::
@end menu
@node Minimal configuration
@section Minimal configuration
An (almost) minimal configuration for @t{mu4e} could look something like this
- as you see most is commented-out.
@lisp
;; example configuration for mu-for-emacs (mu4e)
;; make sure mu4e is in your load-path
(require 'mu4e)
;; 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 offers to
;; create them. they can also functions; see their docstrings.
;; (setq mu4e-sent-folder "/sent")
;; (setq mu4e-drafts-folder "/drafts")
;; (setq mu4e-trash-folder "/trash")
;; smtp mail setting; these are the same that `gnus' uses.
(setq
message-send-mail-function 'smtpmail-send-it
smtpmail-default-smtp-server "smtp.example.com"
smtpmail-smtp-server "smtp.example.com"
smtpmail-local-domain "example.com")
@end lisp
@node Longer configuration
@section Longer configuration
@lisp
;; example configuration mu4e
(require 'mu4e)
;; a regular expression that matches all email address uses by
;; the user; this allows us to correctly determine if user
;; is the sender / direct recipient of some message
(setq mu4e-user-mail-address-regexp
"foo@@bar\.com\\|cuux@@example\.com")
;; path to our Maildir directory
(setq mu4e-maildir "/home/user/Maildir")
;; the next are relative to `mu4e-maildir'
;; instead of strings, they can be functions too, see
;; their docstring or the chapter 'Dynamic folders'
(setq mu4e-sent-folder "/sent"
mu4e-drafts-folder "/drafts"
mu4e-trash-folder "/trash")
;; the maildirs you use frequently; access them with 'j' ('jump')
(setq mu4e-maildir-shortcuts
'(("/archive" . ?a)
("/inbox" . ?i)
("/work" . ?w)
("/sent" . ?s)))
;; when you want to use some external command for text->html
;; conversion, e.g. the 'html2text' program
;; (setq mu4e-html2text-command "html2text")
;; the headers to show in the headers list -- a pair of the field
;; and its width, with `nil' meaning 'unlimited'
;; (better only use that for the last field.
;; These are the defaults:
(setq mu4e-headers-fields
'( (:date . 25)
(: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. Note: if you get your mail without an explicit command,
;; but "true" for the command (also the default)
(setq mu4e-get-mail-command "offlineimap")
;; general emacs mail settings; used when composing e-mail
;; the non-mu4e-* stuff is inherited from emacs/message-mode
(setq mu4e-reply-to-address "foo@@bar.com"
user-mail-address "foo@@bar.com"
user-full-name "Foo X. Bar")
;; include in message with C-c C-w
(setq message-signature
"Foo X. Bar\nhttp://www.example.com\n")
;; smtp mail setting
(setq
message-send-mail-function 'smtpmail-send-it
smtpmail-default-smtp-server "smtp.example.com"
smtpmail-smtp-server ""smtp.example.com"
smtpmail-local-domain "example.com"
;; if you need offline mode, set these -- and create the queue dir
;; with 'mu mkdir', i.e.. mu mkdir /home/user/Maildir/queue
smtpmail-queue-mail nil
smtpmail-queue-dir "/home/user/Maildir/queue/cur")
;; don't keep message buffers around
(setq message-kill-buffer-on-exit t)
@end lisp
@node Gmail configuration
@section Gmail configuration
@emph{Gmail} is a popular e-mail provider; let's see how we can make it work
with @t{mu4e}. Since we are using @abbr{IMAP}, you must enable that in the
Gmail web interface (in the settings, under the ``Forwarding and
POP/IMAP''-tab).
@subsection Setting up offlineimap
First of all, we need a program to get the e-mail from Gmail to our local
machine; for this we use @t{offlineimap}; on Debian (and derivatives like
Ubuntu), this is as easy as:
@verbatim
$ sudo apt-get install offlineimap
@end verbatim
while on Fedora (and similar) you need:
@verbatim
$ sudo yum install offlineimap
@end verbatim
Then, we can configure @t{offlineimap} by editing @file{~/.offlineimaprc}:
@verbatim
[general]
accounts = Gmail
maxsyncaccounts = 3
[Account Gmail]
localrepository = Local
remoterepository = Remote
[Repository Local]
type = Maildir
localfolders = ~/Maildir
[Repository Remote]
type = IMAP
remotehost = imap.gmail.com
remoteuser = USERNAME@gmail.com
remotepass = PASSWORD
ssl = yes
maxconnections = 1
realdelete = no
@end verbatim
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.
@subsection Settings
Now, let's make a @t{mu4e} configuration for this:
@lisp
(require 'mu4e)
;; default
;; (setq mu4e-maildir ("~/Maildir")
(setq mu4e-drafts-folder "/[Gmail].Drafts")
(setq mu4e-sent-folder "/[Gmail].Sent Mail")
(setq mu4e-trash-folder "/[Gmail].Trash")
;; don't save message to Sent Messages, Gmail/IMAP takes care of this
(setq mu4e-sent-messages-behavior 'delete)
;; setup some handy shortcuts
;; you can quickly switch to your Inbox -- press ``ji''
;; then, when you want archive some messages, move them to
;; the 'All Mail' folder by pressing ``ma''.
(setq mu4e-maildir-shortcuts
'( ("/INBOX" . ?i)
("/[Gmail].Sent Mail" . ?s)
("/[Gmail].Trash" . ?t)
("/[Gmail].All Mail" . ?a)))
;; allow for updating mail using 'U' in the main view:
(setq mu4e-get-mail-command "offlineimap")
;; something about ourselves
(setq
user-mail-address "USERNAME@@gmail.com"
user-full-name "Foo X. Bar"
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)
;; alternatively, for emacs-24 you can use:
;;(setq message-send-mail-function 'smtpmail-send-it
;; smtpmail-stream-type 'starttls
;; smtpmail-default-smtp-server "smtp.gmail.com"
;; smtpmail-smtp-server "smtp.gmail.com"
;; smtpmail-smtp-service 587)
;; don't keep message buffers around
(setq message-kill-buffer-on-exit t)
@end lisp
And that's it -- put the above in your @file{~/.emacs}, change @t{USERNAME}
etc. to your own, and restart @t{emacs}, and run @kbd{M-x mu4e}.
@node Some other useful settings
@section Some other useful settings
Finally, here are some more settings that are useful, but not enabled by
default for various reasons.
@lisp
;; use 'fancy' non-ascii characters in various places in mu4e
(setq mu4e-use-fancy-chars t)
;; save attachment to my desktop
(setq mu4e-attachment-dir "~/Desktop")
;; attempt to show images when viewing messages
(setq
mu4e-view-show-images t
mu4e-view-image-max-width 800)
@end lisp
@node FAQ - Frequently Anticipated Questions
@appendix FAQ - Frequently Anticipated Questions
In this chapter we list a number of actual and anticipated questions and their
answers.
@menu
* General::
* Reading messages::
* Writing messages::
* Known issues::
@end menu
@node General
@section General
@itemize
@item @emph{How can I quickly delete/move/trash a lot of messages?} You can
select ('mark' in emacs-speak) the messages like you would select text in a
buffer; the actions you then take (e.g., @key{DEL} for delete, @key{m} for
move and @key{t} for trash) applies to @emph{all} selected messages. You
can also use functions like @code{mu4e-headers-mark-thread} (@key{T}),
@code{mu4e-headers-mark-subthread} (@key{t}) to mark whole threads at the same
time, and @code{mu4e-headers-mark-pattern} (@key{%}) to mark all messages
matching a certain regular expression.
@item @emph{mu4e seems to return a subset of all matches - how can I get
all?}. Indeed, for speed reasons, @t{mu4e} returns only up to the value of the
variable @code{m4ue-search-result-limit} (default: 500) matches. To show
@emph{all} results, use @t{M-x mu4e-headers-toggle-full-search}, or customize
the variable @code{mu4e-headers-full-search}. This applies to all search
commands.
@item @emph{How can I get notifications when receiving mail?} There is
@code{mu4e-index-updated-hook}, which gets triggered when the indexing process
triggered sees an update (no just new mail though). To use this hook, you can
put something like the following in your setup (assuming you have @t{aplay}
and some soundfile, change as needed):
@lisp
(add-hook 'mu4e-index-updated-hook
(defun new-mail-sound ()
(shell-command "aplay ~/Sounds/boing.wav&")))
@end lisp
@item @emph{I don't use @t{offlineimap}, @t{fetchmail} etc., I get my mail
through my own mailserver. What should I use for
@code{mu4e-get-mail-command}}? Use @t{"true"} (or don't do anything, it's the
default). This makes getting mail a no-op, but the messages are still
re-indexed.
@item @emph{When I try to 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} automatically restarts @t{mu} when it needs it. In practice, this
seems to work quite well.
@item @emph{Can I automatically apply the marks on messages when
leaving the headers buffer?} Yes you can -- see the documentation for the
variable @t{mu4e-headers-leave-behavior}.
@item @emph{Is there context-sensitive help available?} Yes - pressing @key{H}
should take you to the right place in this manual.
@item @emph{How can I set @t{mu4e} as the default e-mail client in emacs?}
See @ref{Setting the default emacs mail program}.
@item @emph{Can @t{mu4e} use some fancy Unicode characters instead of these
boring plain-ASCII ones?} Glad you asked! Yes, if you set
@code{mu4e-use-fancy-chars} to @t{t}, @t{mu4e} uses such fancy characters in a
number of places.
@end itemize
@node Reading messages
@section Reading messages
@itemize
@item @emph{How can I show attached images in my message view buffers?} See
@ref{Viewing images inline}.
@item @emph{How can I word-wrap long lines in when viewing a
message?} You can toggle between wrapped and non-wrapped states using
@key{w}. If you want to do this for every message, invoke
@code{longlines-mode} in your @code{mu4e-view-mode-hook}.
@item @emph{What about hiding cited parts?} Toggle between hiding and showing
of cited parts with @key{h}. If you want to hide parts automatically, call
@code{mu4e-view-toggle-hide-cited} in your @code{mu4e-view-mode-hook}.
@item @emph{How can I perform custom actions on messages and attachments?} See
@ref{Actions}.
@item @emph{Does @t{mu4e} support crypto (i.e., decrypting messages and verifying signatures)?}
Yes -- if @t{mu} was built with @t{GMime} 2.6 or later, it is possible to do
both (note, only PGP/MIME is supported). In the @ref{Main view} the support is
indicated by a big letter @t{C} on the right hand side of the @t{mu4e}
version. See @ref{Decryption} and @ref{Verifying signatures}. For encryption
and signing messages, see the below.
@end itemize
@node Writing messages
@section Writing messages
@itemize
@item @emph{How can I use @t{BBDB}?} Currently, there is no built-in for
address management with @t{BBDB}; instead, we recommend using @t{mu4e}'s
built-in @ref{Address autocompletion}.
@item @emph{How can I automatically set the @t{From:} address for a
reply-message, based on some field in the original?} See @ref{Compose hooks}.
@item @emph{And what about customizable folders for draft messages, sent
messages, trashed messages, based on e.g. the @t{From:} header?} See
@ref{Dynamic folders}.
@item @emph{How can I automatically add some header to an outgoing message?}
Once more, see @ref{Compose hooks}.
@item @emph{How can I easily include attachments in the messages I write?}
You can drag-and-drop from your desktop; alternatively, you can use @t{dired}
-- see @ref{Attaching files with dired}.
@item @emph{@t{mu4e} seems to remove myself from the Cc: list; how can I
prevent that?}
Set @code{mu4e-compose-keep-self-cc} to @t{t} in your configuration.
@item @emph{How can I sign or encrypt messages?} You can do so using emacs'
MIME-support -- check the @t{Attachments}-menu while composing a message. Also
see @ref{Signing and encrypting}.
@end itemize
@node Known issues
@section Known issues
Although they are not really @emph{questions}, we end this chapter with a list
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{mu4e does not work well if the emacs language environment is not
utf-8}; so, if you problems with encodings, be sure to have
@code{(set-language-environment "UTF-8")} in your @file{.emacs}.
@item @emph{Thread handling is incomplete.} While threads are calculated and are
visible in the headers buffer, you can not collapse/open them.
@item @emph{The key-bindings are @emph{somewhat} hard-coded} That is, the main
menu assumes the default key-bindings, as do the clicks-on-bookmarks.
@end itemize
@node Extending mu4e
@appendix Extending mu4e
@t{mu4e} is designed to be easily extendible - that is, write your own pieces
of emacs-lisp to make @t{mu4e} is a specific way. Here, we provide some notes
/ tips for doing so.
@menu
* What functions are available::
* Message functions::
* Utility functions::
@end menu
@c @node What are good places to extend mu4e
@c @section What are good places to extend mu4e?
@node What functions are available
@section What functions are (not) available?
The whole of @t{mu4e} consists of hundreds of elisp functions. However, many
of those (more than 50%) are for @emph{internal} use; you can recognize them
easily, because they all start with @code{mu4e~}. They make all kinds of
assumptions, and they are subject to change. The same is true for
@emph{variables} that start with @code{mu4e~}; don't touch them.
Let me repeat that:
@verbatim
Do not use mu4e~* functions or variables!
@end verbatim
In addition, you should use functions in the right context; functions that
start with @t{mu4e-view-} are only applicable to the message-view, while
functions starting with @t{mu4e-headers-} are only applicable to the headers
view. Functions without such prefixes are applicable everywhere.
@node Message functions
@section Message functions
Many functions in @t{mu4e} deal with message plist (property lists). They
contain information about messages, such as sender and recipient, subject,
date and so on. To deal with these message plists, there are a number of
@code{mu4e-message-} functions (in @file{mu4e-message.el}), such as
@code{mu4e-message-field} and @code{mu4e-message-at-point}
For example, to get the subject of the 'message-at-point' in either the
headers view or the message view, you could write:
@lisp
(mu4e-message-field (mu4e-message-at-point) :subject)
@end lisp
Check the docstrings for these functions for the details; some notes:
@itemize
@item The contact fields (To, From, Cc, Bcc) they are lists of cons-pairs
@code{(name . email)}; @code{name} may be @code{nil}. If you are only looking
for a match in this list (e.g., ``Is Jack one of the recipients of the
message?''), there is the convenience function
@code{mu4e-message-contact-field-matches} to make this easy.
@item The message body is only available in the message view, not in the
headers view.
@end itemize
@node Utility functions
@section Utility functions
@file{mu4e-utils} contains a number of utility functions that can be
quite useful; we list a number here; see their docstrings for the details.
@itemize
@item @code{mu4e-read-option}: read one option from a list. For example:
@lisp
(mu4e-read-option \"Choose an animal: \"
'((\"Monkey\" . monkey) (\"Gnu\" . gnu) (\"xMoose\" . moose)))
@end lisp
The user is now presented with:
@example
Choose an animal: [M]onkey, [G]nu, [x]Moose
@end example
@item @code{mu4e-ask-maildir}: ask for a maildir; try one of the
shortcuts (@code{mu4e-maildir-shortcuts}), or the full set of available
maildirs.
@item @code{mu4e-log} logs to the @t{mu4e} debugging log if it is enabled; see @code{mu4e-toggle-logging}.
@item @code{mu4e-message}, @code{mu4e-warning}, @code{mu4e-error} are the
@t{mu4e} smart equivalents of the normal @t{elisp} @code{message},
@code{user-error}@footnote{@code{user-error} only appears in @t{emacs} 24.2
and later; in older versions it falls back to @code{error}} and @code{error}
functions.
@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::
* The message s-expression::
@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 then spits 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 is
invoked whenever the process has some data for us. Something like:
@lisp
(let ((proc (start-process <arguments>)))
(set-process-filter proc 'my-process-filter)
(set-process-sentinel proc 'my-process-sentinel))
@end lisp
Note, the process sentinel is invoked when the process is terminated -- so there
you can clean things up.
The function =my-process-filter= is a user-defined function that takes the
process and the chunk of output as arguments; in @t{mu4e} it looks something like
(pseudo-lisp):
@lisp
(defun my-process-filter (proc str)
;; mu4e-buf: a global string variable to which data gets appended
;; as we receive it
(setq mu4e-buf (concat mu4e-buf str))
(when <we-have-received-a-full-expression>
<eat-expression-from mu4e-buf>
<evaluate-expression>))
@end lisp
@code{<evaluate-expression>} de-multiplexes the s-expression we got. For
example, if the s-expression looks like an e-mail message header, it is
processed by the header-handling function, which appends it to the header
list. If the s-expression looks like an error message, it is reported to the
user. And so on.
The language between frontend and backend is documented in the @t{mu-server}
man-page. @t{mu4e} can log these communications; you can use @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} (@key{$}).
@node The message s-expression
@section The message s-expression
A typical message s-expression looks something like the following:
@lisp
(:docid 32461
:from (("Nikola Tesla" . "niko@@example.com"))
:to (("Thomas Edison" . "tom@@example.com"))
:cc (("Rupert The Monkey" . "rupert@@example.com"))
:subject "RE: what about the 50K?"
:date (20369 17624 0)
:size 4337
:message-id "6BDC23465F79238C8233AB82D81EE81AF0114E4E74@@123213.mail.example.com"
:path "/home/tom/Maildir/INBOX/cur/133443243973_1.10027.atlas:2,S"
:maildir "/INBOX"
:priority normal
:flags (seen)
:parts ( (:index 1 :mime-type "text/plain" :size 12345 :attachment nil)
(:index 2 :name "photo.jpg" :mime-type "image/jpeg"
:size 147331 :attachment t)
(:index 3 :name "book.pdf" :mime-type "application/pdf"
:size 192220 :attachment t))
:references ("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-message-field} to shield you from some of the implementation
details that are subject to change; and see the other convenience functions in
@file{mu4e-message.el}.
Some notes on the format:
@itemize
@item The address fields are @emph{lists} of pairs @code{(name . email)},
where @t{name} can be nil.
@item The date is in format 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 calls @t{mu4e-proc-ping}, and registers a (lambda) function for
@t{mu4e-proc-pong-func}, to handle 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 is called, and it compares the version we got from the @t{pong}
with the version we expected, and raises an error, if they differ.
@node Logging and debugging
@appendix Logging and debugging
As explained in @ref{How it works}, @t{mu4e} communicates with its backend
(@t{mu server}) by sending commands and receiving responses (s-expressions).
For debugging purposes, it can be very useful to see this data. For this
reason, @t{mu4e} can log all these messages. Note that the 'protocol' is
documented to some extent in the @t{mu-server} manpage.
You can enable (and disable) logging with @t{M-x mu4e-toggle-logging}. The
log-buffer is called @t{*mu4e-log*}, and in the @ref{Main view}, @ref{Headers
view} and @t{Message view}, there's a keybinding @key{$} that takes you
there. You can quit it by pressing @key{q}.
Logging can be a bit resource-intensive, so you may not want to leave it on
all the time. By default, the log only maintains the most recent 1200 lines.
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
Something went wrong with that request. Please try again.