opfez
/
.emacs.d
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
.emacs.d/elisp/mu4e/mu4e.info

5824 lines
230 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This is mu4e.info, produced by makeinfo version 6.7 from mu4e.texi.
Copyright © 2012-2020 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.”
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Mu4e: (Mu4e). An email client for GNU Emacs.
END-INFO-DIR-ENTRY

File: mu4e.info, Node: Top, Next: Introduction, Up: (dir)
mu4e manual
***********
Welcome to mu4e 1.6.1.
mu4e (mu-for-emacs) is an e-mail client for GNU Emacs version 24.4 or
higher, built on top of the mu(1) e-mail search engine. mu4e is
optimized for quickly processing large amounts of e-mail.
Some of its highlights:
• Fully search-based: there are no folders(2), only queries.
• Fully documented, with example configurations
• User-interface optimized for speed, with quick key strokes for
common actions
• Support for non-English languages (so “angstrom” matches
“Ångström”)
• Asynchronous: heavy actions don’t block emacs(3)
• Support for cryptography — signing, encrypting and decrypting
• Address auto-completion based on the contacts in your messages
• Extendable with your own snippets of elisp
In this manual, we go through the installation of mu4e, do some basic
configuration and explain its daily use. We also show you how you can
customize mu4e for your special needs.
At the end of the manual, there are some example configurations, to
get you up to speed quickly: *note Example configs::. There’s also a
section with answers to frequently asked questions, *note FAQ::.
* Menu:
* Introduction:: Where to begin
* Getting started:: Setting things up
* Main view:: The mu4e overview
* Headers view:: Lists of message headers
* Message view:: Viewing specific messages
* Editor view:: Creating and editing messages
* Searching:: Some more background on searching/queries‘
* Marking:: Marking messages and performing actions
* Contexts:: Defining contexts and switching between them
* Dynamic folders:: Folders that change based on circumstances
* Actions:: Defining and using custom actions
* Extending mu4e:: Writing code for mu4e
Appendices
* Old message view:: The old way to view messages
* Other tools:: mu4e and the rest of the world
* Example configs:: Some examples to set you up quickly
* FAQ:: Common questions and answers
* Tips and Tricks:: Useful tips
* How it works:: Some notes about the implementation of mu4e
* Debugging:: How to debug problems in mu4e
* GNU Free Documentation License:: The license of this manual
---------- Footnotes ----------
(1) <https://www.djcbsoftware.nl/code/mu>
(2) that is, instead of folders, you use queries that match messages
in a particular folder
(3) currently, the only exception to this is _sending mail_; there
are solutions for that though — see the *note FAQ::

File: mu4e.info, Node: Introduction, Next: Getting started, Prev: Top, Up: Top
1 Introduction
**************
Let’s get started!
* Menu:
* Why another e-mail client::Aren’t there enough already
* Other mail clients::Where mu4e takes its inspiration from
* What mu4e does not do::Focus on the core-business, delegate the rest
* Becoming a mu4e user::Joining the club

File: mu4e.info, Node: Why another e-mail client, Next: Other mail clients, Up: Introduction
1.1 Why another e-mail client?
==============================
I (mu4e’s author) spend a _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
thought about creating my own.
Emacs is an integral part of my workflow, so it made a lot of sense
to use it for e-mail as well. And as I had already written an e-mail
search engine (mu), it seemed only logical to use that as a basis.

File: mu4e.info, Node: Other mail clients, Next: What mu4e does not do, Prev: Why another e-mail client, Up: Introduction
1.2 Other mail clients
======================
Under the hood, mu4e is fully search-based, similar to programs like
notmuch(1) and sup(2).
However, mu4e’s user-interface is quite different. mu4e’s mail
handling (deleting, moving, etc.) is inspired by Wanderlust(3) (another
Emacs-based e-mail client), mutt(4) and the dired file-manager for
emacs.
mu4e keeps all the ‘state’ in your maildirs, so you can easily switch
between clients, synchronize over IMAP, backup with rsync and so on.
The Xapian-database that mu maintains is merely a _cache_; if you delete
it, you won’t lose any information.
---------- Footnotes ----------
(1) <https://notmuchmail.org/>
(2) <https://sup-heliotrope.github.io/>
(3) <http://www.gohome.org/wl/>
(4) <http://www.mutt.org/>

File: mu4e.info, Node: What mu4e does not do, Next: Becoming a mu4e user, Prev: Other mail clients, Up: Introduction
1.3 What mu4e does not do
=========================
There are a number of things that mu4e does not do, by design:
• mu/mu4e do _not_ get your e-mail messages from a mail server. Nor
does it sync-back any changes. Those tasks are delegated to other
tools, such as offlineimap(1), isync/mbsync(2) or fetchmail(3); As
long as the messages end up in a maildir, mu4e and mu are happy to
deal with them.
• mu4e also does _not_ implement sending of messages; instead, it
depends on smtpmail (*note (smtpmail)Top::), which is part of
Emacs. In addition, mu4e piggybacks on Gnus’ message editor; *note
(message)Top::.
Thus, many of the things an e-mail client traditionally needs to do,
are delegated to other tools. This leaves mu4e to concentrate on what
it does best: quickly finding the mails you are looking for, and handle
them as efficiently as possible.
---------- Footnotes ----------
(1) <https://www.offlineimap.org/>
(2) <http://isync.sourceforge.net/>
(3) <http://www.fetchmail.info/>

