     [file version.texi not included]

Copyright © 2012 Dirk-Jan C. Binnema

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

mu4e Manual
***********

Welcome to mu4e!

mu4e (mu-for-emacs) is an e-mail client for GNU Emacs (version 23 and later). It is built on top of the mu e-mail search engine. This manual describes how to install and use mu4e.

This manual has been updated for mu/mu4e version mu4e-version.

Introduction
************

In this chapter some prelimary thoughs about the how and why of mu4e.

Why another e-mail client?
==========================

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

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

Other mail clients
==================

Under the hood, mu4e is fully search-based, similar to programs such as notmuch (http://notmuchmail.org), md (https://github.com/nicferrier/md) and sup (http://sup.rubyforge.org/). The user-interface is quite different though.

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

mu4e tries to keep all the 'state' in your maildirs, so one can switch between clients, synchronize over IMAP or backup with rsync -- if you delete the database, you won't lose any information.

What mu4e does and doesn't do
=============================

mu, and, by extension, mu4e, do not deal with getting your e-mail messages from a mail server; instead, this task is delegated to other tools, such as offlineimap (http://offlineimap.org/), isync (http://isync.sourceforge.net/) or fetchmail (http://www.fetchmail.info/). As long as the messages end up in a Maildir, mu4e/mu are happy to deal with them.

mu4e also does not implement sending messages; instead, it depends on the true-and-tested smtpmail, which is part of emacs. In addition, mu4e piggybacks on Gnus' message editor; see Gnus message editor (message).

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

Getting started
***************

In this chapter, we go through installing mu4e and see how to set it up. After we have succeeded in Getting mail, and Indexing your messages, we discuss Basic configuration.

After going through these steps, mu4e should be ready for use.

Installation
============

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

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

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

     sudo apt-get install libgmime-2.4-dev libxapian-dev
     # emacs if you don't have it yet
     sudo apt-get install emacs23
     # optional
     sudo apt-get install guile-2.0-dev html2text xdg-utils

Installation follows the normal sequence of:

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

After this, mu and mu4e should be installed  (there's a hard dependency between versions of mu4e and mu - you cannot combine different versions.), and be available from the command line and emacs (respectively). You may need to restart emacs so it can pick up mu4e.

mu4e and emacs customization
----------------------------

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

Getting mail
============

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

If you are using some external IMAP or POP server, you can use tools like getmail, offlineimap or isync to download your message into a Maildir-directory (~/Maildir, usually). If you are using a local mail-server (such as Postfix or qmail), you can teach them to deliver into a Maildir as well, maybe in combination with procmail. A bit of googling should be able to provide you with the details; also there is full example of setting mu4e up with offlineimap and Gmail; see Gmail configuration.

You can do all of the mail retrieval outside of emacs/mu4e, but you can also do it from the mu4e. For that, set the variable mu4e-get-mail-command to the command you want to use for retrieving mail, which you can then access from the Main view.

You can also have this command run periodically (in the background), by setting the variable mu4e-update-interval to the number of seconds between such updates. If set to nil, it will not update at all. Note that if you make changes to mu4e-update-interval, mu4e must be restarted before the change will take effect.

Indexing your messages
======================

After you have succeeded in Getting mail, we need to index the messages. That is - we need to scan the Maildir and store the information about the mails into a special database. We can do that from mu4e -- Main view, but this first time, it's better to run it from the command line, as it may be easier to recognize problems.

Assuming that your Maildir is at ~/Maildir, you should give the following command:

       $ mu index --maildir=~/Maildir

This should scan your ~/Maildir (In most cases, you do not even have to provide the --maildir=~/Maildir; see the mu-index man-page for details) and fill the database, and give progress information while doing so. The first time you index your mail may take a few minutes (for thousands of e-mails), afterwards it is much faster since it only has to scan the differences.

Note that indexing is discussed at length in the mu-index man page.

After the indexing is finished, you can quickly test if everything worked, by trying some command line searches, for example

       $ mu find hello

which should list all messages that match hello. For some more examples of searches see Queries, or check the mu-find and mu-easy man pages.

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

Sending mail
============

mu4e re-uses Gnu's message mode see message, for writing mail and inherits the setup for sending mail from that.

For sending mail using SMTP, mu4e uses Emacs' standard smtpmail package -- see 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 - and Example configuration.

A very minimal setup could look something like:

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

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

By default, mu4e puts a copy of any messages you sent in the folder you set for mu4e-sent-folder. In some case, this may not be what you want - for example, when using GMail+IMAP (but not with GMail+POP3), this interferes with GMail's handling of the sent messages folder, and you may end up with duplicate messages. For this, since mu4e 0.9.8.3, there is the variable mu4e-sent-messages-behavior, which takes a symbol. The default is 'sent which, as mentioned, causes the message to be copied to your sent-messages folder. Other possible values are 'trash (so the sent message is copied to the trash-folder (mu4e-trash-folder), and 'delete to simply discard the message altogether.

Thus, for GMail-IMAP you can add the following to your settings:

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

Queuing mail
============

If you cannot send mail directly, for example because you are currently offline, you can queue the mail, and send it when you have restored your internet connection. You can control this from the mu4e see Main view.

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

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

For convenience, we locate the queue directory somewhere in our normal Maildir. If you want to use queued mail, you should create this directory before starting mu4e. The mu mkdir command can be handy here, so for example:

$ mu mkdir ~/Maildir/queue
$ touch ~/Maildir/queue/.noindex

The touch command tells mu to ignore this directory for indexing, which makes sense since it contains smtpmail meta-data rather than 'normal' messages.

Also, see the mu-mkdir and mu-index man pages.

Warning: when you switch on queued-mode, your messages will not reach their destination until you switch it off again; so, be careful not to do so accidentally.

Basic configuration
===================

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

First, we need to load mu4e:

     (require 'mu4e)

Then, we need to tell mu4e where it can find your Maildir, and some special folders. So, for example:

       (setq
         mu4e-maildir       "~/Maildir"   ;; top-level Maildir
         mu4e-sent-folder   "/sent"       ;; where do i keep sent mail?
         mu4e-drafts-folder "/drafts"     ;; where do i keep half-written mail?
         mu4e-trash-folder  "/trash")     ;; where do i move deleted mail?

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

Running mu4e
************

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

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

     ----------------------------------------------------------------------------

             [C]     +--------+   [RFCE]
           --------> | editor | <--------
          /          +--------+          \
         /         [RFCE]^                \
        /                |                 \
     +-------+ [sjbB]+---------+  [RET] +---------+
     | main  | <---> | headers | <----> | message |
     +-------+  [q]  +---------+ [qbBjs]+---------+
                       [sjbB]                ^
                                         [.] | [q]
                                             V
                                           +-----+
                                           | raw |
                                           +-----+

     Default bindings
     ----------------
     R: Reply      s: search            .: raw view (toggle)
     F: Forward    j: jump-to-maildir   q: quit
     C: Compose    b: bookmark-search
     E: Edit       B: bookmark-search (edit-first)

     ----------------------------------------------------------------------------

Main view
=========

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

This looks something like the following:

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

  Basics

	* [j]ump to some maildir
	* enter a [s]earch query
	* [C]ompose a new message

  Bookmarks

	* [bu] Unread messages
	* [bt] Today's messages
	* [bw] Last 7 days
	* [bp] Messages with images
  Misc

	* [U]pdate email & database
	* toggle [m]ail sending mode (direct)
	* [f]lush queued mail

        * [H]elp
	* [q]uit mu4e
----------------------------------------------------------------------------

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

Basic actions
-------------

First, the Basics:

  * [j]ump to some maildir means that after pressing j, mu4e will ask you for a maildir to jump to. These are the maildirs you set in Basic configuration.

  * enter a [s]earch query means that after pressing s you will be asked for a search query, and after entering one, the results will be shown. See Searching.

  * [C]ompose a new message means that after pressing C, you will be thrown in a message-editing buffer, where you can compose a new message.

Bookmarks
---------

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

Miscellaneous
-------------

Finally, there are some Misc actions:

  * [U]pdate email & database will execute whatever is in the variable mu4e-get-mail-command, and afterwards update the mu database; see Indexing your messages. See Getting mail for details.

  * toggle [m]ail sending mode (direct) will toggle between sending mail directly, and queuing it first (for example, when you are offline), and [f]lush queued mail will flush any queued mail. This item is visible only if you have actually set up mail-queuing. See Queuing mail.

  * [H]elp will show help information for this view.

  * Finally, [q]uit mu4e will quit mu4e.

Headers view
============

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

This looks something like the following:

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

Some notes
----------

Some notes to explain what you see in the example:

  * The fields shown in the headers view can be influenced by customizing the variable mu4e-headers-fields

  * You can change the date format by customizing mu4e-headers-date-format

  * 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 From/To field shows the sender of the message unless the sender matches the regular expression in mu4e-user-mail-address-regexp, in which the header will show To followed by the recipient.

  * The subject field displays the discussion threads according to the JWZ mail threading algorithm (http://www.jwz.org/doc/threading.html).

Keybindings
-----------

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

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

d            mark for moving to the trash folder
DEL,D        mark for immediate deletion
m            mark for moving to another maildir folder
u            unmark message at point
R,F,C        reply/forward/compose
E            edit (only allowed for draft messages)

|            pipe message through shell command

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

H            get help
q,z          leave the headers buffer

Marking messages
----------------

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

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

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

Actions
-------

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

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

Split view
----------

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

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

You can influence the way the splitting works by setting the variable mu4e-split-view in your configuration to one of 3 values:

  * horizontal (this is the default): display the message view below the header view

  * vertical: display the message view on the right side of the header view

  * anything else: don't do any splitting

When splitting horizontally, you can determine the number of visible header lines with with the variable mu4e-headers-visible-lines (default value: 8). When split vertically you can use 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 p (or M-up) and n (or 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 mu4e-select-other-view, bound to y.

Message view
============

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

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

[....]
----------------------------------------------------------------------------

Some notes:

  * You can determine which header fields are shown by setting the variable mu4e-view-fields.

  * You can customize the date format by setting the variable mu4e-date-format-long, using the same format that format-time-string uses.

  * If you only want to see the name and not the e-mail address of the contacts in address fields, you can set mu4e-view-show-addresses to nil. This will hide the addresses for contacts that also have a name. The e-mail address is still available as a tool-tip.

  * The body text can be line-wrapped (toggle between wrapped/not-wrapped with w) and/or cited parts can be hidden (toggle between hidden/not-hidden with h. If you want to do this by default when viewing messages, you can set, respectively, mu4e-view-wrap-lines and mu4e-view-hide-cited to t.  (If you have installed the filladapt package (http://www.wonderworks.com/download/filladapt.el), mu4e will use it for line-wrapping, as it generally does a better job than the default mechanism emacs provides.)

Keybindings
-----------

You can find most things you can do with this message in the View menu, or by using the keyboard; the default bindings are:

key          description
---          -----------
n,p          go to next, previous message
y            select the headers view (if it's visible)

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

a            execute some action on the message

d            mark for moving to the trash folder
DEL,D        mark for immediate deletion
m            mark for moving to another maildir folder
u            unmark message at point
R,F,C        reply/forward/compose
E            edit (only allowed for draft messages)

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

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

H            get help
q,z          leave the message view

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

Opening and saving attachments
------------------------------

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

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

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

Actions
-------

mu4e-view-action (a) lets you pick some custom action to perform on the current message. You can specify these actions using the variable mu4e-view-actions.

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

By default, mu4e already offers a few useful actions for attachments:

  * open-with (w): open the attachment with some arbitrary program. For example, suppose you have received a message with a picture attachment; then, A w 1 RET gimp RET will open that attachment in The Gimp.

  * pipe (|: 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 diffstat program. You can use something like: A | 1 RET diffstat -b RET.

  * emacs (e): open the attachment in your running emacs . For example, if you receive some text file you'd like to open in emacs: A e 1 RET.

These actions all work on temporary copy of the attachment.

For more information about actions and how to define your own, see Actions.

Displaying rich-text messages
-----------------------------

For displaying messages, mu4e normally prefers the plain-text version for messages consisting of both a plain-text and an html (rich-text) version of its body-text. If there is only an html-version, or if the plaint-text version is too short in comparison with the html part, mu4e tries to convert the html into plain-text for display. The default way to do that is to use the Emacs built-in html2text function, but if you set the variable mu4e-html2text-command to some external program, that program will be used. This program is expected to take html from standard input and write plain text in utf-8 encoding on standard output.

An obvious choice for this is the program that is actually called html2text (http://www.mbayer.de/html2text/), which you could set up with something like the following in your initialization files:

     (setq mu4e-html2text-command "html2text -utf8 -width 72")

Normally, mu4e prefers the text-version of an e-mail message to determine the message body. You can change this by setting mu4e-view-prefer-html.

Editor view
===========

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

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

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

Some useful keybindings
-----------------------

key          description
---          -----------
C-c C-c      send message
C-c C-d      save to drafts and leave
C-c C-k      kill the message
C-c C-w      insert signature
C-c C-a      attach a file (pro-tip: drag & drop works as well)

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

Searching
*********

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

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

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

Queries
=======

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

# get all messages about bananas
bananas

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

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

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

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

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

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

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

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

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

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

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

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

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

Bookmarks
=========

If you have queries that you use often, you may want to store them as 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 Main view, header view see Headers view, and message view see Message view, using (by default) the key b (mu4e-search-bookmark).

Setting up bookmarks
--------------------

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

     (defvar mu4e-bookmarks
       '( ("flag:unread AND NOT flag:trashed" "Unread messages"      ?u)
          ("date:today..now"                  "Today's messages"     ?t)
          ("date:7d..now"                     "Last 7 days"          ?w)
          ("mime:image/*"                     "Messages with images" ?p))
       "A list of pre-defined queries; these will show up in the main
     screen. Each of the list elements is a three-element list of the
     form (QUERY DESCRIPTION KEY), where QUERY is a string with a mu
     query, DESCRIPTION is a short description of the query (this will
     show up in the UI), and KEY is a shortcut key for the query.")

You can replaces these, or add your own items, by putting in your configuration (~/.emacs) something like:

     (add-to-list 'mu4e-bookmarks
       '("size:5M..500M"       "Big messages"     ?b))

This prepends your bookmark to the list, and assigns the key b to it. If you want to append your bookmark, you can use t as the third argument to add-to-list.

In the various mu4e views, pressing b will list all the bookmarks defined in the echo area, with the shortcut key highlighted. So, to invoke the bookmark we just defined (to get the list of "Big Messages"), all you need to type is bb.

Editing bookmarks before searching
----------------------------------

There is also mu4e-search-bookmark-edit-first (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 "NOT maildir:/Trash AND" (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 Bt (using the Today's messages-bookmark, see above).

Maildir searches
================

Maildir searches are quite similar to bookmark searches (see Bookmarks), with the difference being that the target is always a maildir -- maildir queries provide a 'traditional' folder-like interface to a search-based e-mail client. By default, maildir searches are available in the Main view, Headers view, and Message view, with the key j (mu4e-jump-to-maildir).

Setting up maildir shortcuts
----------------------------

You can do Maildir searches manually (e.g. with a query like maildir:/myfolder) but since it is so common, mu4e offers a quicker way to do this.

To enable this, you need to set the variable mu4e-maildir-shortcuts to list of maildirs you'd like to have quick access to, for example:

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

This would set i as a shortcut for the /inbox folder; so effectively a query maildir:/inbox. There is a special shortcut o for other (so don't use that one for your own shortcuts!), which allows you to choose from all maildirs.

Each of the folder names is relative to your top-level maildir directory; so if you keep your mail in ~/Maildir, /inbox would refer to ~/Maildir/inbox.

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

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

Actions
*******

mu4e allows you to define custom actions for messages in the Headers view and for both messages and attachments in the Message view. Custom actions allow you to easily extend 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 a for actions on messages, and A for actions on attachments. In the following, we'll gives some examples of defining actions.

Functions for actions
---------------------

Defining a new custom action means that you need to write an elisp-function to do the work. Functions that operate on messages look like:

     (defun my-action-func (msg)
      "Describe my func."
     ;; do stuff
     )

Messages that operate on attachments look like:

     (defun my-attachment-action-func (msg attachment-num)
      "Describe my func."
     ;; do stuff
     )

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

Let's now look at some simple examples.

Example: adding an action in the headers view
---------------------------------------------

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

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

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

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

Example: adding an action in the message view
---------------------------------------------

As another example, suppose we would like to search for messages by the sender of this message.

     (defun search-for-sender (msg)
       "Search for messages sent by the sender of the current one."
       (mu4e-search (concat "from:" (cdar (mu4e-msg-field msg :from)))))

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

Example: adding an attachment action
------------------------------------

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

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

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

What functions are available?
-----------------------------

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 mu4e marked for internal use have the prefix mu4e~, while all the public ones use mu4e-. The ~ was chosen because its ascii-code is after all the letters, so they will only appear at the end of completion buffers and the like.

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

Interaction with other tools
****************************

In this chapter we discuss some ways in ways in which mu4e can cooperate with other tools.

Setting the default emacs mail program
======================================

emacs allows you to select an e-mail program as the default program it will use when you press C-x m (compose-mail), call report-emacs-bug and so on.

If you want to use mu4e for this, you do so by adding the following to your configuration:

     (setq mail-user-agent 'mu4e-user-agent)

At the present time, support is still experimental.

Creating org-mode links
=======================

It can be useful to include links to e-mail messages or even search queries in your org-mode files. mu4e supports this with the org-mu4e module; you can set it up by adding it to your configuration:

     (require 'org-mu4e)

After this, you can use the normal org-mode mechanisms to store links: M-x org-store-link will store a link to a particular message when you're in Message view (Message view), and a link to a query when you are in Headers view (Headers view). You can insert these link later with M-x org-insert-link. Then, you can go to the query or message the link points to with either M-x org-agenda-open-link in agenda buffers, or M-x org-open-at-point elsewhere - both are typically bound to C-c C-o.

Maintaining an address-book with org-contacts
=============================================

To manage your addresses using org-mode, there is org-contacts (http://julien.danjou.info/software/org-contacts.el).

You can use it with a capture-template:
("c" "contacts" entry (file "contacts.org")
"* %(mu4e-view-snarf-from 'name)
:PROPERTIES:
:EMAIL: %(mu4e-view-snarf-from 'email)
:NICK:
:BIRTHDAY:
:END:\n\n")

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

Getting new mail notifications with Sauron
==========================================

The emacs-package Sauron (Sauron can be found at https://github.com/djcb/sauron, or in the Marmalade package-repository at 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 crontab (or have some other way of having it execute every n minutes, you will receive notifications in the sauron-buffer when new messages arrive.

#!/bin/sh
# put the path to your Inbox folder here

CHECKDIR="/home/$LOGNAME/Maildir/Inbox"
sauron-msg () {
    DBUS_COOKIE="/home/$LOGNAME/.sauron-dbus"
    if test "x$DBUS_SESSION_BUS_ADDRESS" = "x"; then
        if test -e $DBUS_COOKIE; then
                export DBUS_SESSION_BUS_ADDRESS="`cat $DBUS_COOKIE`"
        fi
    fi
    if test -n "x$DBUS_SESSION_BUS_ADDRESS"; then
        dbus-send --session                 \
            --dest="org.gnu.Emacs"        \
            "/org/gnu/Emacs/Sauron"                \
            "org.gnu.Emacs.Sauron.AddMsgEvent"      \
            string:shell uint32:3 string:"$1"
    fi
}

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

Note, you should put something like:

     (setq sauron-dbus-cookie t)

in your setup, which allows the script to find the D-Bus session bus.

Speedbar support
================

speedbar is an emacs-extension that shows navigational information for an emacs buffer in a separate frame. Using mu4e-speedbar, mu4e lists your bookmarks and maildir folders and allows for one-click access to them.

mu4e loads mu4e-speedbar automatically; all you need to do to activate it is M-x speedbar. Then, when then going to the Main view, the speedbar-frame will be updated with your bookmarks and maildirs.

mu4e-speedbar was contributed by Antono Vasiljev.

Citations with mu-cite
======================

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

mu-cite is a package to control the way message citations look like (i.e., the message you responded to when you reply to them or forward them), with its latest version available at http://www.jpl.org/elips/mu/.

After installation of the mu-cite, you can use something like the following to make it work with mu4e:

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

Example configuration
*********************

In this chapter, we show some example configurations.

Minimal configuration
=====================

An (almost) minimal configuration for mu4e might look something like this:

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

     ;; happily, below settings are all /optional/

     ;; Only needed if your maildir is _not_ ~/Maildir
     ;;(setq mu4e-maildir "/home/user/Maildir")

     ;; these must start with a "/", and must exist
     ;; (i.e.. /home/user/Maildir/sent must exist)
     ;; you use e.g. 'mu mkdir' to make the Maildirs if they don't
     ;; already exist

     ;; below are the defaults; if they do not exist yet, mu4e will offer to
     ;; create them
     ;; (setq mu4e-sent-folder   "/sent")
     ;; (setq mu4e-drafts-folder "/drafts")
     ;; (setq mu4e-trash-folder  "/trash")

     ;; for the settings for outgoing mail consult the section 'Longer configuration'

Longer configuration
====================

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

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

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

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

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

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

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

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

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

        ;; smtp mail setting
        message-send-mail-function 'smtpmail-send-it
        smtpmail-default-smtp-server "smtp.example.com"
        smtpmail-smtp-server ""smtp.example.com"
        smtpmail-local-domain "example.com"

        ;; if you need offline mode, set these -- and create the queue dir
        ;; with 'mu mkdir', i.e.. mu mkdir /home/user/Maildir/queue
        smtpmail-queue-mail  nil
        smtpmail-queue-dir   "/home/user/Maildir/queue/cur")

Gmail configuration
===================

Gmail is a popular e-mail provider; let's see how we can make it work with mu4e.

First of all, we need a program to get the e-mail from Gmail on our local machine; for this we use offlineimap; on Debian (and derivatives like Ubuntu), this is as easy as:
sudo apt-get install offlineimap

Then, create a configuration for offlineimap, i.e. a file ~/.offlineimaprc:

[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

Of course, you need replace USERNAME and PASSWORD with your actual GMail username and password.

After this, you should be able to download your mail:
$ 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

We can now run mu to make sure things work:

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

Note that we can run both the offlineimap and the mu index from within mu4e, but running it from the command line makes it a bit easier to see what is going on.

Now, let's make a mu4e configuration for this:

     (require 'mu4e)

     ;; default
     ;; (setq mu4e-maildir (expand-file-name "~/Maildir"))

     (setq mu4e-drafts-folder "/[Gmail].Drafts")
     (setq mu4e-sent-folder   "/[Gmail].Sent Mail")
     (setq mu4e-trash-folder  "/[Gmail].Trash")

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

     ;; setup some handy shortcuts
     (setq mu4e-maildir-shortcuts
         '( ("/INBOX"               . ?i)
            ("/[Gmail].Sent Mail"   . ?s)
            ("/[Gmail].Trash"       . ?t)
            ("/[Gmail].All Mail"    . ?a)))

     ;; allow for updating mail using 'U' in the main view:
     (setq mu4e-get-mail-command "offlineimap")

     ;; something about ourselves
     (setq
        user-mail-address "USERNAME@gmail.com"
        user-full-name  "Foo X. Bar"

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

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

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

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

Using these setting 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.

FAQ - Frequently Anticipated Questions
**************************************

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

  * How can I quickly delete/move/trash a lot of messages? You can select ('mark' in emacs-speak) the messages; the actions you then take (e.g., DEL for delete, m for move and t for trash) will apply to all selected messages

  * How can I use BBDB? Currently, there is no built-in for address management with BBDB; instead, we recommend Maintaining an address-book with org-contacts for now.

  * mu4e only seems to return a subset of all matches - how can I get all?. Yes, for speed reasons (and because, if you are like the author, you usually don't need thousands of matches), mu4e returns only up to the value of the variable m4ue-search-result-limit matches. You can customize that variable, or simply press the emacs prefix C-u before your search command to get all matches. In other words, when you press C-u s hello you will get all matches, while s hello only gets you up-to-a-limited-number matches. Same for the other search based commands, mu4e-jump-to-maildir (default: j) and mu4e-search-bookmark (default: b).

  * How can I easily include attachments in the messages I write? Drag-and-drop.

  * When I try do run mu index while mu4e is running I get errors like 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 mu4e can do about this, but what you can do is telling mu to (gracefully) terminate:
        pkill -2 -u $UID mu # send SIGINT
        sleep 1
        mu index
     mu4e will automatically restart mu when it needs it. In practice, this seems to work quite well.

  * Can I automatically execute the actions on marked messages when leaving the headers buffer? Yes you can -- see the documentation on mu4e-headers-leave-behavior.

  * Can I automatically apply word-wrapping (and hiding cited parts) when viewing a message? Yes -- see the documentation on mu4e-view-wrap-lines (and mu4e-view-hide-cited). You can always toggle between the two states with w and h, respectively.

  * Is there context-sensitive help available? Yes - pressing H in most cases should point you to the right spot in this manual.

  * How can I set mu4e as the default e-mail client in emacs? See Setting the default emacs mail program.

  * How can I perform custom actions on messages and attachments? See Actions.

Known issues / missing features
*******************************

In this chapter we list a number of known issue and/or missing features in 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.

  * Thread handling is incomplete. While threads are calculated and are visible in the headers buffer, there is no functionality to manipulate them (e.g., collapse the thread, or delete a whole thread at once). But note that you can manipulate a number of consecutive messages at once by selecting them, and then using one of the manipulation commands, such as mu4e-mark-for-move or mu4e-mark-for-delete.

  * No support for crypto when reading mail. Currently, you cannot conveniently read encrypted mail or check signatures. For outgoing messages, it should work though, using the built-in mechanisms.

  * One cannot influence the sorting of messages. Messages are sorted according to thread, then descending by date. It would be nice if it could be sorted in other ways as well.

  * mu4e gets confused when there are multiple windows showing the headers.. Yes -- don't do that.

  * Messages in the sent-folder do not include the attachments you sent. Same for the drafts-folder.

  * The key-bindings are somewhat hard-coded That is, the main menu assumes the default key-bindings, as do the clicks-on-bookmarks.

  * Attachments are not accessible in draft/sent messages. Currently, attachments in saved messages are special strings, which are transformed into the actual attachments when sending. However, you cannot access them afterwards.

How it works
************

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

High-level overview
===================

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

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

In words:

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

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

  * mu4e, which runs inside emacs is such a client; it communicates with mu (in its server-mode to search for messages, and manipulate them.

  * mu4e uses the facilities offered by emacs (the Gnus message editor and smtpmail) to send messages.

mu server
=========

mu4e is based on the 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 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 -- mu4e would invoke e.g., mu find and process the output in emacs.

However, with approach, we need to load the entire e-mail Xapian database (in which the message is stored) for each invocation. Wouldn't it be nicer to keep a running mu instance around?  Indeed, it would - and thus, the mu server sub-command was born. Running mu server, you get a sort-of shell, in which you can give commands to mu, which will then spit out the results/errors. mu server is not meant for humans, but it can be used manually, which is great for debugging.

Reading from the server
=======================

In the design, the next question was what format mu should use for its output for mu4e (emacs) to process. Some other programs use JSON here, but it seemed easier (and possibly, more efficient) just to talk to emacs in its native language: s-expressions (to be precise: plists), and interpret those using the emacs-function read-from-string. See The message s-expression for details on the format.

So, now let's look how we process the data from mu server in emacs. We'll leave out a lot of detail, mu4e-specifics, and look at a bit more generic approach.

The first is to create a process with, for example, start-process, and then register a filter function for it, which will be invoked whenever the process has some chunk of output. Something like:

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

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 mu4e it looks something like (pseudo-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>))

<evaluate-expression> de-multiplexes the s-expression we got. For example, if the s-expression looks like an e-mail message header, it will be processed by the header-handling function, which will append it to the header list. If the s-expression looks like an error message, it will be reported to the user. And so on.

The language between frontend and backend is documented in the mu-server man-page. mu4e can log these communications; you can use M-x mu4e-toggle-logging to turn logging on and off, and you can view the log using M-x mu4e-show-log.

The message s-expression
========================

A typical message s-expression could look something like the following:

     (:docid 32461
      :from (("Nikola Tesla" . "niko@example.com"))
      :to (("Thomas Edison" . "tom@example.com"))
      :cc (("Rupert The Monkey" . "rupert@example.com"))
      :subject "RE: what about the 50K?"
      :date (20369 17624 0)
      :size 4337
      :message-id "6BDC23465F79238C8233AB82D81EE81AF0114E4E74@123213.mail.example.com"
      :path  "/home/tom/Maildir/INBOX/cur/133443243973_1.10027.atlas:2,S"
      :maildir "/INBOX"
      :priority normal
      :flags (seen)
      :attachments ((:index 2 :name "photo.jpg" :mime-type "image/jpeg" :size 147331)
                    (:index 3 :name "book.pdf" :mime-type "application/pdf" :size 192220))
      :references  ("6BDC23465F79238C8384574032D81EE81AF0114E4E74@123213.mail.example.com"
      "6BDC23465F79238203498230942D81EE81AF0114E4E74@123213.mail.example.com")
      :in-reply-to "6BDC23465F79238203498230942D81EE81AF0114E4E74@123213.mail.example.com"
      :body-txt "Hi Tom,
      ....
     "))

This s-expression forms a property list (plist), and we can get values from it using plist-get; for example (plist-get msg :subject) would get you the message subject. However, it's better to use the function mu4e-msg-field to shield you from some of the implementation details that are subject to change.

Some notes on the format:

  * The address fields are lists of pairs (name . email), where name can be nil.

  * The date is in format emacs uses (for example in current-time). (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 time_t in two numbers.)

  * Attachments are a list of elements with fields :index (the number of the MIME-part), :name (the file name, if any), :mime-type (the MIME-type, if any) and :size (the size in bytes, if any).

  * Messages in the Headers view come from the database and do not have :attachments. :body-txt or :body-html fields. Message in the Message view use the actual message file, and do include these fields.

Example: ping-pong
------------------

As an example of this, let's look at the ping-pong-sequence. When mu4e starts, it sends a command ping to the the mu server backend, to learn about its version. mu server then responds with a pong s-expression to provide this information (this is implemented in mu-cmd-server.c).

We start this sequence when mu4e is invoked (when the program is started). It call mu4e-proc-ping, and registers a (lambda) function for mu4e-proc-pong-func, so it will retrieve the response.

-> ping
<- (pong "mu" :version "x.x.x" :doccount 10000)

When we receive such a pong (in mu4e-proc.el), the lambda function we registered will be called, and it check the version we got from the pong with the version we expected, and raises an error, if they differ.

Logging and debugging
*********************

As explained in How it works, mu4e communicates with its backend (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, mu4e can log all these messages. Note that the 'protocol' is documented to some extent in the mu-server manpage.

You can enable (and disable) logging with M-x mu4e-toggle-logging. The log-buffer is called *mu4e-log-buffer*, and in the Main view, Headers view and Message view, there's a keybinding $ that will take you there. You can quit it by pressing 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, mu itself keeps a log as well, you can find this it in <MUHOME>/log/mu.log, typically ~/.mu/log/mu.log.

GNU Free Documentation License
******************************

     [file fdl.texi not included]