File: mu4e.info, Node: Becoming a mu4e user, Prev: What mu4e does not do, Up: Introduction
1.4 Becoming a mu4e user
========================
If mu4e sounds like something for you, give it a shot! We’re trying
hard to make it as easy as possible to set up and use; and while you can
use elisp in various places to augment mu4e, a lot of knowledge about
programming or elisp shouldn’t be required. The idea is to provide
sensible defaults, and allow for customization.
When you take mu4e into use, it’s a good idea to subscribe to the
mu/mu4e-mailing list(1).
Sometimes, you might encounter some unexpected behavior while using
mu4e. It could be a bug in mu4e, it could be an issue in other
software. Or it could just be a misunderstanding. In any case, if you
want to report this (either to the mailing list or to
<https://github.com/djcb/mu/issues>, the latter is preferred), please
always include the following information:
• what did you expect that should happen? what actually happened?
• can you provide some exact steps to reproduce?
• what version of mu4e and emacs were you using? What operating
system?
• can you reproduce it with ‘emacs -q’ and only loading mu4e?
• if the problem is related to some specific message, please include
the raw message file (appropriately anonymized, of course)
---------- Footnotes ----------
(1) <https://groups.google.com/group/mu-discuss>

File: mu4e.info, Node: Getting started, Next: Main view, Prev: Introduction, Up: Top
2 Getting started
*****************
In this chapter, we go through the installation of mu4e and its basic
setup. After we have succeeded in *note Getting mail::, and *note
Indexing your messages::, we discuss the *note Basic configuration::.
After these steps, mu4e should be ready to go!
* Menu:
* Requirements:: What is needed
* Installation:: How to install mu and mu4e
* Getting mail:: Getting mail from a server
* Initializing the message store:: Settings things up
* Indexing your messages:: Creating and maintaining the index
* Basic configuration:: Settings for mu4e
* Folders:: Setting up standard folders
* Retrieval and indexing:: Doing it from mu4e
* Sending mail:: How to send mail
* Running mu4e:: Overview of the mu4e views

File: mu4e.info, Node: Requirements, Next: Installation, Up: Getting started
2.1 Requirements
================
mu/mu4e are known to work on a wide variety of Unix- and Unix-like
systems, including many Linux distributions, OS X and FreeBSD, and even
on MS-Windows (with Cygwin). Emacs 24 or higher is required, as well as
Xapian(1) and GMime(2).
mu has optional support for both versions 2.2 and 3.0 of the Guile
(Scheme) programming language. There are also some GUI-toys, which
require GTK+ 3.x and Webkit.
If you intend to compile mu yourself, you need to have the typical
development tools, such as C and C++ compilers (both ‘gcc’ and ‘clang’
should work), GNU Autotools and ‘make’, and the development packages for
GMime 3.x, GLib and Xapian. Optionally, you also need the development
packages for GTK+, Webkit and Guile.
---------- Footnotes ----------
(1) <https://xapian.org/>
(2) <http://spruce.sourceforge.net/gmime/>

File: mu4e.info, Node: Installation, Next: Getting mail, Prev: Requirements, Up: Getting started
2.2 Installation
================
mu4e is part of mu — by installing the latter, the former is installed
as well. Some Linux distributions provide packaged versions of mu/mu4e;
if you can use those, there is no need to compile anything yourself.
However, if there are no packages for your distribution, if they are
outdated, 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; the
details depend on your distribution. If you’re using another
distribution (or another OS), the below can at least be helpful in
identifying the packages to install.
We provide some instructions for Debian, Ubuntu and Fedora; if those
do not apply to you, you can follow either *note Building from a release
tarball:: or *note Building from git::.
2.2.1 Dependencies for Debian/Ubuntu
------------------------------------
$ sudo apt-get install libgmime-3.0-dev libxapian-dev
# get emacs 25 or higher if you don't have it yet
$ sudo apt-get install emacs
# optional
$ sudo apt-get install guile-2.2-dev html2text xdg-utils
# optional: only needed for msg2pdf and mug (toy gtk+ frontend)
$ sudo apt-get install libwebkitgtk-3.0-dev
2.2.2 Dependencies for Fedora
-----------------------------
$ sudo yum install gmime30-devel xapian-core-devel
# get emacs 25 or higher if you don't have it yet
$ sudo yum install emacs
# optional
$ sudo yum install html2text xdg-utils guile22-devel
# optional: only needed for msg2pdf and mug (toy gtk+ frontend)
$ sudo yum install webkitgtk3-devel
2.2.3 Building on Msys2
-----------------------
# 1) install makepkg tool
pacman -S base-devel msys-devel gcc git
# 2) clone packages repo
cd ~
git clone https://github.com/msys2-unofficial/MSYS2-packages.git --depth=1
# make and install dependencies
cd ~/MSYS2-packages/xapian-core
makepkg -s
pacman -U xapian-core-1.4.15-1-x86_64.pkg.tar.xz
cd ~/MSYS2-packages/gmime3
makepkg -s
pacman -U gmime3-devel-3.2.6-1-x86_64.pkg.tar.xz
# 4) make and install mu from git (changes versions as needed)
cd ~/MSYS2-packages/mu
makepkg -sfp PKGBUILD-git
pacman -U mu-git-2020-03-01-r4854.17f38dc4-1-x86_64.pkg.tar.xz
2.2.4 Building from a release tarball
-------------------------------------
Using a release-tarball (as available from GitHub(1)), installation
follows the typical steps:
$ tar xvfz mu-<version>.tar.gz # use the specific version
$ cd mu-<version>
# On the BSDs: use gmake instead of make
$ ./configure && make
$ sudo make install
Xapian, GMime and their dependencies must be installed.
2.2.5 Building from git
-----------------------
Alternatively, if you build from the git repository or use a tarball
like the ones that github produces, the instructions are slightly
different, and require you to have autotools (autoconf, automake,
libtool, texinfo) installed:
# get from git (alternatively, use a github tarball)
$ git clone git://github.com/djcb/mu.git
$ cd mu
$ ./autogen.sh && make
# On the BSDs: use gmake instead of make
$ sudo make install
(Xapian, GMime and their dependencies must be installed).
After this, mu and mu4e should be installed (2) on your system, and
be available from the command line and in Emacs.
You may need to restart Emacs, so it can find mu4e in its
‘load-path’. If, even after restarting, Emacs cannot find mu4e, you may
need to add it to your ‘load-path’ explicitly; check where mu4e is
installed, and add something like the following to your configuration
before trying again:
;; the exact path may differ --- check it
(add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e")
2.2.6 Building using the meson build system
-------------------------------------------
As an (experimental) alternative to the autotools-build, it is possible
to use the Meson(3) build-system instead.
$ git clone git://github.com/djcb/mu.git
$ cd mu
$ meson build && ninja -C build
$ sudo ninja -C install
2.2.7 mu4e and emacs customization
----------------------------------
There is some support for using the Emacs customization system in mu4e,
but for now, we recommend setting the values manually. Please refer to
*note Example configs:: for a couple of examples of this; here we go
through things step-by-step.
---------- Footnotes ----------
(1) <https://github.com/djcb/mu/releases>
(2) there’s a hard dependency between versions of mu4e and mu — you
cannot combine different versions
(3) <https://mesonbuild.com/>

File: mu4e.info, Node: Getting mail, Next: Initializing the message store, Prev: Installation, Up: Getting started
2.3 Getting mail
================
In order for mu (and, by extension, mu4e) to work, you need to have your
e-mail messages stored in a _maildir_(1) — a specific directory
structure with one-file-per-message.
If you are already using a maildir, you are lucky. If not, some
setup is required:
• _Using an external IMAP or POP server_ — if you are using an IMAP
or POP server, you can use tools like getmail, fetchmail,
offlineimap or isync to download your messages into a maildir
(‘~/Maildir’, often). Because it is such a common case, there is a
full example of setting mu4e up with offlineimap and Gmail; *note
Gmail configuration::.
• _Using a local mail server_ — 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.
The maildir must be on a single file-system; and symbolic links are
not supported.
---------- Footnotes ----------
(1) <https://en.wikipedia.org/wiki/Maildir>; in this manual we use
the term ‘maildir’ for both the standard and the hierarchy of maildirs
that store your messages

File: mu4e.info, Node: Initializing the message store, Next: Indexing your messages, Prev: Getting mail, Up: Getting started
2.4 Initializing the message store
==================================
The first time you run mu, you need to initialize its store (database).
The default location for that is ~/.cache/mu/xapian, but you can change
this using the --muhome option, and remember to pass that to the other
commands as well.
Assuming that your maildir is at ‘~/Maildir’, we issue the following
command:
$ mu init --maildir=~/Maildir
Optionally, you can add some e-mail addresses, so mu recognizes them
as yours:
$ mu init --maildir=~/Maildir --my-address=jim@example.com --my-address=bob@example.com
mu remembers the maildir and your addresses and uses them when
indexing messages. If you want to change them, you need to init once
again.
If you want to see the current values, you can use ‘mu info’.

File: mu4e.info, Node: Indexing your messages, Next: Basic configuration, Prev: Initializing the message store, Up: Getting started
2.5 Indexing your messages
==========================
After you have succeeded in *note Getting mail:: and initialized the
message database, we need to _index_ the messages. That is — we need to
scan the messages in the maildir and store the information about them in
a special database.
We can do that from mu4e — *note Main view::, but the first time, it
is a good idea to run it from the command line, which makes it easier to
verify that everything works correctly.
Assuming that your maildir is at ‘~/Maildir’, we issue the following
command:
$ mu index
This should scan your messages 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 mu only
scans messages that are new or have changed. Indexing is discussed in
full detail in the 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
$ mu find hello
which lists all messages that match hello. For more examples of
searches, see *note Queries::, or check the mu-find and mu-easy man
pages. If all of this worked well, we are well on our way setting
things up; the next step is to do some basic configuration for mu4e.

File: mu4e.info, Node: Basic configuration, Next: Folders, Prev: Indexing your messages, Up: Getting started
2.6 Basic configuration
=======================
Before we can start using mu4e, we need to tell Emacs to load it. So,
add to your ‘~/.emacs’ (or its moral equivalent, such as
‘~/.emacs.d/init.el’) something like:
(require 'mu4e)
If Emacs complains that it cannot find mu4e, check your ‘load-path’
and make sure that mu4e’s installation directory is part of it. If not,
you can add it:
(add-to-list 'load-path MU4E-PATH)
with MU4E-PATH replaced with the actual path.

File: mu4e.info, Node: Folders, Next: Retrieval and indexing, Prev: Basic configuration, Up: Getting started
2.7 Folders
===========
The next step is to tell mu4e where it can find your Maildir, and some
special folders.
So, for example(1):
;; these are actually the defaults
(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
Note, the folder names are all relative to the root-maildir (see the
output of ‘mu info’). If you use mu4e-context, see *note Contexts and
special folders:: for what that means for these special folders.
---------- Footnotes ----------
(1) Note that the folders (mu4e-sent-folder, mu4e-drafts-folder,
mu4e-trash-folder and mu4e-refile-folder) can also be _functions_ that
are evaluated at runtime. This allows for dynamically changing them
depending on the situation. See *note Dynamic folders:: for details.

File: mu4e.info, Node: Retrieval and indexing, Next: Sending mail, Prev: Folders, Up: Getting started
2.8 Retrieval and indexing with mu4e
====================================
As we have seen, we can do all of the mail retrieval _outside_ of
Emacs/mu4e. However, you can also do it from within mu4e.
2.8.1 Basics
------------
To set up mail-retrieval from within mu4e, set the variable
‘mu4e-get-mail-command’ to the program or shell command you want to use
for retrieving mail. You can then get your e-mail using ‘M-x
mu4e-update-mail-and-index’, or ‘C-S-u’ in all mu4e-views;
alternatively, you can use ‘C-c C-u’, which may be more convenient if
you use emacs in a terminal.
You can kill the (foreground) update process with ‘q’.
It is possible to update your mail and index periodically in the
background or foreground, by setting the variable ‘mu4e-update-interval’
to the number of seconds between these updates. If set to ‘nil’, it
won’t update at all. After you make changes to ‘mu4e-update-interval’,
mu4e must be restarted before the changes take effect. By default, this
will run in background and to change it to run in foreground, set
‘mu4e-index-update-in-background’ to ‘nil’.
2.8.2 Handling errors during mail retrieval
-------------------------------------------
If the mail-retrieval process returns with a non-zero exit code, mu4e
shows a warning (unless ‘mu4e-index-update-error-warning’ is set to
‘nil’), but then try to index your maildirs anyway (unless
‘mu4e-index-update-error-continue’ is set to ‘nil’).
Reason for these defaults is that some of the mail-retrieval programs
may return non-zero, even when the updating process succeeded; however,
it is hard to tell such pseudo-errors from real ones like ‘login
failed’.
If you need more refinement, it may be useful to wrap the
mail-retrieval program in a shell-script, for example fetchmail returns
1 to indicate ‘no mail’; we can handle that with:
(setq mu4e-get-mail-command "fetchmail -v || [ $? -eq 1 ]")
A similar approach can be used with other mail retrieval programs,
although not all of them have their exit codes documented.
2.8.3 Implicit mail retrieval
-----------------------------
If you don’t have a specific command for getting mail, for example
because you are running your own mail-server, you can leave
‘mu4e-get-mail-command’ at "true" (the default), in which case mu4e
won’t try to get new mail, but still re-index your messages.
2.8.4 Speeding up indexing
--------------------------
If you have a large number of e-mail messages in your store,
(re)indexing might take a while. The defaults for indexing are to
ensure that we always have correct, up-to-date information about your
messages, even if other programs have modified the Maildir.
The downside of this thoroughness (which is the default) is that it
is relatively slow, something that can be noticeable with large e-mail
corpa on slow file-systems. For a faster approach, you can use the
following:
(setq
mu4e-index-cleanup nil ;; don't do a full cleanup check
mu4e-index-lazy-check t) ;; don't consider up-to-date dirs
In many cases, the mentioned thoroughness might not be needed, and
these settings give a very significant speed-up. Note that you can of
course occasionally run a thorough indexing round.
For further details, please refer to the mu-index manpage; in
particular, see .noindex and .noupdate which can help reducing the
indexing time.
2.8.5 Example setup
-------------------
A simple setup could look something like:
(setq
mu4e-get-mail-command "offlineimap" ;; or fetchmail, or ...
mu4e-update-interval 300) ;; update every 5 minutes
A hook ‘mu4e-update-pre-hook’ is available which is run right before
starting the process. That can be useful, for example, to influence,
‘mu4e-get-mail-command’ based on the the current situation (location,
time of day, ...).
It is possible to get notifications when the indexing process does
any updates — for example when receiving new mail. See
‘mu4e-index-updated-hook’ and some tips on its usage in the *note FAQ::.

File: mu4e.info, Node: Sending mail, Next: Running mu4e, Prev: Retrieval and indexing, Up: Getting started
2.9 Sending mail
================
mu4e re-uses Gnus’ ‘message-mode’ (*note (message)Top::) for writing
mail and inherits the setup for sending mail as well.
For sending mail using SMTP, mu4e uses smtpmail (*note
(smtpmail)Top::). This package supports many different ways to send
mail; please refer to its documentation for the details.
Here, we only provide some simple examples — for more, see *note
Example configs::.
A very minimal setup:
;; 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")
Since mu4e (re)uses the same message mode and smtpmail that Gnus
uses, many settings for those also apply to mu4e.
2.9.1 Dealing with sent messages
--------------------------------
By default, mu4e puts a copy of messages you sent in the folder
determined by ‘mu4e-sent-folder’. In some cases, this may not be what
you want - for example, when using Gmail-over-IMAP, this interferes with
Gmail’s handling of the sent messages folder, and you may end up with
duplicate messages.
You can use the variable ‘mu4e-sent-messages-behavior’ to customize
what happens with sent messages. The default is the symbol ‘sent’
which, as mentioned, causes the message to be copied to your
sent-messages folder. Other possible values are the symbols ‘trash’
(the sent message is moved to the trash-folder (‘mu4e-trash-folder’),
and ‘delete’ to simply discard the sent message altogether (so Gmail can
deal with it).
For Gmail-over-IMAP, you could add the following to your settings:
;; don't save messages to Sent Messages, Gmail/IMAP takes care of this
(setq mu4e-sent-messages-behavior 'delete)
And that’s it! We should now be ready to go.
For more complex needs, ‘mu4e-sent-messages-behavior’ can also be a
parameter-less function that returns one of the mentioned symbols; see
the built-in documentation for the variable.

File: mu4e.info, Node: Running mu4e, Prev: Sending mail, Up: Getting started
2.10 Running mu4e
=================
After following the steps in this chapter, we now (hopefully!) have a
working mu4e setup. Great! In the next chapters, we walk you through
the various views in mu4e.
For your orientation, the diagram below shows how the views relate to
each other, and the default key-bindings to navigate between them.
[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

File: mu4e.info, Node: Main view, Next: Headers view, Prev: Getting started, Up: Top
3 The main view
***************
After you have installed mu4e (*note Getting started::), you can start
it with ‘M-x mu4e’. mu4e does some checks to ensure everything is set
up correctly, and then shows you the mu4e main view. Its major mode is
‘mu4e-main-mode’.
* Menu:
* Overview: MV Overview. What is the main view
* Basic actions::What can we do
* Bookmarks: MV Bookmarks. Jumping to other places
* Miscellaneous::Notes

File: mu4e.info, Node: MV Overview, Next: Basic actions, Up: Main view
3.1 Overview
============
The main view looks something like the following:
* mu4e - mu for emacs version @value{VERSION}
Basics
* [j]ump to some maildir
* enter a [s]earch query
* [C]ompose a new message
Bookmarks
* [bu] Unread messages (26119/26119)
* [bt] Today's messages (1/7)
* [bw] Last 7 days (30/126)
* [bp] Messages with images (268/2309)
Maildirs
* [ja] /archive (3174/17990)
* [ji] /inbox (0/2)
* [jm] /mu (1541/14884)
* [js] /sent
Misc
* [;]Switch context
* [U]pdate email & database
* toggle [m]ail sending mode (currently direct)
* [N]ews
* [A]bout mu4e
* [H]elp
* [q]uit
Info
* database-path : /home/user/.cache/mu/xapian
* maildir : /home/user/Maildir
* in store : 78825 messages
* personal addresses : jim@@example.com, bob@@example.com
Let’s walk through the menu.

File: mu4e.info, Node: Basic actions, Next: MV Bookmarks, Prev: MV Overview, Up: Main view
3.2 Basic actions
=================
First, the _Basics_:
• [j]ump to some maildir: after pressing <j> (“jump”), mu4e asks you
for a maildir to visit. These are the maildirs you set in *note
Basic configuration:: and any of your own. If you choose <o>
(“other”) or </>, you can choose from all maildirs under the
root-maildir. After choosing a maildir, the messages in that
maildir are listed, in the *note Headers view::.
• enter a [s]earch query: after pressing <s>, mu4e asks you for a
search query, and after entering one, shows the results in the
*note Headers view::.
• [C]ompose a new message: after pressing <C>, you are dropped in the
*note Editor view:: to write a new message.

File: mu4e.info, Node: MV Bookmarks, Next: Miscellaneous, Prev: Basic actions, Up: Main view
3.3 Bookmarks
=============
The next item in the Main view is _Bookmarks_.
Bookmarks are predefined queries with a descriptive name and a
shortcut — in the example above, we see the default bookmarks. You can
view the list of messages matching a certain bookmark by pressing <b>
followed by the bookmark’s shortcut. If you’d like to edit the
bookmarked query first before invoking it, use <B>.
Next to each bookmark there is the number of (unread/all) messages
that match.
Bookmarks are stored in the variable ‘mu4e-bookmarks’; you can add
your own and/or replace the default ones; *Note Bookmarks::. For
instance:
(add-to-list 'mu4e-bookmarks
;; add bookmark for recent messages on the Mu mailing list.
'( :name "Mu7Days"
:key ?m
:query "list:mu-discuss.googlegroups.com AND date:7d..now"))
There are optional keys :hide to hide the bookmark from the main
menu, but still have it available (using <b>)) and :hide-unread to avoid
generating the unread-number; that can be useful if you have bookmarks
for slow queries. Note that :hide-unread is implied when the query is
not a string; this for the common case where the query function involves
some user input, which would be disruptive in this case.

File: mu4e.info, Node: Miscellaneous, Prev: MV Bookmarks, Up: Main view
3.4 Miscellaneous
=================
Finally, there are some _Misc_ (miscellaneous) actions:
• [U]pdate email & database executes the shell-command in the
variable ‘mu4e-get-mail-command’, and afterwards updates the mu
database; see *note Indexing your messages:: and *note Getting
mail:: for details.
• toggle [m]ail sending mode (direct) toggles between sending mail
directly, and queuing it first (for example, when you are offline),
and [f]lush queued mail flushes any queued mail. This item is
visible only if you have actually set up mail-queuing. *note
Queuing mail::
• [A]bout mu4e provides general information about the program
• [H]elp shows help information for this view
• Finally, [q]uit mu4e quits your mu4e-session

File: mu4e.info, Node: Headers view, Next: Message view, Prev: Main view, Up: Top
4 The headers view
******************
The headers view shows the results of a query. The header-line shows
the names of the fields. Below that, there is a line with those fields,
for each matching message, followed by a footer line. The major-mode
for the headers view is ‘mu4e-headers-mode’.
* Menu:
* Overview: HV Overview. What is the Header View
* Keybindings::Do things with your keyboard
* Marking: HV Marking. Selecting messages for doing things
* Sorting and threading::Influencing the display
* Custom headers: HV Custom headers. Adding your own headers
* Actions: HV Actions. Defining and using actions
* Split view::Seeing both headers and messages

File: mu4e.info, Node: HV Overview, Next: Keybindings, Up: Headers view
4.1 Overview
============
An example headers view:
Date V Flgs From/To List Subject
06:32 Nu To Edmund Dantès GstDev Gstreamer-V4L2SINK ...
15:08 Nu Abbé Busoni GstDev ├> ...
18:20 Nu Pierre Morrel GstDev │└> ...
07:48 Nu To Edmund Dantès GstDev └> ...
2013-03-18 S Jacopo EmacsUsr emacs server on win...
2013-03-18 S Mercédès EmacsUsr └> ...
2013-03-18 S Beachamp EmacsUsr Re: Copying a whole...
22:07 Nu Albert de Moncerf EmacsUsr └> ...
2013-03-18 S Gaspard Caderousse GstDev Issue with GESSimpl...
2013-03-18 Ss Baron Danglars GuileUsr Guile-SDL 0.4.2 ava...
End of search results
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’; see
‘mu4e-header-info’ for the list of built-in fields. Apart from the
built-in fields, you can also create custom fields using
‘mu4e-header-info-custom’; see *note HV Custom headers:: for
details.
• By default, the date is shown with the :human-date field, which
shows the _time_ for today’s messages, and the _date_ for older
messages. If you do not want to distinguish between ‘today’ and
‘older’, you can use the :date field instead.
• You can customize the date and time formats with the variable
‘mu4e-headers-date-format’ and ‘mu4e-headers-time-format’,
respectively. In the example, we use ‘:human-date’, which shows
the time when the message was sent today, and the date otherwise.
• By default, the subject is shown using the :subject field; however,
it is also possible to use :thread-subject, which shows the subject
of a thread only once, similar to the display of the mutt e-mail
client.
• The header field used for sorting is indicated by “V” or “^”(1),
corresponding to the sort order (descending or ascending,
respectively). You can influence this by a mouse click, or <O>.
Not all fields allow sorting.
• Instead of showing the From: and To: fields separately, you can use
From/To (:from-or-to in ‘mu4e-headers-fields’ as a more compact way
to convey the most important information: it shows From: _except_
when the e-mail was sent by the user (i.e., you) — in that case it
shows To: (prefixed by To(2), as in the example above).
• The ‘List’ field shows the mailing-list a message is sent to;
‘mu4e’ tries to create a convenient shortcut for the mailing-list
name; the variable ‘mu4e-user-mailing-lists’ can be used to add
your your own shortcuts. You can use ‘mu4e-mailing-list-patterns’
to to specify generic shortcuts, e.g. to shorten list names which
contain dots (mu4e defaults to shortening up to the first dot):
(setq mu4e-mailing-list-patterns '(``\\([-_a-z0-9.]+\\)\.lists\.company\.com'')))
• The letters in the ‘Flags’ field correspond to the following:
D=_draft_, F=_flagged_ (i.e., ‘starred’), 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.
• The subject field also indicates the discussion threads (3).
• The headers view is _automatically updated_ if any changes are
found during the indexing process, and if there is no current
user-interaction. If you do not want such automatic updates, set
‘mu4e-headers-auto-update’ to ‘nil’.
• Just before executing a search, a hook-function
‘mu4e-headers-search-hook’ is invoked, which receives the search
expression as its parameter.
• Also, there is a hook-function ‘mu4e-headers-found-hook’ available
which is invoked just after mu4e has completed showing the messages
in the headers-view.
---------- Footnotes ----------
(1) or you can use little graphical triangles; see variable
‘mu4e-use-fancy-chars’
(2) You can customize this by changing the variable
‘mu4e-headers-from-or-to-prefix’ (a cons cell)
(3) using Jamie Zawinski’s mail threading algorithm,
<https://www.jwz.org/doc/threading.html>

File: mu4e.info, Node: Keybindings, Next: HV Marking, Prev: HV Overview, Up: Headers view
4.2 Keybindings
===============
Using the below key bindings, you can do various things with these
messages; these actions are also listed in the Mu4e menu in the Emacs
menu bar.
key description
===========================================================
n,p view the next, previous message
],[ move to the next, previous unread 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
V toggle skip-duplicates
W toggle include-related
marking
-------
d mark for moving to the trash folder
= mark for removing trash flag ('untrash')
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
<insert>,* mark for 'something' (decide later)
# resolve deferred 'something' marks
x execute actions for the marked messages
composition
-----------
R,F,C reply/forward/compose
E edit (only allowed for draft messages)
misc
----
; switch context
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
C-S-u update mail & reindex
q leave the headers buffer

File: mu4e.info, Node: HV Marking, Next: Sorting and threading, Prev: Keybindings, Up: Headers view
4.3 Marking
===========
You can _mark_ messages for a certain action, such as deletion or move.
After one or more messages are marked, you can then execute
(‘mu4e-mark-execute-all’, <x>) these actions. This two-step
mark-execute sequence is similar to what e.g. dired does. It is how
mu4e tries to be as quick as possible, while avoiding accidents.
The mark/unmark commands support the _region_ (i.e., “selection”) —
so, for example, if you select some messages and press <DEL>, all
messages in the region are marked for deletion.
You can mark all messages that match a certain pattern with <%>. In
addition, you can mark all messages in the current thread (<T>) or
sub-thread (<t>).
When you do a new search or refresh the headers buffer while you
still have marked messages, you are asked what to do with those marks —
whether to _apply_ them before leaving, or _ignore_ them. This behavior
can be influenced with the variable ‘mu4e-headers-leave-behavior’.
For more information about marking, see *note Marking::.

File: mu4e.info, Node: Sorting and threading, Next: HV Custom headers, Prev: HV Marking, Up: Headers view
4.4 Sorting and threading
=========================
By default, mu4e sorts messages by date, in descending order: the most
recent messages are shown at the top. In addition, be default mu4e
shows the message _threads_, i.e., the tree structure representing a
discussion thread; this also affects the sort order: the top-level
messages are sorted by the date of the _newest_ message in the thread.
The header field used for sorting is indicated by “V” or “^”(1),
indicating the sort order (descending or ascending, respectively).
You can change the sort order by clicking the corresponding column
with the mouse, or with ‘M-x mu4e-headers-change-sorting’ (<O>); note
that not all fields can be used for sorting. You can toggle threading
on/off using ‘M-x mu4e-headers-toggle-threading’ or <P>. For both of
these functions, unless you provide a prefix argument (<C-u>), the
current search is updated immediately using the new parameters. You can
toggle full-search (*note Searching::) using ‘M-x
mu4e-headers-toggle-full-search’ or <Q>.
Note that with threading enabled, the sorting is exclusively by date,
regardless of the column clicked.
If you want to change the defaults for these settings, you can use
the variables ‘mu4e-headers-sort-field’ and ‘mu4e-headers-show-threads’,
as well as ‘mu4e-headers-change-sorting’ to change the sorting of the
current search results.
---------- Footnotes ----------
(1) or you can use little graphical triangles; see variable
‘mu4e-use-fancy-chars’

File: mu4e.info, Node: HV Custom headers, Next: HV Actions, Prev: Sorting and threading, Up: Headers view
4.5 Custom headers
==================
Sometimes the normal headers that mu4e offers (Date, From, To, Subject,
etc.) may not be enough. For these cases, mu4e offers _custom headers_
in both the headers-view and the message-view.
You can do so by adding a description of your custom header to
‘mu4e-header-info-custom’, which is a list of custom headers.
Let’s look at an example — suppose we want to add a custom header
that shows the number of recipients for a message, i.e., the sum of the
number of recipients in the To: and Cc: fields. Let’s further suppose
that our function takes a message-plist as its argument (*note Message
functions::).
(add-to-list 'mu4e-header-info-custom
'(:recipnum .
( :name "Number of recipients" ;; long name, as seen in the message-view
:shortname "Recip#" ;; short name, as seen in the headers view
:help "Number of recipients for this message" ;; tooltip
:function (lambda (msg)
(format "%d"
(+ (length (mu4e-message-field msg :to))
(length (mu4e-message-field msg :cc))))))))
Or, let’s get the full mailing-list name:
(add-to-list 'mu4e-header-info-custom
'(:full-mailing-list .
( :name "Mailing-list" ;; long name, as seen in the message-view
:shortname "ML" ;; short name, as seen in the headers view
:help "Full name for mailing list" ;; tooltip
:function (lambda (msg)
(or (mu4e-message-field msg :mailing-list) "")))))
You can then add the custom header to your ‘mu4e-headers-fields’,
just like the built-in headers. After evaluation, your headers-view
should include a new header Recip# with the number of recipients, and/or
ML with the full mailing-list name.
This function can be used in both the headers-view and the
message-view; if you need something specific for one of these, you can
check for the mode in your function, or create separate functions.

File: mu4e.info, Node: HV Actions, Next: Split view, Prev: HV Custom headers, Up: Headers view
4.6 Actions
===========
‘mu4e-headers-action’ (<a>) lets you pick custom actions to perform on
the message at point. You can specify these actions using the variable
‘mu4e-headers-actions’. See *note Actions:: for the details.
mu4e defines some default actions. One of those is for _capturing_ a
message: <a c> ‘captures’ the current message. Next, when you’re
editing some message, you can include the previously captured message as
an attachment, using ‘mu4e-compose-attach-captured-message’. See
‘mu4e-actions.el’ in the mu4e source distribution for more example
actions.

File: mu4e.info, Node: Split view, Prev: HV Actions, Up: Headers view
4.7 Split view
==============
Using the _Split view_, we can see the *note Headers view:: and the
*note Message view:: next to each other, with the message selected in
the former, visible in the latter. You can influence the way the
splitting is done by customizing the variable ‘mu4e-split-view’.
Possible values are:
• horizontal (this is the default): display the message view below
the header view. Use ‘mu4e-headers-visible-lines’ the set the
number of lines shown (default: 8).
• vertical: display the message view on the right side of the header
view. Use ‘mu4e-headers-visible-columns’ to set the number of
visible columns (default: 30).
• single-window: single window mode. Single-window mode tries to
minimize mu4e window operations (opening, killing, resizing, etc)
and buffer changes, while still retaining the view and headers
buffers. In addition, it replaces mu4e main view with a minibuffer
prompt containing the same information.
• anything else: don’t do any splitting
Some useful key bindings in the split view:
• <C-+> and <C-->: interactively change the number of columns or
headers shown
• 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>

File: mu4e.info, Node: Message view, Next: Editor view, Prev: Headers view, Up: Top
5 The message view
******************
This chapter discusses the new (since version 1.6) Gnus-based message
view. However, the old one is still available – see *note Old message
view::.
After selecting a message in the *note Headers view::, it appears in
a message view window, which shows the message headers, followed by the
message body. Its major mode is ‘mu4e-view-mode’, which derives from
gnus-article-mode.
* Menu:
* Overview: MSGV Overview. What is the Message View
* Keybindings: MSGV Keybindings. Do things with your keyboard
* Rich-text and images: MSGV Rich-text and images. Reading rich-text messages
* Custom headers: MSGV Custom headers. Your very own headers
* Actions: MSGV Actions. Defining and using actions.

File: mu4e.info, Node: MSGV Overview, Next: MSGV Keybindings, Up: Message view
5.1 Overview
============
An example message view:
From: randy@epiphyte.com
To: julia@eruditorum.org
Subject: Re: some pics
Flags: seen, attach
Date: Thu, 11 Feb 2021 12:59:30 +0200 (4 weeks, 3 days, 21 hours ago)
Maildir: /inbox
Attachments: [2. image/jpeg; DSCN4961.JPG]... [3. image/jpeg; DSCN4962.JPG]...
Hi Julia,
Some pics from our trip to Cerin Amroth. Enjoy!
All the best,
Randy.
On Sun 21 Dec 2003 09:06:34 PM EET, Julia wrote:
[....]
Some notes:
• The variable ‘mu4e-view-fields’ determines the header fields to be
shown; see ‘mu4e-header-info’ for a list of built-in fields. Apart
from the built-in fields, you can also create custom fields using
‘mu4e-header-info-custom’; see *note MSGV Custom headers::.
• For search-related operations, see *note Searching::.
• You can scroll down the message using <SPC>; if you do this at the
end of a message,it automatically takes you to the next one. If
you want to prevent this behavior, set ‘mu4e-view-scroll-to-next’
to ‘nil’.

File: mu4e.info, Node: MSGV Keybindings, Next: MSGV Rich-text and images, Prev: MSGV Overview, Up: Message view
5.2 Keybindings
===============
You can find most things you can do with this message in the _Mu4e_
menu, or by using the keyboard; the default bindings are:
key description
==============================================================
n,p view the next, previous message
],[ move to the next, previous unread message
y select the headers view (if it's visible)
RET scroll down
M-RET open URL at point / attachment at point
SPC scroll down, if at end, move to next message
S-SPC scroll up
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
marking messages
----------------
d mark for moving to the trash folder
= mark for removing trash flag ('untrash')
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
<insert>,* mark for 'something' (decide later)
# resolve deferred 'something' 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)
C-u g visits multiple URLs
f fetch (download )the numbered URL.
C-u f fetches multiple URLs
k save the numbered URL in the kill-ring.
C-u k saves multiple URLs
e extract (save) one or more attachments (asks for numbers)
(or: <mouse-2> or S-RET with point on attachment)
a execute some custom action on the message
A execute some custom action on the message's MIME-parts
misc
----
; switch context
. show the raw message view. 'q' takes you back.
C-+,C-- increase / decrease the number of headers shown
H get help
C-S-u update mail & reindex
q leave the message view
For the marking commands, please refer to *note Marking messages::.

File: mu4e.info, Node: MSGV Rich-text and images, Next: MSGV Custom headers, Prev: MSGV Keybindings, Up: Message view
5.3 Reading rich-text messages
==============================
These days, many e-mail messages contain rich-text (typically, HTML);
either as an alternative to a text-only version, or even as the only
option.
By default, mu4e tries to display the ’richest’ option, which is the
last MIME-part of the alternatives. You can customize this to prefer
the text version, if available, with something like the following in
your configuration (and see the docstring for
mm-discouraged-alternatives for details):
(with-eval-after-load "mm-decode"
(add-to-list 'mm-discouraged-alternatives "text/html")
(add-to-list 'mm-discouraged-alternatives "text/richtext"))
When displaying rich-text messages inline, mu4e (through gnus) uses
the shr built-in HTML-renderer. If you’re using a dark color theme, and
the messages are hard to read, it can help to change the luminosity,
e.g.:
(setq shr-color-visible-luminance-min 80)
Note that you can switch between the HTML and text versions by
clicking on the relevant part in the messages headers; you can make it
even clearer by indicating them in the message itself, using:
(setq gnus-unbuttonized-mime-types nil)
5.3.1 Inline images
-------------------
When you run Emacs in graphical mode, by default images attached to
messages are shown inline in the message view buffer.
To disable this, set ‘gnus-inhibit-images’ to t. By default,
external images in HTML are not retrieved from external URLs because
they can be used to track you.
You can specify what URLs to block by setting ‘gnus-blocked-images’
to a regular exporession or to a function that will receive the message
as an argument. For example, to enable images in Github notifications,
do the following:
(setq gnus-blocked-images
(lambda(&optional _ignore)
(if (mu4e-message-contact-field-matches
(mu4e-message-at-point) :from "notifications@github.com")
nil ".")))

File: mu4e.info, Node: MSGV Custom headers, Next: MSGV Actions, Prev: MSGV Rich-text and images, Up: Message view
5.4 Custom headers
==================
Sometimes the normal headers (Date, From, To, Subject, etc.) may not be
enough. For these cases, mu4e offers _custom headers_ in both the
headers-view and the message-view.
See *note HV Custom headers:: for an example of this; the difference
for the message-view is that you should add your custom header to
‘mu4e-view-fields’ rather than ‘mu4e-headers-fields’.

File: mu4e.info, Node: MSGV Actions, Prev: MSGV Custom headers, Up: Message view
5.5 Actions
===========
You can perform custom functions (“actions”) on messages and their
attachments. For a general discussion on how to define your own, see
*note Actions::.
5.5.1 Message 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’; mu4e defines a number of example actions.
5.5.2 MIME-part actions
-----------------------
MIME-part actions allow you to act upon MIME-parts in a message - such
as attachments. For now, these actions are defined and documented in
‘mu4e-view-mime-part-actions’.

File: mu4e.info, Node: Editor view, Next: Searching, Prev: Message view, Up: Top
6 The editor view
*****************
Writing e-mail messages takes place in the Editor View. mu4e’s editor
view builds on top of Gnus’ message-mode. Most of the message-mode
functionality is available, as well some mu4e-specifics. Its major mode
is ‘mu4e-compose-mode’.
* Menu:
* Overview: EV Overview. What is the Editor view
* Keybindings: EV Keybindings. Doing things with your keyboard
* Address autocompletion:: Quickly entering known addresses
* Compose hooks::Calling functions when composing
* Signing and encrypting:: Support for cryptography
* Queuing mail:: Sending mail when the time is ripe
* Message signatures:: Adding your personal footer to messages
* Other settings::Miscellanea

File: mu4e.info, Node: EV Overview, Next: EV Keybindings, Up: Editor view
6.1 Overview
============
From: Rupert the Monkey <rupert@example.com>
To: Wally the Walrus <wally@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.

File: mu4e.info, Node: EV Keybindings, Next: Address autocompletion, Prev: EV Overview, Up: Editor view
6.2 Keybindings
===============
mu4e’s editor view derives from Gnus’ message editor and shares most of
its keybindings. Here are some of the more useful ones (you can use the
menu to find more):
key description
--- -----------
C-c C-c send message
C-c C-d save to drafts and leave
C-c C-k kill the message buffer (the message remains in the draft folder)
C-c C-a attach a file (pro-tip: drag & drop works as well)
C-c C-; switch the context
(mu4e-specific)
C-S-u update mail & reindex

File: mu4e.info, Node: Address autocompletion, Next: Compose hooks, Prev: EV Keybindings, Up: Editor view
6.3 Address autocompletion
==========================
mu4e supports(1) autocompleting addresses when composing e-mail
messages. mu4e uses the e-mail addresses from the messages you sent or
received as the source for this. Address auto-completion is enabled by
default; if you want to disable it for some reason, set
mu4e-compose-complete-addresses to nil.
Emacs 24 also supports cycling through the alternatives. When there
are more than _5_ matching addresses, they are shown in a *Completions*
buffer. Once the number of matches gets below this number, one is
inserted in the address field and you can cycle through the alternatives
using <TAB>.
6.3.1 Limiting the number of addresses
--------------------------------------
If you have a lot of mail, especially from mailing lists and the like,
there can be a _lot_ of e-mail addresses, many of which may not be very
useful when auto-completing. For this reason, mu4e attempts to limit
the number of e-mail addresses in the completion pool by filtering out
the ones that are not likely to be relevant. The following variables
are available for tuning this:
• ‘mu4e-compose-complete-only-personal’ — when set to t, only
consider addresses that were seen in _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 the
--my-address parameter to mu init.
• ‘mu4e-compose-complete-only-after’ — only consider e-mail addresses
last seen after some date. Parameter is a string, parseable by
‘org-parse-time-string’. This excludes old e-mail addresses. The
default is "2010-01-01", i.e., only consider e-mail addresses seen
since the start of 2010.
• ‘mu4e-contact-process-function’ — a function to rewrite or exclude
certain addresses.
---------- Footnotes ----------
(1) GNU Emacs 24.4 or higher is required

File: mu4e.info, Node: Compose hooks, Next: Signing and encrypting, Prev: Address autocompletion, Up: Editor view
6.4 Compose hooks
=================
If you want to change some setting, or execute some custom action before
message composition starts, you can define a _hook function_. mu4e
offers two hooks:
• ‘mu4e-compose-pre-hook’: this hook is run _before_ composition
starts; if you are composing a _reply_, _forward_ a message, or
_edit_ an existing message, the variable
‘mu4e-compose-parent-message’ points to the message being replied
to, forwarded or edited, and you can use ‘mu4e-message-field’ to
get the value of various properties (and see *note Message
functions::).
• ‘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.
‘mu4e-compose-parent-message’ (see above) is also at your disposal.
Let’s look at some examples. First, suppose we want to set the
From:-address for a reply message based on the receiver of the original:
;; 1) messages to me@foo.example.com should be replied with From:me@foo.example.com
;; 2) messages to me@bar.example.com should be replied with From:me@bar.example.com
;; 3) all other mail should use From:me@cuux.example.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 ((msg mu4e-compose-parent-message)) ;; msg is shorter...
(when msg
(setq user-mail-address
(cond
((mu4e-message-contact-field-matches msg :to "me@foo.example.com")
"me@foo.example.com")
((mu4e-message-contact-field-matches msg :to "me@bar.example.com")
"me@bar.example.com")
(t "me@cuux.example.com")))))))
Secondly, as mentioned, ‘mu4e-compose-mode-hook’ is especially useful
for editing-related settings. For example:
(add-hook 'mu4e-compose-mode-hook
(defun my-do-compose-stuff ()
"My settings for message composition."
(set-fill-column 72)
(flyspell-mode)))
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 Bcc:-header, you could add something like the following, using
‘message-add-header’ from ‘message-mode’.
(add-hook 'mu4e-compose-mode-hook
(defun my-add-bcc ()
"Add a Bcc: header."
(save-excursion (message-add-header "Bcc: me@example.com\n"))))
Or to something context-specific:
(add-hook 'mu4e-compose-mode-hook
(lambda()
(let* ((ctx (mu4e-context-current))
(name (if ctx (mu4e-context-name ctx))))
(when name
(cond
((string= name "account1")
(save-excursion (message-add-header "Bcc: account1@example.com\n")))
((string= name "account2")
(save-excursion (message-add-header "Bcc: account2@example.com\n"))))))))
For a more general discussion about extending mu4e, see *note Extending
mu4e::.

File: mu4e.info, Node: Signing and encrypting, Next: Queuing mail, Prev: Compose hooks, Up: Editor view
6.5 Signing and encrypting
==========================
Signing and encrypting of messages is possible using emacs-mime (*note
(emacs-mime)Composing::), most easily accessed through the
Attachments-menu while composing a message, or with ‘M-x
mml-secure-message-encrypt-pgp’, ‘M-x mml-secure-message-sign-pgp’.
The support for encryption and signing is _independent_ of the
support for their counterparts, decrypting and signature verification
(as discussed in *note OMSGV Crypto::). Even if your mu4e does not have
support for the latter two, you can still sign/encrypt messages.
Important note: the messages are encrypted when they are _sent_: this
means that draft messages are _not_ encrypted. So if you are using e.g.
offlineimap or mbsync to synchronize with some remote IMAP-service, make
sure the drafts folder is _not_ in the set of synchronized folders, for
obvious reasons.

File: mu4e.info, Node: Queuing mail, Next: Message signatures, Prev: Signing and encrypting, Up: Editor view
6.6 Queuing mail
================
If you cannot send mail right now, 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 *note Main
view::.
To allow for queuing, you need to tell smtpmail where you want to
store the queued messages. For example:
(setq smtpmail-queue-mail t ;; start in queuing mode
smtpmail-queue-dir "~/Maildir/queue/cur")
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 mu4e. The ‘mu mkdir’ command may be useful
here, so for example:
$ mu mkdir ~/Maildir/queue
$ touch ~/Maildir/queue/.noindex
The file created by the ‘touch’ command tells mu to ignore this
directory for indexing, which makes sense since it contains smtpmail
meta-data rather than normal messages; see the mu-mkdir and mu-index
man-pages for details.
_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!

File: mu4e.info, Node: Message signatures, Next: Other settings, Prev: Queuing mail, Up: Editor view
6.7 Message signatures
======================
Message signatures are the standard footer blobs in e-mail messages
where you can put in information you want to include in every message.
The text to include is set with ‘mu4e-compose-signature’.
If you don’t want to include this automatically with each message,
you can set ‘mu4e-compose-signature-auto-include’ to ‘nil’; you can then
still include the signature manually, using the function
‘message-insert-signature’, typically bound to ‘C-c C-w’.

File: mu4e.info, Node: Other settings, Prev: Message signatures, Up: Editor view
6.8 Other settings
==================
• If you want use mu4e as Emacs’ default program for sending mail,
see *note Emacs default::.
• Normally, mu4e _buries_ the message buffer after sending; if you
want to kill the buffer instead, add something like the following
to your configuration:
(setq message-kill-buffer-on-exit t)
• If you want to exclude your own e-mail address when “replying to
all”, set ‘mu4e-compose-dont-reply-to-self’ to ‘t’. In order for
this to work properly you need to pass your address to ‘mu init
--my-address=’ at database initialization time.

File: mu4e.info, Node: Searching, Next: Marking, Prev: Editor view, Up: Top
7 Searching
***********
mu4e is fully search-based: even if you ‘jump to a folder’, you are
executing a query for messages that happen to have the property of being
in a certain folder (maildir).
Normally, queries return up to ‘mu4e-headers-results-limit’ (default:
500) results. That is usually more than enough, and makes things
significantly faster. Sometimes, however, you may want to show _all_
results; you can enable this with ‘M-x mu4e-headers-toggle-full-search’,
or by customizing the variable ‘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 *note Sorting and threading::.
* Menu:
* Queries:: Searching for messages.
* Bookmarks:: Remembering queries.
* Maildir searches:: Queries for maildirs.
* Other search functionality:: Some more tricks.

File: mu4e.info, Node: Queries, Next: Bookmarks, Up: Searching
7.1 Queries
===========
mu4e queries are the same as the ones that mu find understands(1). You
can consult the ‘mu-query’ man page for the details.
Additionally, mu4e supports ‘TAB’-completion for queries. There
there is completion for all search keywords such as ‘and’, ‘from:’, or
‘date:’ and also for certain values, i.e., the possible values for
‘flag:’, ‘prio:’, ‘mime:’, and ‘maildir:’.
Let’s look at some examples here.
• Get all messages regarding _bananas_:
bananas
• Get all messages regarding _bananas_ from _John_ with an
attachment:
from:john and flag:attach and bananas
• Get all messages with subject _wombat_ in June 2017
subject:wombat and date:20170601..20170630
• Get all messages with PDF attachments in the /projects folder
maildir:/projects and mime:application/pdf
• Get all messages about _Rupert_ in the /Sent Items folder. Note
that maildirs with spaces must be quoted.
"maildir:/Sent Items" and rupert
• Get all important messages which are signed:
flag:signed and prio:high
• Get all messages from _Jim_ without an attachment:
from:jim and not flag:attach
• Get all messages with Alice in one of the contacts-fields (to,
from, cc, bcc):
contact:alice
• Get all unread messages where the subject mentions Ångström:
(search is case-insensitive and accent-insensitive, so this matches
Ångström, angstrom, aNGstrøM, ...)
subject:Ångström and flag:unread
• Get all unread messages between Mar-2012 and Aug-2013 about some
bird:
date:20120301..20130831 and nightingale and flag:unread
• Get today’s messages:
date:today..now
• Get all messages we got in the last two weeks regarding _emacs_:
date:2w.. and emacs
• Get messages from the _Mu_ mailing list:
list:mu-discuss.googlegroups.com
Note — in the *note Headers view:: you may see the ‘friendly name’
for a list; however, when searching you need the real name. You
can see the real name for a mailing list from the friendly name’s
tool-tip.
• Get messages with a subject soccer, Socrates, society, ...; note
that the ‘*’-wildcard can only appear as a term’s rightmost
character:
subject:soc*
• Get all messages _not_ sent to a mailing-list:
NOT flag:list
• Get all mails with attachments with filenames starting with _pic_;
note that 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, and note that the ‘*’
wildcard can only appear as the term’s rightmost character:
mime:image/*
Get all messages with files that end in .ppt; this uses the
regular-expression support, which is powerful but relatively slow:
file:/\.ppt$/
---------- Footnotes ----------
(1) with the caveat that command-line queries are subject to the
shell’s interpretation before mu sees them

File: mu4e.info, Node: Bookmarks, Next: Maildir searches, Prev: Queries, Up: Searching
7.2 Bookmarks
=============
If you have queries that you use often, you may want to store them as
_bookmarks_. Bookmark searches are available in the main view (*note
Main view::), header view (*note Headers view::), and message view
(*note Message view::), using (by default) the key <b> (‘M-x
mu4e-search-bookmark’), or <B> (‘M-x mu4e-search-bookmark-edit’) which
lets you edit the bookmark first.
7.2.1 Setting up bookmarks
--------------------------
mu4e provides a number of default bookmarks. Their definition may be
instructive:
(defcustom mu4e-bookmarks
'(( :name "Unread messages"
:query "flag:unread AND NOT flag:trashed"
:key ?u)
( :name "Today's messages"
:query "date:today..now"
:key ?t)
( :name "Last 7 days"
:query "date:7d..now"
:hide-unread t
:key ?w)
( :name "Messages with images"
:query "mime:image/*"
:key ?p))
"List of pre-defined queries that are shown on the main screen.
Each of the list elements is a plist with at least:
:name - the name of the query
:query - the query expression
:key - the shortcut key.
Optionally, you add the following:
:hide - if t, bookmark is hdden from the main-view and speedbar.
:hide-unread - do not show the counts of unread/total number
of matches for the query. This can be useful if a bookmark uses
a very slow query. :hide-unread is implied from :hide.
"
:type '(repeat (plist))
:group 'mu4e)
You can replace these or add your own items, by putting in your
configuration (‘~/.emacs’) something like:
(add-to-list 'mu4e-bookmarks
'( :name "Big messages"
:query "size:5M..500M"
:key ?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> 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 ‘bb’.
7.2.2 Lisp expressions or functions as bookmarks
------------------------------------------------
Instead of using strings, it is also possible to use Lisp expressions as
bookmarks. Either the expression evaluates to a query string or the
expression is a function taking no argument that returns a query string.
For example, to get all the messages that are at most a week old in
your inbox:
(add-to-list 'mu4e-bookmarks
'( :name "Inbox messages in the last 7 days"
:query (lambda () (concat "maildir:/inbox AND date:"
(format-time-string "%Y%m%d"
(subtract-time (current-time) (days-to-time 7)))))
:key ?w) t)
Another example where the user is prompted how many days old messages
should be shown:
(defun my/mu4e-bookmark-num-days-old-query (days-old)
(interactive (list (read-number "Show days old messages: " 7)))
(let ((start-date (subtract-time (current-time) (days-to-time days-old))))
(concat "maildir:/inbox AND date:"
(format-time-string "%Y%m%d" start-date))))
(add-to-list 'mu4e-bookmarks
`(:name "Inbox messages in the last 7 days"
:query ,(lambda () (call-interactively 'my/mu4e-bookmark-num-days-old-query))
:key ?o) t)
It is defining a function to make the code more readable.
7.2.3 Editing bookmarks before searching
----------------------------------------
There is also ‘M-x mu4e-headers-search-bookmark-edit’ (key <B>), which
lets you edit the bookmarked query before invoking it. This can be
useful if you have many similar queries, but need to change some
parameter. For example, you could have a bookmark ‘"date:today..now AND
"’(1), which limits any result to today’s messages.
---------- Footnotes ----------
(1) Not a valid search query by itself

File: mu4e.info, Node: Maildir searches, Next: Other search functionality, Prev: Bookmarks, Up: Searching
7.3 Maildir searches
====================
Maildir searches are quite similar to bookmark searches (see *note
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 *note Main view::, *note Headers view::, and *note
Message view::, with the key <j> (‘mu4e-jump-to-maildir’). If a prefix
argument is given, the maildir query can be refined before execution.
7.3.1 Setting up maildir shortcuts
----------------------------------
You can search for maildirs like any other message property (e.g. with
a query like maildir:/myfolder), but since it is so common, mu4e offers
a shortcut for this.
For this to work, you need to set the variable
‘mu4e-maildir-shortcuts’ to the list of maildirs you want to have quick
access to, for example:
(setq mu4e-maildir-shortcuts
'( (:maildir "/inbox" :key ?i)
(:maildir "/archive" :key ?a)
(:maildir "/lists" :key ?l)
(:maildir "/work" :key ?w)
(:maildir "/sent" :key ?s)))
This sets <i> as a shortcut for the /inbox folder — effectively a
query maildir:/inbox. There is a special shortcut <o> or </> for
_other_ (so don’t use those for your own shortcuts!), which allows you
to choose from _all_ maildirs that you have. There is support for
autocompletion; note that the list of maildirs is determined when mu4e
starts; if there are changes in the maildirs while mu4e is running, you
need to restart mu4e.
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’. With these shortcuts, you can jump around your
maildirs (folders) very quickly — for example, getting to the /lists
folder only requires you to type ‘jl’, then change to /work with ‘jw’.
While in queries you need to quote folder names (maildirs) with
spaces in them, you should _not_ quote them when used in
‘mu4e-maildir-shortcuts’, since mu4e does that automatically for you.
The very same shortcuts are used by ‘M-x mu4e-mark-for-move’ (default
shortcut <m>); so, for example, if you want to move a message to the
/archive folder, you can do so by typing ‘ma’.

File: mu4e.info, Node: Other search functionality, Prev: Maildir searches, Up: Searching
7.4 Other search functionality
==============================
7.4.1 Navigating through search queries
---------------------------------------
You can navigate through previous/next queries using
‘mu4e-headers-query-prev’ and ‘mu4e-headers-query-next’, which are bound
to <M-left> and <M-right>, similar to what some web browsers do.
mu4e tries to be smart and not record duplicate queries. Also, the
number of queries remembered has a fixed limit, so mu4e won’t use too
much memory, even if used for a long time. However, if you want to
forget previous/next queries, you can use ‘M-x
mu4e-headers-forget-queries’.
7.4.2 Narrowing search results
------------------------------
It can be useful to narrow existing search results, that is, to add some
clauses to the current query to match fewer messages.
For example, suppose you’re looking at some mailing list, perhaps by
jumping to a maildir (‘M-x mu4e-headers-jump-to-maildir’, <j>) or
because you followed some bookmark (‘M-x mu4e-headers-search-bookmark’,
<b>). Now, you want to narrow things down to only those messages that
have attachments.
This is when ‘M-x mu4e-headers-search-narrow’ (</>) comes in handy.
It 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. <\> takes you
back to the previous query, so, effectively ‘widens’ the search.
Technically, narrowing the results of query x with expression y implies
doing a search (x) AND (y).
Note that messages that were not in your original search results
because of ‘mu4e-headers-results-limit’ may show up in the narrowed
query.
7.4.3 Including related messages
--------------------------------
It can be useful to not only show the messages that directly match a
certain query, but also include messages that are related to these
messages. That is, messages that belong to the same discussion threads
are included in the results, just like e.g. Gmail does it. You can
enable this behavior by setting ‘mu4e-headers-include-related’ to ‘t’,
and you can toggle between including/not-including with <W>.
Be careful though when e.g. deleting ranges of messages from a
certain folder — the list may now also include messages from _other_
folders.
7.4.4 Skipping duplicates
-------------------------
Another useful feature is skipping of _duplicate messages_. When you
have copies of messages, there’s usually little value in including more
than one in search results. A common reason for having multiple copies
of messages is the combination of Gmail and offlineimap, since that is
the way the labels / virtual folders in Gmail are represented. You can
enable skipping duplicates by setting ‘mu4e-headers-skip-duplicates’ to
‘t’, and you can toggle between the skipping/not skipping with <V>.
Note, messages are considered duplicates when they have the same
Message-Id.

File: mu4e.info, Node: Marking, Next: Contexts, Prev: Searching, Up: Top
8 Marking
*********
In mu4e, the common way to do things with messages is a two-step process
- first you _mark_ them for a certain action, then you _execute_ (<x>)
those marks. This is similar to the way dired operates. Marking can
happen in both the *note Headers view:: and the *note Message view::.
* Menu:
* Marking messages::Selecting message do something with them
* What to mark for::What can we do with them
* Executing the marks::Do it
* Trashing messages::Exceptions for mailboxes like Gmail
* Leaving the headers buffer::Handling marks automatically when leaving
* Built-in marking functions::Helper functions for dealing with them
* Custom mark functions::Define your own mark function
* Adding a new kind of mark::Adding your own marks

File: mu4e.info, Node: Marking messages, Next: What to mark for, Up: Marking
8.1 Marking messages
====================
There are multiple ways to mark messages:
• _message at point_: you can put a mark on the message-at-point in
either the *note Headers view:: or *note Message view::
• _region_: you can put a mark on all messages in the current region
(selection) in the *note Headers view::
• _pattern_: you can put a mark on all messages in the *note Headers
view:: matching a certain pattern with ‘M-x
mu4e-headers-mark-pattern’ (<%>)
• _thread/subthread_: You can put a mark on all the messages in the
thread/subthread at point with ‘M-x mu4e-headers-mark-thread’ and
‘M-x mu4e-headers-mark-subthread’, respectively

File: mu4e.info, Node: What to mark for, Next: Executing the marks, Prev: Marking messages, Up: Marking
8.2 What to mark for
====================
mu4e supports a number of marks:
mark for/as | keybinding | description
-------------+-------------+------------------------------
'something' | *, <insert> | mark now, decide later
delete | D, <delete> | delete
flag | + | mark as 'flagged' ('starred')
move | m | move to some maildir
read | ! | mark as read
refile | r | mark for refiling
trash | d | move to the trash folder
untrash | = | remove 'trash' flag
unflag | - | remove 'flagged' mark
unmark | u | remove mark at point
unmark all | U | remove all marks
unread | ? | marks as unread
action | a | apply some action
After marking a message, the left-most columns in the headers view
indicate the kind of mark. This is informative, but if you mark many
(say, thousands) messages, this slows things down significantly(1). For
this reason, you can disable this by setting ‘mu4e-headers-show-target’
to ‘nil’.
something is a special kind of mark; you can use it to mark messages
for ‘something’, and then decide later what the ‘something’ should be(2)
Later, you can set the actual mark using ‘M-x
mu4e-mark-resolve-deferred-marks’ (<#>). Alternatively, mu4e will ask
you when you try to execute the marks (<x>).
---------- Footnotes ----------
(1) this uses an Emacs feature called _overlays_, which are slow when
used a lot in a buffer
(2) This kind of ‘deferred marking’ is similar to the facility in
dired, midnight commander (<https://www.midnight-commander.org/>) and
the like, and uses the same key binding (<insert>).

File: mu4e.info, Node: Executing the marks, Next: Trashing messages, Prev: What to mark for, Up: Marking
8.3 Executing the marks
=======================
After you have marked some messages, you can execute them with <x> (‘M-x
mu4e-mark-execute-all’).
A hook, ‘mu4e-mark-execute-pre-hook’, is available which is run right
before execution of each mark. The hook is called with two arguments,
the mark and the message itself.

File: mu4e.info, Node: Trashing messages, Next: Leaving the headers buffer, Prev: Executing the marks, Up: Marking
8.4 Trashing messages
=====================
For regular mailboxes, trashing works like other marks: when executed,
the message is flagged as trashed. Depending on your mailbox provider,
the trash flag is used to automatically move the message to the trash
folder (‘mu4e-trash-folder’) for instance.
Some mailboxes behave differently however and they don’t interpret
the trash flag. In cases like Gmail, the message must be _moved_ to the
trash folder and the trash flag must not be used.

File: mu4e.info, Node: Leaving the headers buffer, Next: Built-in marking functions, Prev: Trashing messages, Up: Marking
8.5 Leaving the headers buffer
==============================
When you quit or update a headers buffer that has marked messages (for
example, by doing a new search), mu4e asks you what to do with them,
depending on the value of the variable ‘mu4e-headers-leave-behavior’ —
see its documentation.

File: mu4e.info, Node: Built-in marking functions, Next: Custom mark functions, Prev: Leaving the headers buffer, Up: Marking
8.6 Built-in marking functions
==============================
Some examples of mu4e’s built-in marking functions.
• _Mark the message at point for trashing_: press <d>
• _Mark all messages in the buffer as unread_: press ‘C-x h o’
• _Delete the messages in the current thread_: press ‘T D’
• _Mark messages with a subject matching “hello” for flagging_: press
‘% s hello RET’.

File: mu4e.info, Node: Custom mark functions, Next: Adding a new kind of mark, Prev: Built-in marking functions, Up: Marking
8.7 Custom mark functions
=========================
Sometimes, the built-in functions to mark messages may not be sufficient
for your needs. For this, mu4e offers an easy way to define your own
custom mark functions. You can choose one of the custom marker
functions by pressing <&> in the *note Headers view:: and *note Message
view::.
Custom mark functions are to be appended to the list
‘mu4e-headers-custom-markers’. Each of the elements of this list
(’markers’) is a list with two or three elements:
1. 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.
2. a predicate function, taking two arguments MSG and PARAM. MSG is
the message plist (see *note Message functions::) and 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.
3. (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.
Let’s look at an example: suppose we want to match all messages that
have more than _n_ recipients — we could do this with the following
recipe:
(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)
After evaluating this expression, you can use it by pressing <&> in
the headers buffer to select a custom marker function, and then <M> to
choose this particular one (M because it is the first character of the
description).
As you can see, it’s not very hard to define simple functions to
match messages. There are more examples in the defaults for
‘mu4e-headers-custom-markers’; see ‘mu4e-headers.el’ and see *note
Extending mu4e:: for general information about writing your own
functions.

File: mu4e.info, Node: Adding a new kind of mark, Prev: Custom mark functions, Up: Marking
8.8 Adding a new kind of mark
=============================
It is possible to configure new marks. To do so, one can add entries in
the list ‘mu4e-marks’. Such an element must have the following form:
(SYMBOL
:char STRING
:prompt STRING
:ask-target (lambda () TARGET)
:dyn-target (lambda (TARGET MSG) DYN-TARGET)
:show-target (lambda (DYN-TARGET) STRING)
:action (lambda (DOCID MSG DYN-TARGET) nil))
The symbol can be any symbol, except for ‘'unmark’ and ‘'something’,
which are reserved. The rest is a plist with the following elements:
• ‘:char’ — the character to display in the headers view.
• ‘:prompt’ — the prompt to use when asking for marks (used for
example when marking a whole thread).
• ‘:ask-target’ — a function run once per bulk-operation, and thus
suitable for querying the user about a target for move-like marks.
If nil, the TARGET passed to ‘:dyn-target’ is nil.
• ‘:dyn-target’ — a function run once per message (The message is
passed as MSG to the function). This function allows to compute a
per-message target, for refile-like marks. If nil, the DYN-TARGET
passed to the ‘:action’ is the TARGET obtained as above.
• ‘:show-target’ — how to display the target in the headers view. If
‘:show-target’ is nil the DYN-TARGET is shown (and DYN-TARGET must
be a string).
• ‘:action’ — the action to apply on the message when the mark is
executed.
As an example, suppose we would like to add a mark for tagging
messages (GMail-style), then we can run the following code (after
loading mu4e):
(add-to-list 'mu4e-marks
'(tag
:char "g"
:prompt "gtag"
:ask-target (lambda () (read-string "What tag do you want to add?"))
:action (lambda (docid msg target)
(mu4e-action-retag-message msg (concat "+" target)))))
As another example, suppose we would like to “archive and mark read”
a message (GMail-style), then we can run the following code (after
loading mu4e):
(add-to-list 'mu4e-marks
'(archive
:char "A"
:prompt "Archive"
:show-target (lambda (target) "archive")
:action (lambda (docid msg target)
;; must come before proc-move since retag runs
;; 'sed' on the file
(mu4e-action-retag-message msg "-\\Inbox")
(mu4e~proc-move docid nil "+S-u-N"))))
Adding to ‘mu4e-marks’ list allows to use the mark in bulk operations
(for example when tagging a whole thread), but does not bind the mark to
a key to use at the top-level. This must be done separately. In our
example:
(mu4e~headers-defun-mark-for tag)
(mu4e~headers-defun-mark-for archive)
(define-key mu4e-headers-mode-map (kbd "g") 'mu4e-headers-mark-for-tag)
(define-key mu4e-headers-mode-map (kbd "A") 'mu4e-headers-mark-for-archive)

File: mu4e.info, Node: Contexts, Next: Dynamic folders, Prev: Marking, Up: Top
9 Contexts
**********
* Menu:
* What are contexts::Defining the concept
* Context policies::How to determine the current context
* Contexts and special folders::Using context variables to determine them
* Contexts example::How to define contexts
It can be useful to switch between different sets of settings in mu4e; a
typical example is the case where you have different e-mail accounts for
private and work email, each with their own values for folders, e-mail
addresses, mailservers and so on.
The ‘mu4e-context’ system is a mu4e-specific mechanism to allow for
that; users can define different contexts corresponding with groups of
setting and either manually switch between them, or let mu4e determine
the right context based on some user-provided function.
Note that there are a number of existing ways to switch accounts in
mu4e, for example using the method described in the *note Tips and
Tricks:: section of this manual. Those still work — but the new
mechanism has the benefit of being a core part of ‘mu4e’, thus allowing
for deeper integration.

File: mu4e.info, Node: What are contexts, Next: Context policies, Up: Contexts
9.1 What are contexts
=====================
Let’s see what’s contained in a context. Most of it is optional.
A ‘mu4e-context’ is Lisp object with the following members:
• name: the name of the context, e.g. work or private
• vars: an association-list (alist) of variable settings for this
account.
• enter-func: an (optional) function that takes no parameter and is
invoked when entering the context. You can use this for extra
setup etc.
• leave-func: an (optional) function that takes no parameter and is
invoked when leaving the context. You can use this for clearing
things up.
• match-func: an (optional) function that takes an MSG message plist
as argument, and returns non-nil if this context matches the
situation. mu4e uses the first context that matches, in a couple
of situations:
• when starting mu4e to determine the starting context; in this
case, MSG is nil. You can use e.g. the host you’re running
or the time of day to determine which context matches.
• before replying to or forwarding a message with the given
message plist as parameter, or nil when composing a brand new
message. The function should return t when this context is
the right one for this message, or nil otherwise.
• when determining the target folders for deleting, refiling
etc; see *note Contexts and special folders::.
mu4e uses a variable ‘mu4e-contexts’, which is a list of such
objects.

File: mu4e.info, Node: Context policies, Next: Contexts and special folders, Prev: What are contexts, Up: Contexts
9.2 Context policies
====================
When you have defined contexts and you start mu4e it decides which
context to use based on the variable ‘mu4e-context-policy’; similarly,
when you compose a new message, the context is determined using
‘mu4e-compose-context-policy’.
For both of these, you can choose one of the following policies:
• a symbol ‘always-ask’: unconditionally ask the user what context to
pick.
The other choices only apply if none of the contexts match (i.e.,
none of the contexts’ match-functions returns ‘t’). We have the
following options:
• a symbol ‘ask’: ask the user if mu4e can’t figure things out the
context by itself (through the match-function). This is a good
policy if there are no match functions, or if the match functions
don’t cover all cases.
• a symbol ‘ask-if-none’: if there’s already a context, don’t change
it; otherwise, ask the user.
• a symbol ‘pick-first’: pick the first (default) context. This is a
good choice if you want to specify context for special case, and
fall back to the first one if none match.
• ‘nil’: don’t change the context; this is useful if you don’t change
contexts very often, and e.g. manually changes contexts with ‘M-x
mu4e-context-switch’.

File: mu4e.info, Node: Contexts and special folders, Next: Contexts example, Prev: Context policies, Up: Contexts
9.3 Contexts and special folders
================================
As we discussed in *note Folders:: and *note Dynamic folders::, mu4e
recognizes a number of special folders: ‘mu4e-sent-folder’,
‘mu4e-drafts-folder’, ‘mu4e-trash-folder’ and ‘mu4e-refile-folder’.
When you have a headers-buffer with messages that belong to different
contexts (say, a few different accounts), it is desirable for each of
them to use the specific folders for their own context — so, for
instance, if you trash a message, it needs to go to the trash-folder for
the account it belongs to, which is not necessarily the current context.
To make this easy to do, whenever mu4e needs to know the value for
such a special folder for a given message, it tries to determine the
appropriate context using ‘mu4e-context-determine’ (and policy nil; see
*note Context policies::). If it finds a matching context, it let-binds
the ‘vars’ for that account, and then determines the value for the
folder. It does not, however, call the ‘enter-func’ or ‘leave-func’,
since we are not really switching contexts.
In practice, this means that as long as each of the accounts has a
good match-func, all message operations automatically find the
appropriate folders.

File: mu4e.info, Node: Contexts example, Prev: Contexts and special folders, Up: Contexts
9.4 Example
===========
Let’s explain how contexts work by looking at an example. We define two
contexts, ‘Private’ and ‘Work’ for a fictional user _Alice Derleth_.
Note that in this case, we automatically switch to the first context
when starting; see the discussion in the previous section.
(setq mu4e-contexts
`( ,(make-mu4e-context
:name "Private"
:enter-func (lambda () (mu4e-message "Entering Private context"))
:leave-func (lambda () (mu4e-message "Leaving Private context"))
;; we match based on the contact-fields of the message
:match-func (lambda (msg)
(when msg
(mu4e-message-contact-field-matches msg
:to "aliced@home.example.com")))
:vars '( ( user-mail-address . "aliced@home.example.com" )
( user-full-name . "Alice Derleth" )
( mu4e-compose-signature .
(concat
"Alice Derleth\n"
"Lauttasaari, Finland\n"))))
,(make-mu4e-context
:name "Work"
:enter-func (lambda () (mu4e-message "Switch to the Work context"))
;; no leave-func
;; we match based on the maildir of the message
;; this matches maildir /Arkham and its sub-directories
:match-func (lambda (msg)
(when msg
(string-match-p "^/Arkham" (mu4e-message-field msg :maildir))))
:vars '( ( user-mail-address . "aderleth@miskatonic.example.com" )
( user-full-name . "Alice Derleth" )
( mu4e-compose-signature .
(concat
"Prof. Alice Derleth\n"
"Miskatonic University, Dept. of Occult Sciences\n"))))
,(make-mu4e-context
:name "Cycling"
:enter-func (lambda () (mu4e-message "Switch to the Cycling context"))
;; no leave-func
;; we match based on the maildir of the message; assume all
;; cycling-related messages go into the /cycling maildir
:match-func (lambda (msg)
(when msg
(string= (mu4e-message-field msg :maildir) "/cycling")))
:vars '( ( user-mail-address . "aderleth@example.com" )
( user-full-name . "AliceD" )
( mu4e-compose-signature . nil)))))
;; set `mu4e-context-policy` and `mu4e-compose-policy` to tweak when mu4e should
;; guess or ask the correct context, e.g.
;; start with the first (default) context;
;; default is to ask-if-none (ask when there's no context yet, and none match)
;; (setq mu4e-context-policy 'pick-first)
;; compose with the current context is no context matches;
;; default is to ask
;; (setq mu4e-compose-context-policy nil)
A couple of notes about this example:
• You can manually switch the context use ‘M-x mu4e-context-switch’,
by default bound to ‘;’ in headers, view and main mode. The
current context appears in the mode-line.
• Normally, ‘M-x mu4e-context-switch’ does not call the enter or
leave functions if the ’new’ context is the same as the old one.
However, with a prefix-argument (‘C-u’), you can force mu4e to
invoke those function even in that case.
• The function ‘mu4e-context-current’ returns the current-context;
the current context is also visible in the mode-line when in
headers, view or main mode.
• You can set any kind of variable; including settings for mail
servers etc. However, settings such as ‘mu4e-mu-home’ are not
changeable after they have been set without quitting mu4e first.
• ‘leave-func’ (if defined) for the context we are leaving, is
invoked before the ‘enter-func’ (if defined) of the context we are
entering.
• ‘enter-func’ (if defined) is invoked before setting the variables.
• ‘match-func’ (if defined) is invoked just before
‘mu4e-compose-pre-hook’.
• See the variables ‘mu4e-context-policy’ and
‘mu4e-compose-context-policy’ to tweak what mu4e should do when no
context matches (or if you always want to be asked).
• Finally, be careful to get the quotations right — backticks, single
quotes and commas and note the ’.’ between variable name and its
value.

File: mu4e.info, Node: Dynamic folders, Next: Actions, Prev: Contexts, Up: Top
10 Dynamic folders
******************
In *note Folders::, we explained how you can set up mu4e’s special
folders:
(setq
mu4e-sent-folder "/sent" ;; sent messages
mu4e-drafts-folder "/drafts" ;; unfinished messages
mu4e-trash-folder "/trash" ;; trashed messages
mu4e-refile-folder "/archive") ;; saved messages
In some cases, having such static folders may not suffice — perhaps
you want to change the folders depending on the context. For example,
the folder for refiling could vary, based on the sender of the message.
To make this possible, instead of setting the standard folders to a
string, you can set them to be a _function_ that takes a message as its
parameter, and returns the desired folder name. This chapter shows you
how to do that. For a more general discussion of how to extend mu4e and
writing your own functions, see *note Extending mu4e::.
If you use mu4e-context, see *note Contexts and special folders:: for
what that means for these special folders.
* Menu:
* Smart refiling:: Automatically choose the target folder
* Other dynamic folders:: Flexible folders for sent, trash, drafts

File: mu4e.info, Node: Smart refiling, Next: Other dynamic folders, Up: Dynamic folders
10.1 Smart refiling
===================
When refiling messages, perhaps to archive them, it can be useful to
have different target folders for different messages, based on some
property of those message — smart refiling.
To accomplish this, we can set the refiling folder
(‘mu4e-refile-folder’) to a function that returns the actual refiling
folder for the particular message. An example should clarify this:
(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 some spefic address me go to /private
((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")
;; messages sent by me go to the sent folder
((mu4e-message-sent-by-me msg
(mu4e-personal-addresses))
mu4e-sent-folder)
;; everything else goes to /archive
;; important to have a catch-all at the end!
(t "/archive"))))
This can be very powerful; you can select some messages in the headers
view, then press <r>, and have them all marked for refiling to their
particular folders.
Some notes:
• We set ‘mu4e-refile-folder’ to an anonymous (lambda) function.
This function takes one argument, a message plist(1). The plist
corresponds to the message at point. See *note Message functions::
for a discussion on how to deal with them.
• In our function, we use a cond control structure; the function
returns the first of the clauses that matches. It’s important to
make the last clause a catch-all, so we always return _some_
folder.
• We use the convenience function
‘mu4e-message-contact-field-matches’, which evaluates to ‘t’ if any
of the names or e-mail addresses in a contact field (in this case,
the To:-field) matches the regular expression. With mu4e version
0.9.16 or newer, the contact field can in fact be a list instead of
a single value, such as ‘'(:to :cc)'’.
---------- Footnotes ----------
(1) a property list describing a message

File: mu4e.info, Node: Other dynamic folders, Prev: Smart refiling, Up: Dynamic folders
10.2 Other dynamic folders
==========================
Using the same mechanism, you can create dynamic sent-, trash-, and
drafts-folders. The message-parameter you receive for the sent and
drafts folder is the _original_ message, that is, the message you reply
to, or forward, or edit. If there is no such message (for example when
composing a brand new message) the message parameter is nil.
Let’s look at an example. Suppose you want a different trash folder
for work-email. You can achieve this with something like:
(setq mu4e-trash-folder
(lambda (msg)
;; the 'and msg' is to handle the case where msg is nil
(if (and msg
(mu4e-message-contact-field-matches msg :to "me@work.example.com"))
"/trash-work"
"/trash")))
Good to remember:
• The MSG parameter you receive in the function refers to the
_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 MSG
parameter is ‘nil’.
• When re-editing messages, the value of ‘mu4e-drafts-folder’ is
ignored.

File: mu4e.info, Node: Actions, Next: Extending mu4e, Prev: Dynamic folders, Up: Top
11 Actions
**********
mu4e lets you define custom actions for messages in *note Headers view::
and for both messages and attachments in *note 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 key <a> for actions on messages, and
key <A> for actions on attachments.
For general information extending mu4e and writing your own
functions, see *note Extending mu4e::.
* Menu:
* Defining actions::How to create an action
* Headers view actions::Doing things with message headers
* Message view actions::Doing things with messages
* Attachment actions::Doing things with attachments
* Example actions::Some more examples

File: mu4e.info, Node: Defining actions, Next: Headers view actions, Up: Actions
11.1 Defining actions
=====================
Defining a new custom action comes down to writing an elisp-function to
do the work. Functions that operate on messages receive a MSG
parameter, which corresponds to the message at point. Something like:
(defun my-action-func (msg)
"Describe my message function."
;; do stuff
)
Functions that operate on attachments receive a MSG parameter, which
corresponds to the message at point, and an ATTACHMENT-NUM, which is the
number of the attachment as seen in the message view. An attachment
function looks like:
(defun my-attachment-action-func (msg attachment-num)
"Describe my attachment function."
;; do stuff
)
After you have defined your function, you can add it to the list of
actions(1), either ‘mu4e-headers-actions’, ‘mu4e-view-actions’ or
‘mu4e-view-attachment-actions’. The format(2) of each action is a
cons-cell, ‘(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 look at some examples.
---------- Footnotes ----------
(1) Instead of defining the functions separately, you can obviously
also add a ‘lambda’-function directly to the list; however, separate
functions are easier to change
(2) 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;
mu4e warns you when you are using the old format.

File: mu4e.info, Node: Headers view actions, Next: Message view actions, Prev: Defining actions, Up: Actions
11.2 Headers view actions
=========================
Suppose we want to inspect the number of recipients for a message in the
*note Headers view::. We add the following to our configuration:
(defun show-number-of-recipients (msg)
"Display the number of recipients for the message at point."
(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
;; the 't' argument to add-to-list puts it at the end of the list
(add-to-list 'mu4e-headers-actions
'("Number of recipients" . show-number-of-recipients) t)
After evaluating this, ‘a N’ in the headers view shows the number of
recipients for the message at point.

File: mu4e.info, Node: Message view actions, Next: Attachment actions, Prev: Headers view actions, Up: Actions
11.3 Message view actions
=========================
As another example, suppose we would like to search for messages by the
sender of the message at point:
(defun search-for-sender (msg)
"Search for messages sent by the sender of the message at point."
(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)
If you wonder why we use ‘cdar’, remember that the From:-field is a
list of ‘(NAME . EMAIL)’ cells; thus, ‘cdar’ gets us the e-mail address
of the first in the list. From:-fields rarely contain multiple cells.

File: mu4e.info, Node: Attachment actions, Next: Example actions, Prev: Message view actions, Up: Actions
11.4 Attachment actions
=======================
Finally, let’s define an attachment action. As mentioned,
attachment-action functions receive _2_ arguments, the message and the
attachment number to use.
The following example action counts the number of lines in an
attachment, and defines <n> as its shortcut key (the <n> is prefixed to
the description).
(defun count-lines-in-attachment (msg attachnum)
"Count the number of lines in an attachment."
(mu4e-view-pipe-attachment msg attachnum "wc -l"))
;; defining 'n' as the shortcut
(add-to-list 'mu4e-view-attachment-actions
'("ncount lines" . count-lines-in-attachment) t)

File: mu4e.info, Node: Example actions, Prev: Attachment actions, Up: Actions
11.5 Example actions
====================
mu4e includes a number of example actions in the file ‘mu4e-actions.el’
in the source distribution (see ‘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.

File: mu4e.info, Node: Extending mu4e, Next: Old message view, Prev: Actions, Up: Top
12 Extending mu4e
*****************
mu4e is designed to be easily extensible — that is, write your own
emacs-lisp to make mu4e behave exactly as you want. Here, we provide
some guidelines for doing so.
* Menu:
* Extension points::Where to hook into mu4e
* Available functions::General helper functions
* Message functions::Working with messages
* Contact functions::Working with contacts
* Utility functions::Miscellaneous helpers

File: mu4e.info, Node: Extension points, Next: Available functions, Up: Extending mu4e
12.1 Extension points
=====================
There are a number of places where mu4e lets you plug in your own
functions:
• Custom functions for message headers in the message-view and
headers-view — see *note HV Custom headers::, *note OMSGV Custom
headers::
• Using message-specific folders for drafts, trash, sent messages and
refiling, based on a function — see *note Dynamic folders::
• Using an attachment-specific download-directory — see the variable
‘mu4e-attachment-dir’.
• Apply a function to a message in the headers view - see *note
Headers view actions::
• Apply a function to a message in the message view — see *note
Message view actions::
• Add a new kind of mark for use in the headers view - see *note
Adding a new kind of mark::
• Apply a function to an attachment — see *note Attachment actions::
• Custom function to mark certain messages — see *note Custom mark
functions::
• Using various _mode_-hooks, ‘mu4e-compose-pre-hook’ (see *note
Compose hooks::), ‘mu4e-index-updated-hook’ (see *note FAQ::)
You can also write your own functions without using the above. If you
want to do so, key useful functions are ‘mu4e-message-at-point’ (see
below), ‘mu4e-headers-for-each’ (to iterate over all headers, see its
docstring) and ‘mu4e-view-for-each-part’ (to iterate over all
parts/attachments, see its docstring). There is also
‘mu4e-view-for-each-uri’ to iterate of all the URIs in the current
message.
Another useful function is ‘mu4e-headers-find-if’ which searches for
a message matching a certain pattern; again, see its docstring.

File: mu4e.info, Node: Available functions, Next: Message functions, Prev: Extension points, Up: Extending mu4e
12.2 Available functions
========================
The whole of mu4e consists of hundreds of elisp functions. However, the
majority of those are for _internal_ use only; you can recognize them
easily, because they all start with ‘mu4e~’. These functions make all
kinds of assumptions, and they are subject to change, and should
therefore _not_ be used. The same is true for _variables_ that start
with ‘mu4e~’; don’t touch them. Let me repeat that:
Do not use mu4e~... functions or variables!
In addition, you should use functions in the right context; functions
that start with mu4e-view- are only applicable to the message view,
while functions starting with mu4e-headers- are only applicable to the
headers view. Functions without such prefixes are applicable
everywhere.

File: mu4e.info, Node: Message functions, Next: Contact functions, Prev: Available functions, Up: Extending mu4e
12.3 Message functions
======================
Many functions in mu4e deal with message plists (property lists). They
contain information about messages, such as sender and recipient,
subject, date and so on. To deal with these plists, there are a number
of ‘mu4e-message-’ functions (in ‘mu4e-message.el’), such as
‘mu4e-message-field’ and ‘mu4e-message-at-point’, and a shortcut to
combine the two, ‘mu4e-message-field-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:
(mu4e-message-field (mu4e-message-at-point) :subject)
Note that:
• The contact fields (To, From, Cc, Bcc) are lists of cons-pairs
‘(name . email)’; ‘name’ may be ‘nil’. So, for example:
(mu4e-message-field some-msg :to)
;; => (("Jack" . "jack@example.com") (nil . "foo@example.com"))
If you are only looking for a match in this list (e.g., “Is Jack
one of the recipients of the message?”), there is a convenience
function ‘mu4e-message-contact-field-matches’ to make this easy.
• The message body is only available in the message view, not in the
headers view.
Note that in headers-mode, you only have access to a reduced message
plist, without the information about the message-body or mime-parts;
mu4e does this for performance reasons. And even in view-mode, you do
not have access to arbitrary message-headers.
However, it is possible to get the information indirectly, using the
raw-message and some third-party tool like procmail’s formail:
(defun my-mu4e-any-message-field-at-point (hdr)
"Quick & dirty way to get an arbitrary header HDR at
point. Requires the 'formail' tool from procmail."
(replace-regexp-in-string "\n$" ""
(shell-command-to-string
(concat "formail -x " hdr " -c < "
(shell-quote-argument (mu4e-message-field-at-point :path))))))
12.3.1 Rewriting the message body
---------------------------------
Message body rewriting allows you to modify the message text that is
presented in the message view. This can be useful if the message needs
special processing, for instance for special filling or cleaning up
encoding artifacts (this is what mu4e uses this for internally).
To enable this, you can append your rewrite-function to
‘mu4e-message-body-rewrite-functions’; your function is expected to take
two parameters ‘MSG’ and ‘TXT’, which are the message-plist and the
body-text, which could be the result of earlier transformations,
including html->text conversion as per ‘mu4e-html2-text-command’. The
function is expected to return the transformed text.
As a fairly useless example, suppose we insist on reading mu4e as
MU4E:
(defun mu4e-to-MU4E-rewrite (msg txt)
(replace-regexp-in-string "mu4e" "MU4E" txt))
(add-to-list 'mu4e-message-body-rewrite-functions 'mu4e-to-MU4E-rewrite t)

File: mu4e.info, Node: Contact functions, Next: Utility functions, Prev: Message functions, Up: Extending mu4e
12.4 Contact functions
======================
It can sometimes be useful to discard or rewrite the contact information
that mu4e provides, for example to fix spelling errors, or omit unwanted
contacts.
To handle this, mu4e provides ‘mu4e-contact-process-function’, which,
if defined, is applied to each contact. If the result is nil, the
contact is discarded, otherwise the (modified or not) contact
information is used.
Each contact is a full e-mail address as you would see in a
contact-field of an e-mail message, e.g.,
"Foo Bar" <foo.bar@example.com>
or
cuux@example.com
An example ‘mu4e-contact-process-function’ might look like:
(defun my-contact-processor (contact)
(cond
;; remove unwanted
((string-match-p "evilspammer@example.com" contact) nil)
((string-match-p "noreply" contact) nil)
;;
;; jonh smiht --> John Smith
((string-match "jonh smiht" contact)
(replace-regexp-in-string "jonh smiht" "John Smith" contact))
(t contact)))
(setq mu4e-contact-process-function 'my-contact-processor)

File: mu4e.info, Node: Utility functions, Prev: Contact functions, Up: Extending mu4e
12.5 Utility functions
======================
‘mu4e-utils’ contains a number of utility functions; we list a few here.
See their docstrings for details:
• ‘mu4e-read-option’: read one option from a list. For example:
(mu4e-read-option "Choose an animal: "
'(("Monkey" . monkey) ("Gnu" . gnu) ("xMoose" . moose)))
The user is presented with:
Choose an animal: [M]onkey, [G]nu, [x]Moose
• ‘mu4e-ask-maildir’: ask for a maildir; try one of the shortcuts
(‘mu4e-maildir-shortcuts’), or the full set of available maildirs.
• ‘mu4e-running-p’: return ‘t’ if the mu4e process is running, ‘nil’
otherwise.
• ‘(mu4e-user-mail-address-p addr)’: return ‘t’ if ADDR is one of the
user’s e-mail addresses (as per ‘(mu4e-personal-addresses)’).
• ‘mu4e-log’ logs to the mu4e debugging log if it is enabled; see
‘mu4e-toggle-logging’.
• ‘mu4e-message’, ‘mu4e-warning’, ‘mu4e-error’ are the mu4e
equivalents of the normal elisp ‘message’, ‘user-error’ and ‘error’
functions.

File: mu4e.info, Node: Old message view, Next: Other tools, Prev: Extending mu4e, Up: Top
Appendix A The old message view
*******************************
Since version 1.6 mu4e defaults to the new, Gnus-based, message view, as
described in *Note Message view::, and we recommend it for all users.
However, the older view is still available, and this chapter is about
that one. While we recommend using the default one, you can still use
the old one by configuring it _before_ require’ing mu4e:
(setq mu4e-view-use-old t)
Users of use-package(1) can use the :init section for this.
If you want to change this, you need to fully restart mu4e (in
practice, this means you need to restart emacs.
After selecting a message in the *note Headers view::, it appears in
a message view window, which shows the message headers, followed by the
message body. Its major mode is ‘mu4e-view-mode’.
* Menu:
* Overview: OMSGV Overview. What is the Message View
* Keybindings: OMSGV Keybindings. Do things with your keyboard
* Attachments:: Opening and saving them
* Viewing images inline::Images display inside emacs
* Displaying rich-text messages::Dealing with HTML mail
* Verifying signatures and decryption: OMSGV Crypto. Support for cryptography
* Custom headers: OMSGV Custom headers. Your own headers
* Actions: OMSGV Actions. Defining and using actions.
---------- Footnotes ----------
(1) <https://jwiegley.github.io/use-package/>

File: mu4e.info, Node: OMSGV Overview, Next: OMSGV Keybindings, Up: Old message view
A.1 Overview
============
An example message view:
From: randy@epiphyte.com
To: julia@eruditorum.org
Subject: Re: some pics
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 Julia,
Some pics from our trip to Cerin Amroth. Enjoy!
All the best,
Randy.
On Sun 21 Dec 2003 09:06:34 PM EET, Julia wrote:
[....]
Some notes:
• The variable ‘mu4e-view-fields’ determines the header fields to be
shown; see ‘mu4e-header-info’ for a list of built-in fields. Apart
from the built-in fields, you can also create custom fields using
‘mu4e-header-info-custom’; see *note OMSGV Custom headers::.
• You can set the date format with the variable
‘mu4e-date-format-long’.
• By default, only the names of contacts in address fields are
visible (see ‘mu4e-view-show-addresses’ to change this). You can
view the e-mail addresses by clicking on the name, or pressing
<M-RET>.
• You can compose a message for the contact at point by either
clicking <[mouse-2]> or pressing <C>.
• The body text can be line-wrapped using visual-line-mode. mu4e
defines <w> to toggle between the wrapped and unwrapped state. If
you want to do this automatically when viewing a message, invoke
‘visual-line-mode’ in your ‘mu4e-view-mode-hook’.
• For messages that support it, you can toggle between html and text
versions using ‘mu4e-view-toggle-html’, bound to <h>;
• You can hide cited parts in messages (the parts starting with “>”)
using ‘mu4e-view-hide-cited’, bound to <#>. If you want to do this
automatically for every message, invoke the function in your
‘mu4e-view-mode-hook’.
• For search-related operations, see *note Searching::.
• You can scroll down the message using <SPC>; if you do this at the
end of a message,it automatically takes you to the next one. If
you want to prevent this behavior, set ‘mu4e-view-scroll-to-next’
to ‘nil’.

File: mu4e.info, Node: OMSGV Keybindings, Next: Attachments, Prev: OMSGV Overview, Up: Old message view
A.2 Keybindings
===============
You can find most things you can do with this message in the _Mu4e_
menu, or by using the keyboard; the default bindings are:
key description
==============================================================
n,p view the next, previous message
],[ move to the next, previous unread message
y select the headers view (if it's visible)
RET scroll down
M-RET open URL at point / attachment at point
SPC scroll down, if at end, move to next message
S-SPC scroll up
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
= mark for removing trash flag ('untrash')
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
<insert>,* mark for 'something' (decide later)
# resolve deferred 'something' 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)
C-u g visits multiple URLs
f fetch (download )the numbered URL.
C-u f fetches multiple URLs
k save the numbered URL in the kill-ring.
C-u k saves multiple URLs
e extract (save) one or more attachments (asks for numbers)
(or: <mouse-2> or S-RET with point on attachment)
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
----
; switch context
c copy address at point (with C-u copy long version)
h toggle between html/text (if available)
w toggle line wrapping
# toggle show/hide 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
C-S-u update mail & reindex
q leave the message view
For the marking commands, please refer to *note Marking messages::.

File: mu4e.info, Node: Attachments, Next: Viewing images inline, Prev: OMSGV Keybindings, Up: Old message view
A.3 Attachments
===============
By default, mu4e uses the xdg-open-program (1) or (on OS X) the open
program for opening attachments. If you want to use another program,
you do so by setting the MU_PLAY_PROGRAM environment variable to the
program to be used.
The default directory for attaching and extracting (saving)
attachmentsis your home directory (‘~/’); you can change this using the
variable ‘mu4e-attachment-dir’, for example:
(setq mu4e-attachment-dir "~/Downloads")
For more flexibility, ‘mu4e-attachment-dir’ can also be a
user-provided function. This function receives two parameters: the
file-name and the mime-type as found in the e-mail message(2) of the
attachment, either or both of which can be nil. For example:
(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
You can extract multiple attachments at once by prefixing the
extracting command by <C-u>; so ‘C-u e’ asks you for a range of
attachments to extract (for example, ‘1 3-6 8’). The range "‘a’" is a
shortcut for _all_ attachments.
---------- Footnotes ----------
(1) <https://www.freedesktop.org/wiki/Software/xdg-utils/>
(2) sadly, often application/octet-stream is used for the mime-type,
even if a better type is available

File: mu4e.info, Node: Viewing images inline, Next: Displaying rich-text messages, Prev: Attachments, Up: Old message view
A.4 Viewing images inline
=========================
It is possible to show images inline in the message view buffer if you
run Emacs in GUI-mode. You can enable this by setting the variable
‘mu4e-view-show-images’ to t. Since Emacs does not always handle images
correctly, this is not enabled by default. If you are using Emacs 24
with _ImageMagick_(1) support, make sure you call
‘imagemagick-register-types’ in your configuration, so it is used for
images.
;; enable inline images
(setq mu4e-view-show-images t)
;; use imagemagick, if available
(when (fboundp 'imagemagick-register-types)
(imagemagick-register-types))
---------- Footnotes ----------
(1) <http://www.imagemagick.org/>

File: mu4e.info, Node: Displaying rich-text messages, Next: OMSGV Crypto, Prev: Viewing images inline, Up: Old message view
A.5 Displaying rich-text messages
=================================
mu4e normally prefers the plain-text version for messages that consist
of both a plain-text and html (rich-text) versions of the body-text.
You can change this by setting ‘mu4e-view-prefer-html’ to t. And you
can toggle this value (globally) using ‘h’ in the message view; this
also refreshes the message with the new setting.
Note, when using html-based rendering, you don’t get the hyperlink
shortcuts the text-version provides.
If there is only an html-version, or if the plain-text version is too
short in comparison with the html part(1), mu4e tries to convert the
html into plain-text for display.
With emacs 24.4 or newer, this defaults to ‘mu4e-shr2text’, which
uses the built-in shr renderer. For older emacs versions, this defaults
to the built-in ‘html2text’ function. In practice, the latter gives
much better results.
If you use ‘mu4e-shr2text’, it might be useful to emulate some of the
shr key bindings, with something like:
(add-hook 'mu4e-view-mode-hook
(lambda()
;; try to emulate some of the eww key-bindings
(local-set-key (kbd "<tab>") 'shr-next-link)
(local-set-key (kbd "<backtab>") 'shr-previous-link)))
If you’re using a dark theme, and the messages are hard to read, it
can help to change the luminosity, e.g.:
(setq shr-color-visible-luminance-min 80)
If your emacs does not have shr yet, it can be useful to use a custom
method. For that, you can set the variable ‘mu4e-html2text-command’ to
either a shell command or a function instead.
A.5.1 Html2text commands
------------------------
If ‘mu4e-html2text-command’ is a shell command, it is expected to take
html from standard input and write plain text in UTF-8 encoding on
standard output.
An example of such a program is the program that is actually _called_
html2text(2). After installation, you can set it up with something like
the following:
(setq mu4e-html2text-command "html2text -utf8 -width 72")
An alternative to this is the Python python-html2text package; after
installing that, you can tell mu4e to use it with something like:
(setq mu4e-html2text-command
"html2markdown | grep -v '&nbsp_place_holder;'")
On OS X, there is a program called textutil as yet another
alternative:
(setq mu4e-html2text-command
"textutil -stdin -format html -convert txt -stdout")
A.5.2 Html2text functions
-------------------------
If ‘mu4e-html2text-command’ refers to an elisp function, the function is
expected to take a message plist as its input, and returns the
transformed data.
You can easily create your own function, for instance:
(defun my-mu4e-html2text (msg)
"My html2text function; shows short message inline, show
long messages in some external browser (see `browse-url-generic-program')."
(let ((html (or (mu4e-message-field msg :body-html) "")))
(if (> (length html) 20000)
(progn
(mu4e-action-view-in-browser msg)
"[Viewing message in external browser]")
(mu4e-shr2text msg))))
(setq mu4e-html2text-command 'my-mu4e-html2text)
A.5.3 Privacy aspects
---------------------
When opening your messages in a graphical browser, it may expose you
doing so to the sender, due to the presence of specially crafted image
URLs, or Javascript.
If that is an issue, it is recommended to use a browser (or browser
profile) that does not load images. The same applies to Javascript.
---------- Footnotes ----------
(1) this is e.g. for the case where the text-part is only a short
blurb telling you to use the html-version; see
‘mu4e-view-html-plaintext-ratio-heuristic’
(2) <http://www.mbayer.de/html2text/>

File: mu4e.info, Node: OMSGV Crypto, Next: OMSGV Custom headers, Prev: Displaying rich-text messages, Up: Old message view
A.6 Crypto
==========
The mu4e message view supports decryption of encrypted messages, as well
as verification of signatures. For signing/encrypting messages your
outgoing messages, see *note Signing and encrypting::.
For all of this to work, ‘gpg-agent’ must be running, and it must set
the environment variable GPG_AGENT_INFO. You can check from Emacs with
<M-x getenv GPG_AGENT_INFO>.
In many mainstream Linux/Unix desktop environments, everything works
out-of-the-box, but if your environment does not automatically start
‘gpg-agent’, you can do so by hand:
$ eval $(gpg-agent --daemon)
This starts the daemon, and sets the environment variable.
Some users have reported problems with certain S/MIME-signed messages
where mu checks if the certificate has been revoked. This can be
avoided by adding disable-crl-checks to ~/.gnupg/gpgsm.conf;
alternatively, you could use the gnus-based viewer.
A.6.1 Decryption
----------------
If you receive messages that are encrypted (using PGP/MIME), mu4e can
try to decrypt them, base on the setting of ‘mu4e-decryption-policy’.
If you set it to t, mu4e attempts to decrypt messages automatically;
this is the default. If you set it to nil, mu4e _won’t_ attempt to
decrypt anything. Finally, if you set it to 'ask, it asks you what to
do, each time an encrypted message is encountered.
When opening an encrypted message, mu consults gpg-agent to see if it
already has unlocked the key needed to decrypt the message; if not, it
prompts you for a password (typically with a separate top-level window).
This is only needed once per session.
A.6.2 Verifying signatures
--------------------------
Some e-mail messages are cryptographically signed, and mu4e can check
the validity of these signatures. If a message has one or more
signatures, the message view shows an extra header Signature: (assuming
it is part of your ‘mu4e-view-fields’), and one or more ‘verdicts’ of
the signatures found; either verified, unverified or error. For
instance:
Signature: unverified (Details)
or
Signature: verified Darrow Andromedus <darrow@rising.com> (Details)
You can see the details of the signature verification by activating
the Details or pressing <v>. This pops up a little window with the
details of the signatures found and whether they could be verified or
not.
Note that mu4e does not check whether the signer is the same as the
sender of the message, since this would cause too many false negatives
for senders that use an address that is not part of their certificate.
Also, the From: address can easily be forged.
For more information, see the ‘mu-verify’ manual page.

File: mu4e.info, Node: OMSGV Custom headers, Next: OMSGV Actions, Prev: OMSGV Crypto, Up: Old message view
A.7 Custom headers
==================
Sometimes the normal headers that mu4e offers (Date, From, To, Subject,
etc.) may not be enough. For these cases, mu4e offers _custom headers_
in both the headers-view and the message-view.
See *note HV Custom headers:: for an example of this; the difference
for the message-view is that you should add your custom header to
‘mu4e-view-fields’ rather than ‘mu4e-headers-fields’.

File: mu4e.info, Node: OMSGV Actions, Prev: OMSGV Custom headers, Up: Old message view
A.8 Actions
===========
You can perform custom functions (“actions”) on messages and their
attachments. For a general discussion on how to define your own, see
*note Actions::.
A.8.1 Message 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’; mu4e defines a number of example actions.
A.8.2 MIME-part actions
-----------------------
MIME-part actions allow you to act upon MIME-parts in a message - such
as attachments. For now, these actions are defined and documented in
‘mu4e-view-attachment-actions’.
A.8.3 Attachment actions
------------------------
Note – these actions are only available for the old message view; see
*Note Old message view::.
Similarly, there is ‘mu4e-view-attachment-action’ (<A>) for actions
on attachments, which you can specify with
‘mu4e-view-attachment-actions’.
mu4e predefines a number of attachment-actions:
• 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’ opens 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 a _temporary copy_ of the attachment.

File: mu4e.info, Node: Other tools, Next: Example configs, Prev: Old message view, Up: Top
Appendix B Other tools
**********************
In this chapter, we discuss some ways in which mu4e can cooperate with
other tools.
* Menu:
* Emacs default::Making mu4e the default emacs e-mail program
* Org-mode links::Adding mu4e to your organized life
* Org-contacts::Hooking up with org-contacts
* BBDB::Hooking up with the Insidious Big Brother Database
* iCalendar::Replying to iCal events
* Sauron::Getting new mail notifications with Sauron
* Speedbar::A special frame with your folders
* Dired:: Attaching files using dired
* Hydra:: Custom shortcut menus
* iCalendar Integration:: Enabling iCalendar invite processing in mu4e

File: mu4e.info, Node: Emacs default, Next: Org-mode links, Up: Other tools
B.1 Emacs default
=================
Emacs allows you to select an e-mail program as the default program it
uses when you press <C-x m> (‘compose-mail’), call ‘report-emacs-bug’
and so on. If you want to use mu4e for this, you can do so by adding
the following to your configuration:
(setq mail-user-agent 'mu4e-user-agent)
Similarly, to specify mu4e as your preferred method for reading mail,
customize the variable ‘read-mail-command’.
(set-variable 'read-mail-command 'mu4e)
(*note Emacs: (Sending Mail)Top.)

File: mu4e.info, Node: Org-mode links, Next: Org-contacts, Prev: Emacs default, Up: Other tools
B.2 Org-mode links
==================
It can be useful to include links to e-mail messages or search queries
in your org-mode files. mu4e supports this by default, unless you set
mu4e-support-org to ‘nil’.
You can use the normal org-mode mechanisms to store links: ‘M-x
org-store-link’ stores a link to a particular message when you are in
*note Message view::. When you are in *note Headers view::, ‘M-x
org-store-link’ links to the _query_ if
‘mu4e-org-link-query-in-headers-mode’ is non-‘nil’, and to the
particular message otherwise (which is the default).
You can insert this link later with ‘M-x org-insert-link’. From
org-mode, 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 typically bound to ‘C-c C-o’.
You can also directly _capture_ such links — for example, to add
e-mail messages to your todo-list. For that, mu4e-org has a function
‘mu4e-org-store-and-capture’. This captures the message-at-point (or
header — see the discussion on ‘mu4e-org-link-query-in-headers-mode’
above), then calls org-mode’s capture functionality.
You can add some specific capture-template for this. In your capture
templates, the following mu4e-specific values are available:
item | description
-----------------------------------------------------+------------------------
%:date, %:date-timestamp, %d:date-timestamp-inactive | date, org timestamps
%:from, %:fromname, %:fromaddress | sender, name/address
%:to, %:toname, %:toaddress | recipient, name/address
%:maildir | maildir for the message
%:message-id | message-id
%:path | file system path
%:subject | message subject
For example, to add a message to your todo-list, and set a deadline
for processing it within two days, you could add this to
‘org-capture-templates’:
("P" "process-soon" entry (file+headline "todo.org" "Todo")
"* TODO %:fromname: %a %?\nDEADLINE: %(org-insert-time-stamp (org-read-date nil t \"+2d\"))")
If you use the functionality a lot, you may want to define
key-bindings for that in headers and view mode:
(define-key mu4e-headers-mode-map (kbd "C-c c") 'mu4e-org-store-and-capture)
(define-key mu4e-view-mode-map (kbd "C-c c") 'mu4e-org-store-and-capture)

File: mu4e.info, Node: Org-contacts, Next: BBDB, Prev: Org-mode links, Up: Other tools
B.3 Org-contacts
================
Note, mu4e supports built-in address autocompletion; *note Address
autocompletion::, and that is the recommended way to do this. However,
it is also possible to manage your addresses with org-mode, using
org-contacts(1).
mu4e-actions defines a useful action (*note Actions::) for adding a
contact based on the From:-address in the message at point. To enable
this, add to your configuration something like:
(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)
After this, you should be able to add contacts using <a o> in the
headers view and the message view, using the org-capture mechanism.
Note, the shortcut character <o> is due to the first character of
org-contact-add.
---------- Footnotes ----------
(1) <https://julien.danjou.info/projects/emacs-packages#org-contacts>

File: mu4e.info, Node: BBDB, Next: iCalendar, Prev: Org-contacts, Up: Other tools
B.4 BBDB
========
Note, mu4e supports built-in address autocompletion; *note Address
autocompletion::, and that is the recommended way to do this. However,
it is also possible to manage your addresses with the current
(2015-06-23) development release of BBDB, or releases of BBDB after
3.1.2.(1).
To enable BBDB, add to your ‘~/.emacs’ (or its moral equivalent, such
as ‘~/.emacs.d/init.el’) the following _after_ the ‘(require 'mu4e)’
line:
;; Load BBDB (Method 1)
(require 'bbdb-loaddefs)
;; OR (Method 2)
;; (require 'bbdb-loaddefs "/path/to/bbdb/lisp/bbdb-loaddefs.el")
;; OR (Method 3)
;; (autoload 'bbdb-insinuate-mu4e "bbdb-mu4e")
;; (bbdb-initialize 'message 'mu4e)
(setq bbdb-mail-user-agent 'mu4e-user-agent)
(setq mu4e-view-mode-hook 'bbdb-mua-auto-update)
(setq mu4e-compose-complete-addresses nil)
(setq bbdb-mua-pop-up t)
(setq bbdb-mua-pop-up-window-size 5)
(setq mu4e-view-show-addresses t)
After this, you should be able to:
• In mu4e-view mode, add the sender of the email to BBDB with <C-u :>
• Tab-complete addresses from BBDB when composing emails
• View the BBDB contact while viewing a message
---------- Footnotes ----------
(1) <https://savannah.nongnu.org/projects/bbdb/>

File: mu4e.info, Node: iCalendar, Next: Sauron, Prev: BBDB, Up: Other tools
B.5 iCalendar
=============
When Gnus’ article-mode is chosen (*note Message view::), it is possible
to view and reply to iCalendar events. To enable this feature, add
(require 'mu4e-icalendar)
(mu4e-icalendar-setup)
to your configuration. If you want that the original invitation
message be automatically trashed after sending the message created by
clicking on the buttons “Accept”, “Tentative”, or “Decline”, also add:
(setq mu4e-icalendar-trash-after-reply t)
When you reply to an iCal event, a line may be automatically added to
the diary file of your choice. You can specify that file with
(setq mu4e-icalendar-diary-file "/path/to/your/diary")
Note that, if the specified file is not your main diary file, add
#include "/path/to/your/diary" to you main diary file to display the
events.
To enable optional iCalendar→Org sync functionality, add the
following:
(setq gnus-icalendar-org-capture-file "~/org/notes.org")
(setq gnus-icalendar-org-capture-headline '("Calendar"))
(gnus-icalendar-org-setup)
Both the capture file and the headline(s) inside it must already
exist.
By default, ‘gnus-icalendar-org-setup’ adds a temporary capture
template to the variable ‘org-capture-templates’, with the description
“used by gnus-icalendar-org”, and the shortcut key “#”. If you want to
use your own template, create it using the same key and description.
This will prevent the temporary one from being installed next time you
‘gnus-icalendar-org-setup’ is called.
The full default capture template is:
("#" "used by gnus-icalendar-org" entry
(file+olp ,gnus-icalendar-org-capture-file
,gnus-icalendar-org-capture-headline)
"%i" :immediate-finish t)
where the values of the variables ‘gnus-icalendar-org-capture-file’
and ‘gnus-icalendar-org-capture-headline’ are inserted via macro
expansion.
If, for example, you wanted to store ical events in a date tree,
prompting for the date, you could use the following:
("#" "used by gnus-icalendar-org" entry
(file+olp+datetree path-to-capture-file)
"%i" :immediate-finish t :time-prompt t)
Note that the default behaviour for ‘datetree’ targets in this
situation is to store the event at the date that you capture it, not at
the date that it is scheduled. That’s why I’ve suggested using the
‘:timeprompt t’ argument. This gives you an opportunity to set the time
to the correct value yourself.
You can extract the event time directly, and have the ‘org-capture’
functions use that to set the ‘datetree’ location:
(defun my-catch-event-time (orig-fun &rest args)
"Set org-overriding-default-time to the start time of the capture event"
(let ((org-overriding-default-time (date-to-time
(gnus-icalendar-event:start (car args)))))
(apply orig-fun args)))
(advice-add 'gnus-icalendar:org-event-save :around #'my-catch-event-time)
If you do this, you’ll want to omit the ‘:timeprompt t’ setting from
your capture template.

File: mu4e.info, Node: Sauron, Next: Speedbar, Prev: iCalendar, Up: Other tools
B.6 Sauron
==========
The Emacs package sauron(1) (by the same author) can be used to get
notifications about new mails. If you run something like the below
script from your crontab (or have some other way of having it execute
every _n_ minutes), you receive notifications in the sauron-buffer when
new messages arrive.
#!/bin/sh
# the mu binary
MU=mu
# 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
}
#
# -mmin -5: consider only messages that were created / changed in the
# the last 5 minutes
#
for f in `find $CHECKDIR -mmin -5 -a -type f -not -iname '.uidvalidity'`; do
subject=`$MU view $f | grep '^Subject:' | sed 's/^Subject://'`
sauron_msg "mail: $subject"
done
You might want to put:
(setq sauron-dbus-cookie t)
in your setup, to allow the script to find the D-Bus session bus, even
when running outside its session.
---------- Footnotes ----------
(1) Sauron can be found at <https://github.com/djcb/sauron>, or in
the MELPA (Milkypostman’s Emacs Lisp Package Archive) package repository
at <https://melpa.org/>

File: mu4e.info, Node: Speedbar, Next: Dired, Prev: Sauron, Up: Other tools
B.7 Speedbar
============
‘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.
To enable this, add (require 'mu4e-speedbar) to your configuration;
then, all you need to do to activate it is ‘M-x speedbar’. Then, when
then switching to the *note Main view::, the speedbar-frame is updated
with your bookmarks and maildirs.
For speed reasons, the list of maildirs is determined when mu4e
starts; if the list of maildirs changes while mu4e is running, you need
to restart 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.

File: mu4e.info, Node: Dired, Next: Hydra, Prev: Speedbar, Up: Other tools
B.8 Dired
=========
It is possible to attach files to mu4e messages using dired (*note
(emacs)Dired::), using the following steps (based on a post on the
mu-discuss mailing list by _Stephen Eglen_).
(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode)
Then, mark the file(s) in dired you would like to attach and press
C-c RET C-a, and you’ll be asked whether to attach them to an existing
message, or create a new one.

File: mu4e.info, Node: Hydra, Next: iCalendar Integration, Prev: Dired, Up: Other tools
B.9 Hydra
=========
People sometimes ask about having multi-character shortcuts for
bookmarks; an easy way to achieve this, is by using an emacs package
called Hydra(1).
With Hydra installed, we can add multi-character shortcuts, for
instance:
(defhydra my-mu4e-bookmarks-work (:color blue)
"work bookmarks"
("b" (mu4e-headers-search "banana AND maildir:/work") "banana")
("u" (mu4e-headers-search "flag:unread AND maildir:/work") "unread"))
(defhydra my-mu4e-bookmarks-personal (:color blue)
"personal bookmarks"
("c" (mu4e-headers-search "capybara AND maildir:/personal") "capybara")
("u" (mu4e-headers-search "flag:unread AND maildir:/personal") "unread"))
(defhydra my-mu4e-bookmarks (:color blue)
"mu4e bookmarks"
("p" (my-mu4e-bookmarks-personal/body) "Personal")
("w" (my-mu4e-bookmarks-work/body) "Work"))
Now, you can bind a convenient key to my-mu4e-bookmarks/body.
---------- Footnotes ----------
(1) <https://github.com/abo-abo/hydra>

File: mu4e.info, Node: iCalendar Integration, Prev: Hydra, Up: Other tools
B.10 iCalendar Integration
==========================
By default, mu4e presents iCalendar invitations as .vcs file
attachments. Experimental support is available to parse these
attachments in order to add the expected “Accept”, “Reject”, “Add to
Calendar” buttons. This requires using Gnus’ article view, which is the
default since mu4e version 1.6.
The minimal setup is:
(require 'mu4e-icalendar)
(mu4e-icalendar-setup)
To add the event to a diary file of your choice:
(setq mu4e-icalendar-diary-file "/path/to/your/diary")
To enable optional functionality to capture iCalendar events to your
org files:
(require 'org-agenda)
(setq gnus-icalendar-org-capture-file "~/org/notes.org")
(setq gnus-icalendar-org-capture-headline '("Calendar"))
(gnus-icalendar-org-setup)
NOTE: both the capture file and the headline(s) inside must already
exist.

File: mu4e.info, Node: Example configs, Next: FAQ, Prev: Other tools, Up: Top
Appendix C Example configs
**************************
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::Simplest configuration to get you going
* Longer configuration::A more extensive setup
* Gmail configuration::GMail-specific setup
* Other settings:CONF Other settings. Some other useful configuration

File: mu4e.info, Node: Minimal configuration, Next: Longer configuration, Up: Example configs
C.1 Minimal configuration
=========================
An (almost) minimal configuration for mu4e might look like this — as you
see, most of it is commented-out.
;; example configuration for mu4e
;; make sure mu4e is in your load-path
(require 'mu4e)
;; use mu4e for e-mail in emacs
(setq mail-user-agent 'mu4e-user-agent)
;; 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")

File: mu4e.info, Node: Longer configuration, Next: Gmail configuration, Prev: Minimal configuration, Up: Example configs
C.2 Longer configuration
========================
A somewhat longer configuration, showing some more things that you can
customize.
;; example configuration for mu4e
(require 'mu4e)
;; use mu4e for e-mail in emacs
(setq mail-user-agent 'mu4e-user-agent)
;; the next are relative to the root maildir
;; (see `mu info`).
;; 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
'((:maildir "/archive" :key ?a)
(:maildir "/inbox" :key ?i)
(:maildir "/work" :key ?w)
(:maildir "/sent" :key ?s)))
;; the headers to show in the headers list -- a pair of a 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) ;; alternatively, use :human-date
(:flags . 6)
(:from . 22)
(:subject . nil))) ;; alternatively, use :thread-subject
;; program to get mail; alternatives are 'fetchmail', 'getmail'
;; isync or your own shellscript. called when 'U' is pressed in
;; main view.
;; If you get your mail without an explicit command,
;; use "true" for the command (this is 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-compose-reply-to-address "foo@bar.example.com"
user-mail-address "foo@bar.example.com"
user-full-name "Foo X. Bar")
(setq mu4e-compose-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)

File: mu4e.info, Node: Gmail configuration, Next: CONF Other settings, Prev: Longer configuration, Up: Example configs
C.3 Gmail configuration
=======================
_Gmail_ is a popular e-mail provider; let’s see how we can make it work
with mu4e. Since we are using IMAP, you must enable that in the Gmail
web interface (in the settings, under the “Forwarding and
POP/IMAP”-tab).
Gmail users may also be interested in *note Including related
messages::, and in *note Skipping duplicates::.
C.3.1 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 offlineimap; on Debian (and derivatives
like Ubuntu), this is as easy as:
$ sudo apt-get install offlineimap
while on Fedora (and similar) you need:
$ sudo yum install offlineimap
Then, we can configure offlineimap by editing ‘~/.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
Obviously, you need to 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/.cache/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/.cache/mu/xapian]
/ processing mail; processed: 520; updated/new: 0, cleaned-up: 0
mu: elapsed: 0 second(s)
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
troubleshoot as we are setting things up.
Note: when using encryption, you probably do _not_ want to
synchronize your Drafts-folder, since it contains the unencrypted
messages. You can use OfflineIMAP’s folderfilter for that.
C.3.2 Settings
--------------
Next step: let’s make a mu4e configuration for this:
(require 'mu4e)
;; use mu4e for e-mail in emacs
(setq mail-user-agent 'mu4e-user-agent)
(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)
;; (See the documentation for `mu4e-sent-messages-behavior' if you have
;; additional non-Gmail addresses and want assign them different
;; behavior.)
;; 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
'( (:maildir "/INBOX" :key ?i)
(:maildir "/[Gmail].Sent Mail" :key ?s)
(:maildir "/[Gmail].Trash" :key ?t)
(:maildir "/[Gmail].All Mail" :key ?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"
mu4e-compose-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)
And that’s it — put the above in your ‘~/.emacs’, change USERNAME
etc. to your own, and restart Emacs, and run ‘M-x mu4e’.

File: mu4e.info, Node: CONF Other settings, Prev: Gmail configuration, Up: Example configs
C.4 Other settings
==================
Finally, here are some more settings that are useful, but not enabled by
default for various reasons.
;; use 'fancy' non-ascii characters in various places in mu4e
(setq mu4e-use-fancy-chars t)
;; save attachment to my desktop (this can also be a function)
(setq mu4e-attachment-dir "~/Desktop")
;; attempt to show images when viewing messages
(setq mu4e-view-show-images t)

File: mu4e.info, Node: FAQ, Next: Tips and Tricks, Prev: Example configs, Up: Top
Appendix D FAQ — Frequently Asked Questions
*******************************************
In this chapter we list a number of actual and anticipated questions and
their answers.
* Menu:
* General::General questions and answers about mu4e
* Retrieving mail::Getting mail and indexing
* Reading messages::Dealing with incoming messages
* Writing messages::Dealing with outgoing messages
* Known issues::Limitations we know about

File: mu4e.info, Node: General, Next: Retrieving mail, Up: FAQ
D.1 General
===========
D.1.1 Results from ‘mu’ and mu4e differ - why?
----------------------------------------------
In general, the same queries for ‘mu’ and mu4e should yield the same
results. If they differ, this is usually because one of the following
reasons:
• different options: mu4e defaults to having
mu4e-headers-include-related, and mu4e-headers-results-limit set to
500. However, the command-line ‘mu find’’s corresponding
--include-related is false, and there’s no limit (--maxnum).
• reverse sorting: The results may be different when mu4e and ‘mu
find’ do not both sort their results in the same direction.
• shell quoting issues: Depending on the shell, various shell
metacharacters in search query (such as *) may be expanded by the
shell before ‘mu’ ever sees them, and the query may not be what you
think it is. Quoting is necessary.
D.1.2 The unread/all counts in the main-screen differ from the ’real’ numbers - what’s going on?
------------------------------------------------------------------------------------------------
For speed reasons, the counts do not exclude messages that no longer
exist in the file-system, nor does it exclude duplicate messages; *Note
mu-mu4e-differ::.
D.1.3 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., <DEL> for
delete, <m> for move and <t> for trash) apply to all selected messages.
You can also use functions like ‘mu4e-headers-mark-thread’ (<T>),
‘mu4e-headers-mark-subthread’ (<t>) to mark whole threads at the same
time, and ‘mu4e-headers-mark-pattern’ (<%>) to mark all messages
matching a certain regular expression.
D.1.4 Can I automatically apply the marks on messages when leaving the headers buffer?
--------------------------------------------------------------------------------------
Yes you can — see the documentation for the variable
mu4e-headers-leave-behavior.
D.1.5 How can I set mu4e as the default e-mail client in Emacs?
---------------------------------------------------------------
See *note Emacs default::.
D.1.6 Can mu4e use some fancy Unicode instead of these boring plain-ASCII ones?
-------------------------------------------------------------------------------
Glad you asked! Yes, if you set ‘mu4e-use-fancy-chars’ to t, mu4e uses
such fancy characters in a number of places. Since not all fonts
include all characters, you may want to install the unifont and/or
symbola fonts on your system.
D.1.7 Can I start mu4e in the background?
-----------------------------------------
Yes — if you provide a prefix-argument (<C-u>), mu4e starts, but does
not show the main-window.
D.1.8 Does mu4e support searching for CJK (Chinese-Japanese-Korean) characters?
-------------------------------------------------------------------------------
Yes, if you have Xapian 1.2.8 or newer, and set the environment variable
XAPIAN_CJK_NGRAM to non-empty before indexing, both when using mu from
the command-line and from mu4e.
D.1.9 How can I customize the function to select a folder?
----------------------------------------------------------
The mu4e-completing-read-function variable can be customized to select a
folder in any way. The variable can be set to a function that receives
five arguments, following completing-read. The default value is
‘ido-completing-read’; to use emacs’s default behavior, set the variable
to ‘completing-read’. Helm users can use the same value, and by
enabling ‘helm-mode’ use helm-style completion.
D.1.10 With a lot of Maildir folders, jumping to them can get slow. What can I do?
----------------------------------------------------------------------------------
Set ‘mu4e-cache-maildir-list’ to ‘t’ (make sure to read its docstring).
D.1.11 How can I hide messages from the search results?
-------------------------------------------------------
See the variable ‘mu4e-headers-hide-predicate’.
For example, to filter out GMail’s spam, set it to:
(setq mu4e-headers-hide-predicate
(lambda (msg)
(string-suffix-p "Spam" (mu4e-message-field msg :maildir))))
D.1.12 I’m getting an error ’Variable binding depth exceeds max-specpdl-size’ when using mu4e – what can I do about it?
-----------------------------------------------------------------------------------------------------------------------
The error occurs because mu4e is binding more variables than emacs
allows for, by default. You can avoid this by setting a higher value,
e.g. by adding the following to your configuration:
(setq max-specpdl-size 5000)

File: mu4e.info, Node: Retrieving mail, Next: Reading messages, Prev: General, Up: FAQ
D.2 Retrieving mail
===================
D.2.1 How can I get notifications when receiving mail?
------------------------------------------------------
There is ‘mu4e-index-updated-hook’, which gets triggered when the
indexing process triggered sees an update (not just new mail though).
To use this hook, put something like the following in your setup
(assuming you have aplay and some soundfile, change as needed):
(add-hook 'mu4e-index-updated-hook
(defun new-mail-sound ()
(shell-command "aplay ~/Sounds/boing.wav&")))
D.2.2 Getting mail through a local mailserver. What should I use for ‘mu4e-get-mail-command’?
---------------------------------------------------------------------------------------------
Use the literal string "true" (or don’t do anything, it’s the default)
which then uses /bin/true (a command that does nothing and always
succeeds). This makes getting mail a no-op, but the messages are still
re-indexed.
D.2.3 How can I re-index my messages without getting new mail?
--------------------------------------------------------------
Use ‘M-x mu4e-update-index’
D.2.4 When I try to run mu index while mu4e is running I get errors
-------------------------------------------------------------------
For instance:
mu: mu_store_new_writable: xapian error
'Unable to get write lock on ~/.cache/mu/xapian: already locked
What to do about this? You get this error because the underlying
Xapian database is locked by some other process; it can be opened only
once in read-write mode. There is not much mu4e can do about this, but
if is another ‘mu’ instance that is holding the lock, you can ask it to
(gracefully) terminate:
pkill -2 -u $UID mu # send SIGINT
sleep 1
mu index
mu4e automatically restarts mu when it needs it. In practice, this
seems to work quite well.
D.2.5 How can I disable the Indexing... messages?
-------------------------------------------------
Set the variable ‘mu4e-hide-index-messages’ to non-nil.
D.2.6 IMAP-synchronization and file-name changes
------------------------------------------------
Some IMAP-synchronization programs such as mbsync (but not offlineimap)
don’t like it when message files do not change their names when they are
moved to different folders. mu4e can attempt to help with this - you
can set the variable ‘mu4e-change-filenames-when-moving’ to non-nil.
D.2.7 ‘offlineimap’ and UTF-7
-----------------------------
‘offlineimap’ uses IMAP’s UTF-7 for encoding non-ascii folder names,
while ‘mu’ expects UTF-8 (so, e.g. /まりもえ お(1) becomes
/&MH4wijCCMEgwSg-).
This is best solved by telling ‘offlineimap’ to use UTF-8 instead —
see <https://github.com/djcb/mu/issues/68#issuecomment-8598652>.
D.2.8 ‘mbsync’ or ‘offlineimap’ do not sync properly
----------------------------------------------------
Unfortunately, ‘mbsync’ and/or ‘offlineimap’ do not always agree with mu
about the meaning of various Maildir-flags. If you encounter unexpected
behavior, it is recommended you check before and after a sync-operation.
If the problem only shows up _after_ sync’ing, the problem is with the
sync-program, and it’s most productive to complain there.
Also, you may want to ensure that mu4e-index-lazy-check is kept at
its default (nil) value, since it seems ‘mbsync’ can make changes that
escape a ’lazy’ check.
Furthermore, there have been quite a few related queries on the
mailing-list; worthwhile to check out.
---------- Footnotes ----------
(1) some Japanese characters

File: mu4e.info, Node: Reading messages, Next: Writing messages, Prev: Retrieving mail, Up: FAQ
D.3 Reading messages
====================
D.3.1 Opening messages is slower than expected - why?
-----------------------------------------------------
mu4e is designed to be very fast, even with large amounts of mail.
However, if you experience slowdowns, here are some things to consider:
• opening messages while indexing: mu4e corresponds with the mu
server synchronously; this means that you can do only one thing at
a time. The one operation that potentially does take a bit of time
is indexing of mail, during which you have to wait for messages to
open. For some strategies to reduce that time, see the next
question.
• getting contact information can take some time: especially when
opening mu4e the first time and you have a _lot_ of contacts, it
can take a few seconds to process those. Note that mu4e 1.3 and
higher only get _changed_ contacts in subsequent updates (after and
indexing operation), so this should be less of a concern.
• decryption / sign verification: encrypted / signed messages
sometimes require network access, and this may take a while;
certainly if the needed servers cannot be found. Part of this may
be that influential environment variables are not set in the emacs
environment.
If you still experience unexpected slowness, you can of course file a
ticket, but please be sure to mention the following:
• are all messages slow or only some messages?
• if it’s only some messages, is there something specific about them?
• in addition, please a (sufficiently censored version of) a message
that is slow
• is opening _always_ slow or only sometimes? When?
D.3.2 How can I view attached images in my message view buffers? See
--------------------------------------------------------------------
*note Viewing images inline::.
D.3.3 How can I word-wrap long lines in when viewing a message?
---------------------------------------------------------------
You can toggle between wrapped and non-wrapped states using <w>. If you
want to do this automatically, invoke ‘visual-line-mode’ in your
‘mu4e-view-mode-hook’.
D.3.4 How can I perform custom actions on messages and attachments?
-------------------------------------------------------------------
See *note Actions::.
D.3.5 Does mu4e support crypto (i.e., decrypting messages and verifying signatures)?
------------------------------------------------------------------------------------
Yes — it is possible to do both (note, only PGP/MIME is supported). In
the *note Main view:: the support is indicated by a big letter C on the
right hand side of the mu4e version. See *note Decryption:: and *note
Verifying signatures::. For encryption and signing messages, see *note
Writing messages::.
D.3.6 How can I prevent mu4e from automatically marking messages as ‘read’ when I read them?
--------------------------------------------------------------------------------------------
Set ‘mu4e-view-auto-mark-as-read’ to ‘nil’.
D.3.7 Does mu4e support including all related messages in a thread, like Gmail does?
------------------------------------------------------------------------------------
Yes — see *note Including related messages::.
D.3.8 There seems to be a lot of duplicate messages — how can I get rid of them?
--------------------------------------------------------------------------------
See *note Skipping duplicates::.
D.3.9 How can I use the eww browser to view rich-text messages?
---------------------------------------------------------------
With a new enough emacs, this happens automatically. See *note
Html2text functions:: for some details.
D.3.10 Some messages are almost unreadable in emacs — can I view them in an external web browser?
-------------------------------------------------------------------------------------------------
Indeed, airlines often send messages that heavily depend on html and are
hard to digest inside emacs. Fortunately, there’s an _action_ (*note
Message view actions::) defined for this. Simply add to your
configuration:
(add-to-list 'mu4e-view-actions
'("ViewInBrowser" . mu4e-action-view-in-browser) t)
Now, when viewing such a difficult message, type ‘aV’, and the
message opens inside a web browser. You can influence the browser with
‘browse-url-generic-program’; and see *note Privacy aspects::.
D.3.11 How can I read encrypted messages that I sent?
-----------------------------------------------------
Since you do not own the recipient’s key you typically cannot read those
mails — so the trick is to encrypt outgoing mails with your key, too.
This can be automated by adding the following snippet to your
configuration (courtesy of user kpachnis):
(require 'epg-config)
(setq mml2015-use 'epg
epg-user-id "gpg_key_id"
mml2015-encrypt-to-self t
mml2015-sign-with-sender t)
D.3.12 Can I ‘bounce’ or ‘resend’ messages?
-------------------------------------------
Somewhat — it is possible to edit a (copy of) an existing message and
then send it, using ‘M-x mu4e-compose-resend’. This gives you a raw
copy of the message, including all headers, encoded parts and so on.
Reason for this is that for resending, it is important not to change
anything (except perhaps for the To: address when bouncing); since we
cannot losslessly decode an existing message, you get the raw version.

File: mu4e.info, Node: Writing messages, Next: Known issues, Prev: Reading messages, Up: FAQ
D.4 Writing messages
====================
D.4.1 What’s the deal with replies to messages I wrote myself?
--------------------------------------------------------------
Like many other mail-clients, mu4e treats replies to messages you wrote
yourself as special — these messages keep the same To: and Cc: as the
original message. This is to ease the common case of following up to a
message you wrote earlier.
D.4.2 How can I automatically set the From:-address for a reply-message?
------------------------------------------------------------------------
See *note Compose hooks::.
D.4.3 How can I dynamically determine the folders for draft/sent/trashed messages?
----------------------------------------------------------------------------------
See *note Dynamic folders::.
D.4.4 How can I define aliases for (groups of) e-mail addresses?
----------------------------------------------------------------
See *note (emacs) Mail Aliases::.
D.4.5 How can I automatically add some header to an outgoing message?
---------------------------------------------------------------------
See *note Compose hooks::.
D.4.6 How can I influence the way the original message looks when replying/forwarding?
--------------------------------------------------------------------------------------
Since ‘mu4e-compose-mode’ derives from ‘message-mode’, you can re-use
many of its facilities. *note (message)Insertion Variables::.
D.4.7 How can I easily include attachments in the messages I write?
-------------------------------------------------------------------
You can drag-and-drop from your desktop; alternatively, you can use
dired — see *note Dired::.
D.4.8 mu4e seems to remove myself from the Cc:-list; how can I prevent that?
----------------------------------------------------------------------------
Set ‘mu4e-compose-keep-self-cc’ to t in your configuration.
D.4.9 mu4e include myself from the Cc:-list; how can I prevent that?
--------------------------------------------------------------------
You need list your personal addresses by passing one or more
--my-address=... to mu init. Note that the
‘mu4e-user-mail-address-list’ which was used in older mu4e versions is
no longer used. Also see the entries for version 1.4 in NEWS.org (‘N’)
in the main-menu.
D.4.10 How can I start a new message-thread from a reply?
---------------------------------------------------------
Remove the In-Reply-To header, and mu4e automatically removes the
(hidden) References header as well when sending it. This makes the
message show up as a top-level message rather than as a response.
D.4.11 How can I attach an existing message?
--------------------------------------------
Use ‘mu4e-action-capture-message’ (i.e., ‘a c’ in the headers view) to
‘capture’ the to-be-attached message, then when editing the message, use
‘M-x mu4e-compose-attach-captured-message’.
D.4.12 How can I sign or encrypt messages?
------------------------------------------
You can do so using Emacs’ MIME-support — check the Attachments-menu
while composing a message. Also see *note Signing and encrypting::.
You can do so using Emacs’ MIME-support — check the Attachments-menu
while composing a message. Also see *note Signing and encrypting::.
D.4.13 Address auto-completion does not work?
---------------------------------------------
If you have set ‘mu4e-compose-complete-only-personal’ to non-nil, mu4e
only completes ’personal’ addresses - so you tell it about your e-mail
addresses when setting up the database (mu init); *note Initializing the
message store::.
D.4.14 Can I use BBDB with mu4e?
--------------------------------
Yes, with releases of BBDB after 3.1.2. *note BBDB::.
D.4.15 How can I get rid of the message buffer after sending?
-------------------------------------------------------------
(setq message-kill-buffer-on-exit t)
D.4.16 Sending big messages is slow and blocks emacs — what can I do about it?
------------------------------------------------------------------------------
For this, there’s <https://github.com/jwiegley/emacs-async> (also
available from the Emacs package repository); add the following snippet
to your configuration:
(require 'smtpmail-async)
(setq
send-mail-function 'async-smtpmail-send-it
message-send-mail-function 'async-smtpmail-send-it)
With this, messages are sent using a background Emacs instance.
A word of warning though, this tends to not be as reliable as sending
the message in the normal, synchronous fashion, and people have reported
silent failures, where mail sending fails for some reason without any
indication of that.
You can check the progress of the background by checking the
*Messages*-buffer, which should show something like:
Delivering message to "William Shakespeare" <will@example.com>...
Mark set
Saving file /home/djcb/Maildir/sent/cur/20130706-044350-darklady:2,S...
Wrote /home/djcb/Maildir/sent/cur/20130706-044350-darklady:2,S
Sending...done
The first and final messages are the most important, and there may be
considerable time between them, depending on the size of the message.
D.4.17 Is it possible to compose messages in a separate frame?
--------------------------------------------------------------
Yes — set the variable ‘mu4e-compose-in-new-frame’ to ‘t’.
D.4.18 How can I apply format=flowed to my outgoing messages?
-------------------------------------------------------------
This enables receiving clients that support this feature to reflow
paragraphs. Plain text emails with Content-Type: text/plain;
format=flowed can be reflowed (i.e. line endings removed, paragraphs
refilled) by receiving clients that support this standard. Clients that
don’t support this, show them as is, which means this feature is truly
non-invasive.
Here’s an explanatory blog post which also shows why this is a
desirable feature: <https://mathiasbynens.be/notes/gmail-plain-text> (if
you don’t have it, your mails mostly look quite bad especially on mobile
devices) and here’s the RFC with all the details:
<https://www.ietf.org/rfc/rfc2646.txt>.
Since version 0.9.17, mu4e sends emails with format=flowed by setting
(setq mu4e-compose-format-flowed t)
in your Emacs init file (‘~/.emacs’ or ‘~/.emacs.d/init.el’). The
transformation of your message into the proper format is done at the
time of sending. For this to happen properly, you should write each
paragraph of your message of as a long line (i.e. without carriage
return). If you introduce unwanted newlines in your paragraph, use
‘M-q’ to reformat it as a single line.
If you want to send the message with paragraphs on single lines but
without format=flowed (because, say, the receiver does not understand
the latter as it is the case for Google or Github), use ‘M-x
use-hard-newlines’ (to turn ‘use-hard-newlines’ off) or uncheck the box
format=flowed in the Text menu when composing a message.
D.4.19 How can I force images to be shown at the end of my messages, regardless of where I insert them?
-------------------------------------------------------------------------------------------------------
User Marcin Borkowski has a solution:
(defun mml-attach-file--go-to-eob (orig-fun &rest args)
"Go to the end of buffer before attaching files."
(save-excursion
(save-restriction
(widen)
(goto-char (point-max))
(apply orig-fun args))))
(advice-add 'mml-attach-file :around #'mml-attach-file--go-to-eob)
D.4.20 How can I avoid Outlook display issues?
----------------------------------------------
Limited testing shows that certain Outlook clients do not work well with
inline replies, and the entire message including-and-below the first
quoted section is collapsed. This means recipients may not even notice
important inline text, especially if there is some top-posted content.
This has been observed on OS X, Windows, and Web-based Outlook clients
accessing Office 365.
It appears the bug is triggered by the standard reply regex "On ...
wrote:". Changing "On", or removing the trailing ":" appears to fix the
bug (in limited testing). Therefore, a simple work-around is to set
‘message-citation-line-format‘ to something slightly non-standard, such
as:
(setq message-citation-line-format "On %Y-%m-%d at %R %Z, %f wrote...")

File: mu4e.info, Node: Known issues, Prev: Writing messages, Up: FAQ
D.5 Known issues
================
Although they are not really _questions_, we end this chapter with a
list of known issues 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.
D.5.1 UTF-8 language environment is required
--------------------------------------------
mu4e does not work well if the Emacs language environment is not UTF-8;
so, if you encounter problems with encodings, be sure to have
‘(set-language-environment "UTF-8")’ in your ‘~/.emacs’ (or its moral
equivalents in other places).
D.5.2 Thread handling is incomplete
-----------------------------------
While threads are calculated and are visible in the headers buffer, you
cannot collapse/open them.
D.5.3 Key-bindings are _somewhat_ hard-coded.
---------------------------------------------
That is, the main menu assumes the default key-bindings, as do the
clicks-on-bookmarks.
For a more complete list, please refer to the issues-list in the
github-repository.

File: mu4e.info, Node: Tips and Tricks, Next: How it works, Prev: FAQ, Up: Top
Appendix E Tips and Tricks
**************************
* Menu:
* Fancy characters:: Non-ascii characters in the UI
* Refiling messages:: Moving message to some archive folder
* Saving outgoing messages:: Automatically save sent messages
* Confirmation before sending:: Check messages before sending

File: mu4e.info, Node: Fancy characters, Next: Refiling messages, Up: Tips and Tricks
E.1 Fancy characters
====================
When using ‘fancy characters’ (‘mu4e-use-fancy-chars’) with the
_Inconsolata_-font (and likely others as well), the display may be
slightly off; the reason for this issue is that Inconsolata does not
contain the glyphs for the ‘fancy’ arrows and the glyphs that are used
as replacements are too high.
To fix this, you can use something like the following workaround (in
your .emacs-file):
(when (equal window-system 'x)
(set-fontset-font "fontset-default" 'unicode "Dejavu Sans Mono")
(set-face-font 'default "Inconsolata-10"))
Other fonts with good support for Unicode are unifont and symbola.
For a more complete solution, but with greater overhead, you can also
try the _unicode-fonts_ package:
(require 'unicode-fonts)
(require 'persistent-soft) ; To cache the fonts and reduce load time
(unicode-fonts-setup)

File: mu4e.info, Node: Refiling messages, Next: Saving outgoing messages, Prev: Fancy characters, Up: Tips and Tricks
E.2 Refiling messages
=====================
By setting ‘mu4e-refile-folder’ to a function, you can dynamically
determine where messages are to be refiled. If you want to do this
based on the subject of a message, you can use a function that matches
the subject against a list of regexes in the following way. First, set
up a variable ‘my-mu4e-subject-alist’ containing regexes plus associated
mail folders:
(defvar my-mu4e-subject-alist '(("kolloqui\\(um\\|a\\)" . "/Kolloquium")
("Calls" . "/Calls")
("Lehr" . "/Lehre")
("webseite\\|homepage\\|website" . "/Webseite"))
"List of subjects and their respective refile folders.")
Now you can use the following function to automatically refile
messages based on their subject line:
(defun my-mu4e-refile-folder-function (msg)
"Set the refile folder for MSG."
(let ((subject (mu4e-message-field msg :subject))
(folder (or (cdar (member* subject my-mu4e-subject-alist
:test #'(lambda (x y)
(string-match (car y) x))))
"/General")))
folder))
Note the "/General" folder: it is the default folder in case the
subject does not match any of the regexes in ‘my-mu4e-subject-alist’.
In order to make this work, you’ll of course need to set
‘mu4e-refile-folder’ to this function:
(setq mu4e-refile-folder 'my-mu4e-refile-folder-function)
If you have multiple accounts, you can accommodate them as well:
(defun my-mu4e-refile-folder-function (msg)
"Set the refile folder for MSG."
(let ((maildir (mu4e-message-field msg :maildir))
(subject (mu4e-message-field msg :subject))
folder)
(cond
((string-match "Account1" maildir)
(setq folder (or (catch 'found
(dolist (mailing-list my-mu4e-mailing-lists)
(if (mu4e-message-contact-field-matches
msg :to (car mailing-list))
(throw 'found (cdr mailing-list)))))
"/Account1/General")))
((string-match "Gmail" maildir)
(setq folder "/Gmail/All Mail"))
((string-match "Account2" maildir)
(setq folder (or (cdar (member* subject my-mu4e-subject-alist
:test #'(lambda (x y)
(string-match
(car y) x))))
"/Account2/General"))))
folder))
This function actually uses different methods to determine the refile
folder, depending on the account: for _Account2_, it uses
‘my-mu4e-subject-alist’, for the _Gmail_ account it simply uses the
folder “All Mail”. For Account1, it uses another method: it files the
message based on the mailing list to which it was sent. This requires
another variable:
(defvar my-mu4e-mailing-lists
'(("mu-discuss@googlegroups.com" . "/Account1/mu4e")
("pandoc-discuss@googlegroups.com" . "/Account1/Pandoc")
("auctex@gnu.org" . "/Account1/AUCTeX"))
"List of mailing list addresses and folders where
their messages are saved.")

File: mu4e.info, Node: Saving outgoing messages, Next: Confirmation before sending, Prev: Refiling messages, Up: Tips and Tricks
E.3 Saving outgoing messages
============================
Like ‘mu4e-refile-folder’, the variable ‘mu4e-sent-folder’ can also be
set to a function, in order to dynamically determine the save folder.
One might, for example, wish to automatically put messages going to
mailing lists into the trash (because you’ll receive them back from the
list anyway). If you have set up the variable ‘my-mu4e-mailing-lists’
as mentioned, you can use the following function to determine a save
folder:
(defun my-mu4e-sent-folder-function (msg)
"Set the sent folder for the current message."
(let ((from-address (message-field-value "From"))
(to-address (message-field-value "To")))
(cond
((string-match "my.address@account1.example.com" from-address)
(if (member* to-address my-mu4e-mailing-lists
:test #'(lambda (x y)
(string-match (car y) x)))
"/Trash"
"/Account1/Sent"))
((string-match "my.address@gmail.com" from-address)
"/Gmail/Sent Mail")
(t (mu4e-ask-maildir-check-exists "Save message to maildir: ")))))
Note that this function doesn’t use ‘(mu4e-message-field msg
:maildir)’ to determine which account the message is being sent from.
The reason is that the function in ‘mu4e-sent-folder’ is called when you
send the message, but before mu4e has created the message struct from
the compose buffer, so that ‘mu4e-message-field’ cannot be used.
Instead, the function uses ‘message-field-value’, which extracts the
values of the headers in the compose buffer. This means that it is not
possible to extract the account name from the message’s maildir, so
instead the from address is used to determine the account.
Again, the function shows three different possibilities: for the
first account (my.address@account1.example.com) it uses
‘my-mu4e-mailing-lists’ again to determine if the message goes to a
mailing list. If so, the message is put in the trash folder, if not, it
is saved in /Account1/Sent. For the second (Gmail) account, sent mail
is simply saved in the Sent Mail folder.
If the from address is not associated with Account1 or with the Gmail
account, the function uses ‘mu4e-ask-maildir-check-exists’ to ask the
user for a maildir to save the message in.

File: mu4e.info, Node: Confirmation before sending, Prev: Saving outgoing messages, Up: Tips and Tricks
E.4 Confirmation before sending
===============================
To protect yourself from sending messages too hastily, you can add a
final confirmation, which you can of course make as elaborate as you
wish.
(add-hook 'message-send-hook
(lambda ()
(unless (yes-or-no-p "Sure you want to send this?")
(signal 'quit nil))))
Another option is to simply set ‘message-confirm-send’ to non-nil so
the question “Send message?” is asked for confirmation.

File: mu4e.info, Node: How it works, Next: Debugging, Prev: Tips and Tricks, Up: Top
Appendix F How it works
***********************
While perhaps not interesting for all users of mu4e, some curious souls
may want to know how mu4e does its job.
* Menu:
* High-level overview::How the pieces fit together
* mu server::The mu process running in the background
* Reading from the server::Processing responses from the server
* The message s-expression::What messages look like from the inside

File: mu4e.info, Node: High-level overview, Next: mu server, Up: How it works
F.1 High-level overview
=======================
At 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 its subdirectories), and new mail comes in using
tools like fetchmail, offlineimap, or through a local mail server.
• 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.

File: mu4e.info, Node: mu server, Next: Reading from the server, Prev: High-level overview, Up: How it works
F.2 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 was the
first approach — mu4e would invoke e.g., mu find and process the output
in Emacs.
However, with this 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
starts a simple shell, in which you can give commands to ‘mu’, which
then spits out the results/errors. ‘mu server’ is not meant for humans,
but it can be used manually, which is great for debugging.

File: mu4e.info, Node: Reading from the server, Next: The message s-expression, Prev: mu server, Up: How it works
F.3 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_, and interpret those using
the Emacs-function ‘read-from-string’. See *note The message
s-expression:: for details on the format.
So, now let’s look at how we process the data from mu server in
Emacs. We’ll leave out a lot of details, mu4e-specifics, and look at a
bit more generic approach.
The first thing to do is to create a process (for example, with
‘start-process’), and then register a filter function for it, which is
invoked whenever the process has some data for us. 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 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 partly in the
mu-server man-page and more completely in the output of mu server
--commands.
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’ (<$>).

File: mu4e.info, Node: The message s-expression, Prev: Reading from the server, Up: How it works
F.4 The message s-expression
============================
A typical message s-expression looks 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 "C8233AB82D81EE81AF0114E4E74@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 ("C8384574032D81EE81AF0114E4E74@123213.mail.example.com"
"38203498230942D81EE81AF0114E4E74@123213.mail.example.com")
:in-reply-to "38203498230942D81EE81AF0114E4E74@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-message-field’ to shield you from some of the
implementation details that are subject to change; and see the other
convenience functions in ‘mu4e-message.el’.
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’).(1)
• 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 *note Headers view:: come from the database and do
not have :attachments. :body-txt or :body-html fields. Message in
the *note Message view:: use the actual message file, and do
include these fields.
F.4.1 Example: ping-pong
------------------------
As an example of the communication between mu4e and ‘mu’, let’s look at
the ping-pong-sequence. When mu4e starts, it sends a command ping to
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 calls mu4e-proc-ping, and registers a (lambda) function
for mu4e-proc-pong-func, to handle the response.
-> (ping)
<-<prefix>(:pong "mu" :props (:version "x.x.x" :doccount 78545))
When we receive such a pong (in ‘mu4e-proc.el’), the lambda function
we registered is called, and it compares the version we got from the
pong with the version we expected, and raises an error if they differ.
---------- Footnotes ----------
(1) 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.

File: mu4e.info, Node: Debugging, Next: GNU Free Documentation License, Prev: How it works, Up: Top
Appendix G Debugging
********************
As explained in *note 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*, and in the *note Main view::, *note
Headers view:: and *note Message view::, there’s a keybinding <$> that
takes 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. mu itself keeps a log as well, you can find it in
<MUHOME>/mu.log, on Unix typically ~/.cache/mu/mu.log.

File: mu4e.info, Node: GNU Free Documentation License, Prev: Debugging, Up: Top
Appendix H GNU Free Documentation License
*****************************************
Version 1.2, November 2002
Copyright © 2000,2001,2002 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document “free” in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative
works of the document must themselves be free in the same sense.
It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless
of subject matter or whether it is published as a printed book. We
recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it can
be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The
“Document”, below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as “you”. You accept
the license if you copy, modify or distribute the work in a way
requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document’s overall
subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document
is in part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or
of legal, commercial, philosophical, ethical or political position
regarding them.
The “Invariant Sections” are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in the
notice that says that the Document is released under this License.
If a section does not fit the above definition of Secondary then it
is not allowed to be designated as Invariant. The Document may
contain zero Invariant Sections. If the Document does not identify
any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed
of pixels) generic paint programs or (for drawings) some widely
available drawing editor, and that is suitable for input to text
formatters or for automatic translation to a variety of formats
suitable for input to text formatters. A copy made in an otherwise
Transparent file format whose markup, or absence of markup, has
been arranged to thwart or discourage subsequent modification by
readers is not Transparent. An image format is not Transparent if
used for any substantial amount of text. A copy that is not
“Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available DTD, and standard-conforming
simple HTML, PostScript or PDF designed for human modification.
Examples of transparent image formats include PNG, XCF and JPG.
Opaque formats include proprietary formats that can be read and
edited only by proprietary word processors, SGML or XML for which
the DTD and/or processing tools are not generally available, and
the machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, “Title
Page” means the text near the most prominent appearance of the
work’s title, preceding the beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document
whose title either is precisely XYZ or contains XYZ in parentheses
following text that translates XYZ in another language. (Here XYZ
stands for a specific section name mentioned below, such as
“Acknowledgements”, “Dedications”, “Endorsements”, or “History”.)
To “Preserve the Title” of such a section when you modify the
Document means that it remains a section “Entitled XYZ” according
to this definition.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These
Warranty Disclaimers are considered to be included by reference in
this License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and
has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. You
may not use technical measures to obstruct or control the reading
or further copying of the copies you make or distribute. However,
you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow the
conditions in section 3.
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than 100, and
the Document’s license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also clearly
and legibly identify you as the publisher of these copies. The
front cover must present the full title with all words of the title
equally prominent and visible. You may add other material on the
covers in addition. Copying with changes limited to the covers, as
long as they preserve the title of the Document and satisfy these
conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a machine-readable
Transparent copy along with each Opaque copy, or state in or with
each Opaque copy a computer-network location from which the general
network-using public has access to download using public-standard
network protocols a complete Transparent copy of the Document, free
of added material. If you use the latter option, you must take
reasonably prudent steps, when you begin distribution of Opaque
copies in quantity, to ensure that this Transparent copy will
remain thus accessible at the stated location until at least one
year after the last time you distribute an Opaque copy (directly or
through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of copies,
to give them a chance to provide you with an updated version of the
Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you
release the Modified Version under precisely this License, with the
Modified Version filling the role of the Document, thus licensing
distribution and modification of the Modified Version to whoever
possesses a copy of it. In addition, you must do these things in
the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of previous
versions (which should, if there were any, be listed in the
History section of the Document). You may use the same title
as a previous version if the original publisher of that
version gives permission.
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in
the Modified Version, together with at least five of the
principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you
from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below.
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document’s
license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled “History”, Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on the
Title Page. If there is no section Entitled “History” in the
Document, create one stating the title, year, authors, and
publisher of the Document as given on its Title Page, then add
an item describing the Modified Version as stated in the
previous sentence.
J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for
previous versions it was based on. These may be placed in the
“History” section. You may omit a network location for a work
that was published at least four years before the Document
itself, or if the original publisher of the version it refers
to gives permission.
K. For any section Entitled “Acknowledgements” or “Dedications”,
Preserve the Title of the section, and preserve in the section
all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered
in their text and in their titles. Section numbers or the
equivalent are not considered part of the section titles.
M. Delete any section Entitled “Endorsements”. Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled
“Endorsements” or to conflict in title with any Invariant
Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option designate
some or all of these sections as invariant. To do this, add their
titles to the list of Invariant Sections in the Modified Version’s
license notice. These titles must be distinct from any other
section titles.
You may add a section Entitled “Endorsements”, provided it contains
nothing but endorsements of your Modified Version by various
parties—for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of
a standard.
You may add a passage of up to five words as a Front-Cover Text,
and a passage of up to 25 words as a Back-Cover Text, to the end of
the list of Cover Texts in the Modified Version. Only one passage
of Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document
already includes a cover text for the same cover, previously added
by you or by arrangement made by the same entity you are acting on
behalf of, you may not add another; but you may replace the old
one, on explicit permission from the previous publisher that added
the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination all
of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique
by adding at the end of it, in parentheses, the name of the
original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the
combined work.
In the combination, you must combine any sections Entitled
“History” in the various original documents, forming one section
Entitled “History”; likewise combine any sections Entitled
“Acknowledgements”, and any sections Entitled “Dedications”. You
must delete all sections Entitled “Endorsements.”
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the documents
in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of a
storage or distribution medium, is called an “aggregate” if the
copyright resulting from the compilation is not used to limit the
legal rights of the compilation’s users beyond what the individual
works permit. When the Document is included in an aggregate, this
License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half
of the entire aggregate, the Document’s Cover Texts may be placed
on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket
the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also
include the original English version of this License and the
original versions of those notices and disclaimers. In case of a
disagreement between the translation and the original version of
this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled “Acknowledgements”,
“Dedications”, or “History”, the requirement (section 4) to
Preserve its Title (section 1) will typically require changing the
actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided for under this License. Any other
attempt to copy, modify, sublicense or distribute the Document is
void, and will automatically terminate your rights under this
License. However, parties who have received copies, or rights,
from you under this License will not have their licenses terminated
so long as such parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
<http://www.gnu.org/copyleft/>.
Each version of the License is given a distinguishing version
number. If the Document specifies that a particular numbered
version of this License “or any later version” applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If the
Document does not specify a version number of this License, you may
choose any version ever published (not as a draft) by the Free
Software Foundation.
ADDENDUM: How to use this License for your documents
====================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with
the Front-Cover Texts being LIST, and with the Back-Cover Texts
being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.

Tag Table:
Node: Top628
Ref: Top-Footnote-12909
Ref: Top-Footnote-22955
Ref: Top-Footnote-33051
Node: Introduction3176
Node: Why another e-mail client3556
Node: Other mail clients4166
Ref: Other mail clients-Footnote-14947
Ref: Other mail clients-Footnote-24982
Ref: Other mail clients-Footnote-35026
Ref: Other mail clients-Footnote-45062
Node: What mu4e does not do5093
Ref: What mu4e does not do-Footnote-16164
Ref: What mu4e does not do-Footnote-26203
Ref: What mu4e does not do-Footnote-36243
Node: Becoming a mu4e user6280
Ref: Becoming a mu4e user-Footnote-17687
Node: Getting started7740
Node: Requirements8581
Ref: Requirements-Footnote-19475
Ref: Requirements-Footnote-29505
Node: Installation9552
Ref: Building from a release tarball12083
Ref: Building from git12474
Ref: Installation-Footnote-114204
Ref: Installation-Footnote-214250
Ref: Installation-Footnote-314360
Node: Getting mail14394
Ref: Getting mail-Footnote-115596
Node: Initializing the message store15767
Node: Indexing your messages16720
Node: Basic configuration18236
Node: Folders18856
Ref: Folders-Footnote-119659
Node: Retrieval and indexing19938
Node: Sending mail24191
Node: Running mu4e26414
Node: Main view27461
Node: MV Overview27990
Node: Basic actions29148
Node: MV Bookmarks30001
Node: Miscellaneous31374
Node: Headers view32249
Node: HV Overview33009
Ref: HV Overview-Footnote-137331
Ref: HV Overview-Footnote-237422
Ref: HV Overview-Footnote-337529
Node: Keybindings37629
Node: HV Marking39679
Node: Sorting and threading40842
Ref: Sorting and threading-Footnote-142418
Node: HV Custom headers42509
Node: HV Actions44692
Node: Split view45402
Node: Message view46838
Node: MSGV Overview47674
Node: MSGV Keybindings48873
Node: MSGV Rich-text and images51417
Node: MSGV Custom headers53526
Node: MSGV Actions54062
Node: Editor view54819
Node: EV Overview55618
Node: EV Keybindings56033
Node: Address autocompletion56689
Ref: Address autocompletion-Footnote-158791
Node: Compose hooks58836
Node: Signing and encrypting62139
Node: Queuing mail63153
Node: Message signatures64447
Node: Other settings65081
Node: Searching65813
Node: Queries66778
Ref: Queries-Footnote-169887
Node: Bookmarks70001
Ref: Bookmarks-Footnote-174160
Node: Maildir searches74203
Node: Other search functionality76706
Ref: Including related messages78610
Ref: Skipping duplicates79229
Node: Marking79818
Node: Marking messages80653
Node: What to mark for81445
Ref: What to mark for-Footnote-183022
Ref: What to mark for-Footnote-283119
Node: Executing the marks83315
Node: Trashing messages83761
Node: Leaving the headers buffer84385
Node: Built-in marking functions84818
Node: Custom mark functions85374
Node: Adding a new kind of mark87723
Node: Contexts90923
Node: What are contexts92090
Node: Context policies93742
Node: Contexts and special folders95215
Node: Contexts example96611
Node: Dynamic folders101484
Node: Smart refiling102751
Ref: Smart refiling-Footnote-1105284
Node: Other dynamic folders105329
Node: Actions106597
Node: Defining actions107492
Ref: Defining actions-Footnote-1108768
Ref: Defining actions-Footnote-2108944
Node: Headers view actions109131
Node: Message view actions110061
Node: Attachment actions110895
Node: Example actions111680
Node: Extending mu4e112071
Node: Extension points112602
Node: Available functions114394
Node: Message functions115305
Node: Contact functions118421
Node: Utility functions119659
Node: Old message view120881
Ref: Old message view-Footnote-1122302
Node: OMSGV Overview122352
Node: OMSGV Keybindings124598
Node: Attachments127459
Ref: Attachments-Footnote-1128897
Ref: Attachments-Footnote-2128960
Node: Viewing images inline129068
Ref: Viewing images inline-Footnote-1129896
Node: Displaying rich-text messages129934
Ref: Html2text functions132592
Ref: Privacy aspects133347
Ref: Displaying rich-text messages-Footnote-1133686
Ref: Displaying rich-text messages-Footnote-2133851
Node: OMSGV Crypto133893
Ref: Decryption134982
Ref: Verifying signatures135699
Node: OMSGV Custom headers136704
Node: OMSGV Actions137250
Node: Other tools139113
Node: Emacs default139849
Node: Org-mode links140477
Node: Org-contacts143205
Ref: Org-contacts-Footnote-1144286
Node: BBDB144360
Ref: BBDB-Footnote-1145730
Node: iCalendar145783
Node: Sauron149031
Ref: Sauron-Footnote-1150569
Node: Speedbar150739
Node: Dired151626
Node: Hydra152142
Ref: Hydra-Footnote-1153244
Node: iCalendar Integration153287
Node: Example configs154283
Node: Minimal configuration154826
Node: Longer configuration156037
Node: Gmail configuration158733
Node: CONF Other settings164112
Node: FAQ164657
Node: General165177
Ref: mu-mu4e-differ165370
Node: Retrieving mail170081
Ref: Retrieving mail-Footnote-1173747
Node: Reading messages173780
Node: Writing messages179376
Node: Known issues187930
Node: Tips and Tricks189064
Node: Fancy characters189451
Node: Refiling messages190467
Node: Saving outgoing messages194065
Node: Confirmation before sending196599
Node: How it works197203
Node: High-level overview197704
Node: mu server199204
Node: Reading from the server200229
Node: The message s-expression202585
Ref: The message s-expression-Footnote-1205810
Node: Debugging205997
Node: GNU Free Documentation License207036

End Tag Table

Local Variables:
coding: utf-8
End:
Reference in New Issue View Git Blame Copy Permalink