/
mu4e.texi
3484 lines (2857 loc) · 130 KB
/
mu4e.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\input texinfo.tex @c -*-texinfo-*-
@c %**start of header
@setfilename mu4e.info
@settitle mu4e user manual
@c Use proper quote and backtick for code sections in PDF output
@c Cf. Texinfo manual 14.2
@set txicodequoteundirected
@set txicodequotebacktick
@documentencoding UTF-8
@c %**end of header
@include texi.texi
@copying
Copyright @copyright{} 2012, 2013 Dirk-Jan C. Binnema
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end quotation
@end copying
@titlepage
@title @t{mu4e} - an e-mail client for Emacs
@subtitle version @value{mu-version}
@author Dirk-Jan C. Binnema
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@dircategory Emacs
@direntry
* mu4e: (mu4e). An email client for Emacs.
@end direntry
@contents
@ifnottex
@node Top
@top mu4e manual
@end ifnottex
@iftex
@node Welcome to mu4e
@unnumbered Welcome to mu4e
@end iftex
Welcome to @t{mu4e}!
@t{mu4e} (@t{mu}-for-emacs) is an e-mail client for GNU-Emacs version 23 and
later, built on top of the
@t{mu}@footnote{@url{http://www.djcbsoftware.nl/code/mu}} e-mail search
engine. @t{mu4e} is optimized for fast handling of large amounts of e-mail.
Some of mu4e's highlights:
@itemize
@item Fully search-based: there are no folders@footnote{that is, instead of
folders, you can use queries that match all messages in a folder}, only
queries
@item Fully documented, with example configurations
@item User-interface optimized for speed, with quick key strokes for common actions
@item Support for non-English languages (so ``angstrom'' will match ``Ångström'')
@item Asynchronous; heavy actions don't block @command{emacs}@footnote{currently,
the only exception to this is @emph{sending mail}; there are solutions for
that though - see the @ref{FAQ}}
@item Support for crypto
@item Writing rich-text e-mails using @t{org-mode}
@item Address auto-completion based on the contacts in your messages
@item Extendable with your own snippets of elisp
@end itemize
In this manual, we go through the installation of @t{mu4e}, do some basic
configuration and explain its daily use. We also show you how you can
customize @t{mu4e} for your needs.
At the end of the manual, there are some example configurations, to get you up
to speed quickly: @ref{Example configurations}. There's also an @ref{FAQ},
which should help you with some common questions.
@menu
* Introduction:: How it all began
* Getting started:: Setting things up
* Main view:: Where we go when starting @t{mu4e}
* Headers view:: Lists of message headers
* Message view:: Viewing specific messages
* Editor view:: Creating / editing messages
* Searching:: Some more background on searching/queries
* Marking:: Marking messages and performing actions
* Dynamic folders:: Folders that depend on the context
* Actions:: Defining and using custom actions
* Extending mu4e:: Writing code for @t{mu4e}
Appendices
* Interaction with other tools:: mu4e and the rest of the world
* Example configurations:: 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 @t{mu4e}
* Logging and debugging:: How to debug problems in @t{mu4e}
* GNU Free Documentation License:: The license of this manual
@end menu
@node Introduction
@chapter Introduction
@menu
* Why another e-mail client::
* Other mail clients::
* What mu4e does not do::
* Becoming a mu4e user::
@end menu
@node Why another e-mail client
@section Why another e-mail client?
Fair question.
I'm not sure the world needs yet another e-mail client, but perhaps @emph{I}
do! I (the author) spend a @emph{lot} of time dealing with e-mail, both
professionally and privately. Having an efficient e-mail client is essential.
Since none of the existing ones worked the way I wanted, I created my
own. @command{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 already had written an e-mail
search engine (@t{mu}), it seemed only logical to use that as a basis.
@node Other mail clients
@section Other mail clients
Under the hood, @t{mu4e} is fully search-based, similar to programs like
@t{notmuch}@footnote{@url{http://notmuchmail.org}},
@t{md}@footnote{@url{https://github.com/nicferrier/md}} and
@t{sup}@footnote{@url{http://sup.rubyforge.org/}}. However, @t{mu4e}'s
user-interface is quite different. @t{mu4e}'s mail handling (deleting, moving
etc.) is inspired by
@emph{Wanderlust}@footnote{@url{http://www.gohome.org/wl/}} (another
@code{emacs}-based e-mail client),
@t{mutt}@footnote{@url{http://www.mutt.org/}} and @t{dired}.
@t{mu4e} tries to keep all the 'state' in your maildirs, so you can easily
switch between clients, synchronize over @abbr{IMAP}, backup with @t{rsync}
and so on. If you delete the database, you won't lose any information.
@node What mu4e does not do
@section What @t{mu4e} does not do
There are a number of things that @t{mu4e} does @emph{not} do:
@itemize
@item @t{mu}/@t{mu4e} do @emph{not} deal with getting your e-mail messages from
a mail server. That task is delegated to other tools, such as
@t{offlineimap}@footnote{@url{http://offlineimap.org/}},
@t{isync}@footnote{@url{http://isync.sourceforge.net/}} or
@t{fetchmail}@footnote{@url{http://www.fetchmail.info/}}. As long as the
messages end up in a maildir, @t{mu4e} and @t{mu} are happy to deal with them.
@item @t{mu4e} also does @emph{not} implement sending of messages; instead, it
depends on @t{smptmail} (@inforef{Top,,smtpmail}), which is part of
@command{emacs}. In addition, @t{mu4e} piggybacks on Gnus' message editor;
@inforef{Top,,message}.
@end itemize
Thus, many of the things an e-mail client traditionally needs to do, are
delegated to other tools. This leaves @t{mu4e} to concentrate on what it does
best: quickly finding the mails you are looking for, and handle them as
efficiently as possible.
@node Becoming a mu4e user
@section Becoming a @t{mu4e} user
If @t{mu4e} looks like something for you, give it a shot! We've been 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 @t{mu4e}, a lot of knowledge about
programming or elisp shouldn't be required.
When you take @t{mu4e} into use, it's a good idea to subscribe to the
@t{mu}/@t{mu4e}-mailing
list@footnote{@url{http://groups.google.com/group/mu-discuss}}.
If you have suggestions for improvements or bug reports, please use the GitHub
issues list@footnote{@url{https://github.com/djcb/mu/issues}}. In bug reports,
please clearly specify the versions of @t{mu}/@t{mu4e} and @command{emacs} you
are using, as well as any other relevant details. If you are new to all this,
the somewhat paternalistic @emph{``How to ask questions the smart
way''}@footnote{@url{http://www.catb.org/esr/faqs/smart-questions.html}} can
be a good read.
@node Getting started
@chapter Getting started
In this chapter, we go through the installation of @t{mu4e} and its basic
setup. After we have succeeded in @ref{Getting mail}, and @pxref{Indexing your
messages}, we discuss @ref{Basic configuration}.
After these steps, @t{mu4e} should be ready to go!
@menu
* Requirements:: What is needed
* Installation:: How to install @t{mu} and @t{mu4e}
* Getting mail:: Getting mail from a server
* Indexing your messages:: Creating and maintaining the index
* Basic configuration:: Settings for @t{mu4e}
* Folders:: Setting up standard folders
* Retrieval and indexing:: Doing it from mu4e
* Sending mail:: How to send mail
* Running mu4e:: Overview of the @t{mu4e} views
@end menu
@node Requirements
@section Requirements
@t{mu}/@t{mu4e} are known to work on a wide variety of Unix- and Unix-like
systems, including many Linux distributions, MacOS and
FreeBSD. @command{emacs} 23 or 24 is required, as well as
Xapian@footnote{@url{http://xapian.org/}} and
GMime@footnote{@url{http://spruce.sourceforge.net/gmime/}}.
@t{mu} has optional support the Guile 2.x (Scheme) programming language. There
are also some GUI-tools, which require GTK+ and Webkit; either the GTK+2 or
GTK+3-versions.
If you intend to compile it yourself, you need to have the typical development
tools, such as C and C++ compilers (both @command{gcc} and @command{clang}
should work), GNU Autotools and @command{make}, and (if you use them) the
development packages for GTK+, Webkit and Guile.
@node Installation
@section Installation
@t{mu4e} is part of @t{mu} - by installing the latter, the former is installed
as well. Some Linux distributions provide packaged versions of
@t{mu}/@t{mu4e}; if you can use those, there is no need to compile anything
yourself. However, if there are no packages for your distribution, 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 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 @ref{Building from a release tarball} or
@ref{Building from git}.
@subsection Dependencies for Debian/Ubuntu
@example
$ sudo apt-get install libgmime-2.6-dev libxapian-dev
# if libgmime-2.6-dev is not available, try libgmime-2.4-dev
# get emacs 23 or 24 if you don't have it yet
# emacs 24 works better; it may be available as 'emacs-snapshot'
$ sudo apt-get install emacs23
# optional
$ sudo apt-get install guile-2.0-dev html2text xdg-utils
# optional: only needed for msg2pdf and mug (toy gtk+ frontend)
$ sudo apt-get install libwebkit-dev
@end example
@subsection Dependencies for Fedora
@example
$ sudo yum install gmime-devel xapian-core-devel
# get emacs 23 or 24 if you don't have it yet
$ sudo yum install emacs
# optional
$ sudo yum install html2text xdg-utils
# optional: only needed for msg2pdf and mug (toy gtk+ frontend)
$ sudo apt-get install webkitgtk-devel
# or:
$ sudo apt-get install webkitgtk3-devel
@end example
@subsection Building from a release tarball
@anchor{Building from a release tarball}
Using a release-tarball (as available from
GoogleCode@footnote{@url{http://code.google.com/p/mu0/downloads/list}},
installation follows the normal steps:
@example
$ tar xvfz mu-<version>.tar.gz # use the specific version
$ cd mu-<version>
# On the BSDs: use gmake instead of make
$ ./configure && make
$ sudo make install
@end example
Xapian, GMime and their dependencies must be installed.
@subsection Building from git
@anchor{Building from git}
Alternatively, if you build from the git repository or use a tarball like the
ones that @t{github} produces, the instructions are slightly different, and
require you to have @t{autotools} installed:
@example
# get from git (alternatively, use a github tarball)
$ git clone git://github.com/djcb/mu.git
$ cd mu
$ autoreconf -i && ./configure && make
# On the BSDs: use gmake instead of make
$ sudo make install
@end example
(Xapian, GMime and their dependencies must be installed).
After this, @t{mu} and @t{mu4e} should be installed @footnote{there's a hard
dependency between versions of @t{mu4e} and @t{mu} - you cannot combine
different versions} on your system, and be available from the command line
in @command{emacs}.
You may need to restart @command{emacs}, so it can find @t{mu4e} in its
@code{load-path}. If, even after restarting, @command{emacs} cannot find
@t{mu4e}, you may need to add to your @code{load-path} explicitly; check where
@t{mu4e} is installed, and add something like the following to your
configuration before trying again:
@lisp
;; the exact path may differ -- check it
(add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e")
@end lisp
@subsection mu4e and emacs customization
There is some support for using the @command{emacs} customization system in
@t{mu4e}, but for now, we recommend setting the values manually. Please refer
to @ref{Example configurations} for a couple of examples of this; here we go
through things step-by-step.
@node Getting mail
@section Getting mail
In order for @t{mu} (and, by extension, @t{mu4e}) to work, you need to have
your e-mail messages stored in a
@emph{maildir}@footnote{@url{http://en.wikipedia.org/wiki/Maildir}; in this
manual we use the term 'maildir' for both the standard and the hierarchy of
maildirs that store your messages} - 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:
@itemize
@item @emph{Using an external IMAP or POP server} - if you are using an
@abbr{IMAP} or @abbr{POP} server, you can use tools like @t{getmail},
@t{fetchmail}, @t{offlineimap} or @t{isync} to download your messages into a
maildir (@file{~/Maildir}, often). Because it is such a common case, there is
a full example of setting @t{mu4e} up with @t{offlineimap} and Gmail;
@pxref{Gmail configuration}.
@item @emph{Using a local mail server} - if you are using a local mail-server
(such as @t{postfix} or @t{qmail}), you can teach them to deliver into a
maildir as well, maybe in combination with @t{procmail}. A bit of googling
should be able to provide you with the details.
@end itemize
@node Indexing your messages
@section Indexing your messages
After you have succeeded in @ref{Getting mail}, we need to @emph{index} the
messages. That is - we need to scan the message in the maildir and store the
information about the mails into a special database. We can do that from
@t{mu4e} -- @ref{Main view}, but the first time, it is a good idea to run
it from the command line, to make sure everything works correctly.
Assuming that your maildir is at @file{~/Maildir}, we give the following
command:
@example
$ mu index --maildir=~/Maildir
@end example
This should scan your @file{~/Maildir}@footnote{In most cases, you do not even
need to provide the @t{--maildir=~/Maildir} since it is the default; see the
@t{mu-index} man-page for details} and fill the database, and give progress
information while doing so.
The indexing process may take a few minutes the first time you do it (for
thousands of e-mails); afterwards it is much faster, since @t{mu} only scans
messages that are new or have changed. Indexing is discussed in full detail in
the @t{mu-index} man page.
After the indexing process has finished, you can quickly test if everything
worked, by trying some command-line searches, for example
@example
$ mu find hello
@end example
which should list all messages that match @t{hello}. For more examples of
searches, see @ref{Queries}, or check the @t{mu-find} and @t{mu-easy} man
pages. If all of this worked well, we are well on our way setting up @t{mu};
the next step is to do some basic configuration for @t{mu4e}.
@node Basic configuration
@section Basic configuration
Before we can start using @t{mu4e}, we need to tell @command{emacs} to load
it. So, add to your @file{~/.emacs} (or its moral equivalent, such as
@file{~/.emacs.d/init.el}) something like:
@lisp
(require 'mu4e)
@end lisp
If @command{emacs} complains that it cannot find @t{mu4e}, check your
@code{load-path} and make sure that @t{mu4e}'s installation directory is part
of it. If not, you can add it:
@lisp
(add-to-list 'load-path MU4E-PATH)
@end lisp
with @t{MU4E-PATH} replaced with the actual path.
@node Folders
@section Folders
The next step is to tell @t{mu4e} where it can find your Maildir, and some
special folders. So, for example@footnote{Note that the folders
(@t{mu4e-sent-folder}, @t{mu4e-drafts-folder}, @t{mu4e-trash-folder} and
@t{mu4e-refile-folder}) can also be @emph{functions} that are evaluated at
runtime. This allows for dynamically changing them depending on context. See
@ref{Dynamic folders} for details.}:
@lisp
;; these are actually the defaults
(setq
mu4e-maildir "~/Maildir" ;; top-level Maildir
mu4e-sent-folder "/sent" ;; folder for sent messages
mu4e-drafts-folder "/drafts" ;; unfinished messages
mu4e-trash-folder "/trash" ;; trashed messages
mu4e-refile-folder "/archive") ;; saved messages
@end lisp
@code{mu4e-maildir} takes an actual filesystem-path, the other folder names
are all relative to @code{mu4e-maildir}.
@node Retrieval and indexing
@section Retrieval and indexing
As we have seen, we can do all of the mail retrieval @emph{outside} of
@command{emacs}/@t{mu4e}. However, you can also do it from within
@t{mu4e}. For that, set the variable @code{mu4e-get-mail-command} to the
program or shell command you want to use for retrieving mail. You can then
retrieve your e-mail using @kbd{M-x mu4e-update-mail-and-index}, or
@kbd{C-S-u} in all @t{mu4e}-views.
If you don't have a specific command for getting mail, for example because you
are running your own mail-server, you can set @code{mu4e-get-mail-command} to
@t{"true"}, in which case @t{mu4e} won't try to get new mail, but still
re-index your messages.
You can also update your mail and index periodically in the background, by
setting the variable @code{mu4e-update-interval} to the number of seconds
between these updates. If set to @code{nil}, it won't update at all. After you
make changes to @code{mu4e-update-interval}, @t{mu4e} must be restarted before
the changes take effect.
A simple setup could look something like:
@lisp
(setq
mu4e-get-mail-command "offlineimap" ;; or fetchmail, or ...
mu4e-update-interval 300) ;; update every 5 minutes
@end lisp
It is possible to get notifications when the indexing process does any updates
- for example when receiving new mail. See @code{mu4e-index-updated-hook} and
some tips on its usage in the @ref{FAQ}.
@node Sending mail
@section Sending mail
@t{mu4e} re-uses Gnu's @code{message-mode} (@inforef{Top,,message}) for
writing mail and inherits the setup for sending mail as well.
For sending mail using @abbr{SMTP}, @t{mu4e} uses @t{smtpmail}
(@inforef{Top,,smtpmail}). 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 @ref{Example
configurations}.
A very minimal setup:
@lisp
;; tell message-mode how to send mail
(setq message-send-mail-function 'smtpmail-send-it)
;; if our mail server lives at smtp.example.org; if you have a local
;; mail-server, simply use 'localhost' here.
(setq smtpmail-smtp-server "smtp.example.org")
@end lisp
Since @t{mu4e} (re)uses the same @t{message mode} and @t{smtpmail} that Gnus
uses, many settings for those also apply to @t{mu4e}.
@subsection Dealing with sent messages
By default, @t{mu4e} puts a copy of messages you sent in the folder determined
by @code{mu4e-sent-folder}. In some cases, this may not be what you want -
for example, when using Gmail-over-@abbr{IMAP}, this interferes with Gmail's
handling of the sent messages folder, and you may end up with duplicate
messages.
You can use the the variable @code{mu4e-sent-messages-behavior} to customize
what happens with sent messages. The default is the symbol @code{sent} which,
as mentioned, causes the message to be copied to your sent-messages
folder. Other possible values are the symbols @code{trash} (the sent message
is moved to the trash-folder (@code{mu4e-trash-folder}), and @code{delete} to
simply discard the sent message altogether (so GMail can deal with it).
For Gmail-over-@abbr{IMAP}, you could add the following to your settings:
@verbatim
;; don't save messages to Sent Messages, Gmail/IMAP takes care of this
(setq mu4e-sent-messages-behavior 'delete)
@end verbatim
And that's it! We should now be ready to go.
@node Running mu4e
@section Running mu4e
After following the steps in this chapter, we hopely now have a working
@t{mu4e} setup. Great! In the next chapters, we walk you through the various
views in @t{mu4e}.
For your orientation, the diagram below shows how the views relate to each
other, and the default key-bindings to navigate between them.
@cartouche
@verbatim
[C] +--------+ [RFCE]
--------> | editor | <--------
/ +--------+ \
/ [RFCE]^ \
/ | \
+-------+ [sjbB]+---------+ [RET] +---------+
| main | <---> | headers | <----> | message |
+-------+ [q] +---------+ [qbBjs]+---------+
[sjbB] ^
[.] | [q]
V
+-----+
| raw |
+-----+
Default bindings
----------------
R: Reply s: search .: raw view (toggle)
F: Forward j: jump-to-maildir q: quit
C: Compose b: bookmark-search
E: Edit B: edit bookmark-search
@end verbatim
@end cartouche
@node Main view
@chapter The main view
After you have installed @t{mu4e} (@pxref{Getting started}), you can start it
with @kbd{M-x mu4e}. @t{mu4e} does some checks to ensure everything is set up
correctly, and then shows you the @t{mu4e} main view. Its major mode is
@code{mu4e-main-mode}.
@menu
* MV Overview::
* Basic actions::
* MV Bookmarks::
* Miscellaneous::
@end menu
@node MV Overview
@section Overview
The main view looks something like the following:
@cartouche
@verbatim
* mu4e - mu for emacs version x.x CG
Basics
* [j]ump to some maildir
* enter a [s]earch query
* [C]ompose a new message
Bookmarks
* [bu] Unread messages
* [bt] Today's messages
* [bw] Last 7 days
* [bp] Messages with images
Misc
* [U]pdate email & database
* toggle [m]ail sending mode (direct)
* [f]lush queued mail
* [A]bout mu4e
* [H]elp
* [q]uit mu4e
@end verbatim
@end cartouche
In the example above, you can see the letters ``@t{CG}'', which indicate:
@itemize
@item @t{C}: support for decryption of encrypted messages, and verifying
signatures. See @ref{MSGV Crypto} in the @ref{Message view} for details.
@item @t{G}: support for the Guile 2.0 programming language
@end itemize
Whether you see both, one or none of these letters depends on the way @t{mu}
is built.
Let's walk through the menu.
@node Basic actions
@section Basic actions
First, the @emph{Basics}:
@itemize
@item @t{[j]ump to some maildir}: after pressing @key{j} (``jump''),
@t{mu4e} asks you for a maildir to visit. These are the maildirs you set in
@ref{Basic configuration} and any of your own. If you choose @key{o}
(``other'') or @key{/}, you can choose from all maildirs under
@code{mu4e-maildir}. After choosing a maildir, the messages in that maildir
are listed, in the @ref{Headers view}.
@item @t{enter a [s]earch query}: after pressing @key{s}, @t{mu4e} asks
you for a search query, and after entering one, shows the results in the
@ref{Headers view}.
@item @t{[C]ompose a new message}: after pressing @key{C}, you are dropped in
the @ref{Editor view} to write a new message.
@end itemize
@node MV Bookmarks
@section Bookmarks
The next item in the Main view is @emph{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 @key{b} followed by the bookmark's shortcut. If you'd
like to edit the bookmarked query first before invoking it, use @key{B}.
Bookmarks are stored in the variable @code{mu4e-bookmarks}; you can add your
own and/or replace the default ones; @xref{Bookmarks}.
@node Miscellaneous
@section Miscellaneous
Finally, there are some @emph{Misc} (miscellaneous) actions:
@itemize
@item @t{[U]pdate email & database} executes the shell-command in the variable
@code{mu4e-get-mail-command}, and afterwards updates the @t{mu} database;
see @ref{Indexing your messages} and @ref{Getting mail} for details.
@item @t{toggle [m]ail sending mode (direct)} toggles between sending
mail directly, and queuing it first (for example, when you are offline), and
@t{[f]lush queued mail} flushes any queued mail. This item is visible only
if you have actually set up mail-queuing. @ref{Queuing mail}
@item @t{[A]bout mu4e} provides general information about the program
@item @t{[H]elp} shows help information for this view
@item Finally, @t{[q]uit mu4e} quits your @t{mu4e}-session
@end itemize
@node Headers view
@chapter The headers view
The headers view shows the results of a query. The topline 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 the headers view is
@code{mu4e-headers-mode}.
@menu
* HV Overview::
* Keybindings::
* Marking messages::
* Sort order and threading::
* HV Actions::
* Split view::
@end menu
@node HV Overview
@section Overview
An example headers view:
@cartouche
@verbatim
Date V Flgs From/To List Subject
06:32 Nu To Edmund Dantès GstDev + Re: Gstreamer-V4L...
15:08 Nu Abbé Busoni GstDev + Re: Gstreamer-V...
18:20 Nu Pierre Morrel GstDev \ Re: Gstreamer...
2013-03-18 S Jacopo EmacsUsr + emacs server on win...
2013-03-18 S Mercédès EmacsUsr \ RE: emacs server ...
2013-03-18 S Beachamp EmacsUsr + Re: Copying a whole...
22:07 Nu Albert de Moncerf EmacsUsr \ Re: Copying a who...
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
@end verbatim
@end cartouche
Some notes to explain what you see in the example:
@itemize
@item The fields shown in the headers view can be influenced by customizing
the variable @code{mu4e-headers-fields}; see @code{mu4e-header-info} for the
list of available fields.
@item By default, the date is shown with the @t{:human-date} field, which
shows the @emph{time} for today's messages, and the @emph{date} for older
messages. If you want to distinguish between 'today' and 'older', you can use
the @t{:date} field instead.
@item You can customize the date and time formats with the variable
@code{mu4e-headers-date-format} and @code{mu4e-headers-time-format},
respectively. In the example, we use @code{:human-date}, which shows when the
time when the message was sent today, and the date otherwise.
@item The header field used for sorting is indicated by ``@t{V}'' or
``@t{^}''@footnote{or you can use little graphical triangles; see variable
@code{mu4e-use-fancy-chars}}, indicating the sort order (descending or
ascending, respectively). You can influence this by a mouse click, or
@key{O}. Not all fields allow sorting.
@item Instead of showing the @t{From:} and @t{To:} fields separately, you
can use From/To (@t{:from-or-to} in @code{mu4e-headers-fields} as a more
compact way to convey the most important information: it shows @t{From:}
@emph{except} when the e-mail was sent by the user (i.e., you) - in that case
it shows @t{To:} (prefixed by @t{To}@footnote{You can customize this by
changing the variable @code{mu4e-headers-from-or-to-prefix} (a cons cell)}, as
in the example above). To determine whether a message was sent by you,
@t{mu4e} uses the variable @code{mu4e-user-mail-address-list}, a list of
your e-mail addresses.
@item The 'List' field shows the mailing-list a message is sent to;
@code{mu4e} tries to create a convenient shortcut for the mailing-list name;
the variable @code{mu4e-user-mailing-lists} can be used to add your own
shortcuts.
@item The letters in the 'Flags' field correspond to the following: D=@emph{draft},
F=@emph{flagged} (i.e., 'starred'), N=@emph{new}, P=@emph{passed} (i.e.,
forwarded), R=@emph{replied}, S=@emph{seen}, T=@emph{trashed},
a=@emph{has-attachment}, x=@emph{encrypted}, s=@emph{signed},
u=@emph{unread}. The tooltip for this field also contains this information.
@item The subject field also indicates the discussion threads @footnote{using
Jamie Zawinski's mail threading algorithm,
@url{http://www.jwz.org/doc/threading.html}}.
@item The headers view is @emph{automatically updated} if any changes are
found during the indexing process, and if there is not current
user-interaction. If you do not want such automatic updates, set
@code{mu4e-headers-auto-update} to @code{nil}.
@end itemize
@node Keybindings
@section Keybindings
Using the below key bindings, you can do various things with these messages;
these actions are also listed in the @t{Headers} menu in the @command{emacs}
menu bar.
@verbatim
key description
===========================================================
n,p go to next, previous message
y select the message view (if it's visible)
RET open the message at point in the message view
searching
---------
s search
S edit last query
/ narrow the search
b search bookmark
B edit bookmark before search
j jump to maildir
M-left previous query
M-right next query
O change sort order
P toggle threading
Q toggle full-search
V toggle skip-duplicates
W toggle include-related
marking
-------
d mark for moving to the trash folder
DEL,D mark for complete deletion
m mark for moving to another maildir folder
r mark for refiling
+,- mark for flagging/unflagging
?,! mark message as unread, read
u unmark message at point
U unmark *all* messages
% mark based on a regular expression
T,t mark whole thread, subthread
<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
----
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,z leave the headers buffer
@end verbatim
@node Marking messages
@section Marking messages
When processing messages, the first step is to @emph{mark} them for a certain
action, such as deletion or move. Then, after one or more messages are marked,
you execute (@code{mu4e-mark-execute-all}, @key{x}) these actions. This
two-step mark-execute sequence is similar to what e.g. @t{dired} does. This is
how @t{mu4e} tries to be as quick as possible, while avoiding accidents.
The mark/unmark commands support the @emph{region} (i.e., ``selection'') --
so, for example, if you select some messages and press @key{DEL}, all messages
in the region are marked for deletion.
You can mark all messages that match a certain pattern with @key{%}. In
addition, you can mark all messages in the current thread (@key{T}) or
sub-thread (@key{t}).
When you 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
@emph{apply} them before leaving, or @emph{ignore} them. This behavior can be
influenced with the variable @code{mu4e-headers-leave-behavior}.
For more information about marking, see @ref{Marking}.
@node Sort order and threading
@section Sort order and threading
By default, @t{mu4e} sorts messages by date, in descending order: the most
recent messages are shown at the top. In addition, the messages are
@emph{threaded}, i.e., shown in the context of a discussion thread; this also
affects the sort order.
The header field used for sorting is indicated by ``@t{V}'' or
``@t{^}''@footnote{or you can use little graphical triangles; see variable
@code{mu4e-use-fancy-chars}}, indicating the sort order (descending or
ascending, respectively).
You can change the sort order by clicking the corresponding field with the
mouse, or with @kbd{M-x mu4e-headers-change-sorting} (@key{O}); note that not
all fields can be used for sorting. You can toggle threading on/off using
@kbd{M-x mu4e-headers-toggle-threading} or @key{P}. For both of these functions,
unless you provide a prefix argument (@key{C-u}), the current search is
updated immediately using the new parameters. You can toggle full-search
(@ref{Searching}) using @kbd{M-x mu4e-headers-toggle-full-search} or @key{Q}.
If you want to change the defaults for these settings, you can use the
variables @code{mu4e-headers-sortfield} and @code{mu4e-headers-show-threads}.
@node HV Actions
@section Actions
@code{mu4e-headers-action} (@key{a}) lets you pick custom actions to perform
on the message at point. You can specify these actions using the variable
@code{mu4e-headers-actions}. See @ref{Actions} for the details.
@t{mu4e} defines some default actions. One of those is for @emph{capturing} a
message: @key{a c} 'captures' the current message. Next, when you're editing
some message, you can include the previously captured message as an
attachment, using @code{mu4e-compose-attach-captured-message}. See
@file{mu4e-actions.el} in the @t{mu4e} source distribution for more example
actions.
@node Split view
@section Split view
Using the @emph{Split view}, we can see the @ref{Headers view} and the
@ref{Message view} next to each other, with the message selected in the
former, visible in the latter. You can influence the way the splitting is done
by customizing the variable @code{mu4e-split-view}. Possible values are:
@itemize
@item @t{horizontal} (this is the default): display the message view below the
header view. Use @code{mu4e-headers-visible-lines} the set the number of lines
shown (default: 8).
@item @t{vertical}: display the message view on the
right side of the header view. Use @code{mu4e-headers-visible-columns} to set
the number of visible columns (default: 30).
@item anything else: don't do any splitting
@end itemize
@noindent
Some useful key bindings in the split view:
@itemize
@item @key{C-+} and @key{C--}: interactively change the number of columns or
headers shown
@item You can change the selected window from the
headers-view to the message-view and vice-versa with
@code{mu4e-select-other-view}, bound to @key{y}
@end itemize
@node Message view
@chapter The message view
After selecting a message in the @ref{Headers view}, it appears in a message
view window: the message headers, followed by the message body. Its major
mode is @code{mu4e-view-mode}.
@menu
* MSGV Overview::
* MSGV Keybindings::
* Opening and saving attachments::
* Viewing images inline::
* Displaying rich-text messages::
* MSGV Crypto::
* MSGV Actions::
@end menu
@node MSGV Overview
@section Overview
An example message view:
@cartouche
@verbatim
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:
[....]
@end verbatim
@end cartouche
Some notes:
@itemize
@item The variable @code{mu4e-view-fields} determines the header fields to be shown.
@item You can set the date format with the variable
@code{mu4e-date-format-long}.
@item By default, only the names of contacts in address fields are visible
(see @code{mu4e-view-show-addresses} to change this). You can view the e-mail
addresses by clicking on the name, or pressing @key{M-RET}.
@item You can compose a message for the contact at point by either clicking
@key{[mouse-2]} or pressing @key{C}.
@item The body text can be line-wrapped using @t{longlines-mode}. @t{mu4e}
defines @key{w} to toggle between the wrapped and unwrapped state. If you want
to do this automatically when viewing a message, invoke @code{longlines-mode}
in your @code{mu4e-view-mode-hook}.
@item You can hide cited parts in messages (the parts starting with ``@t{>}'')
using @code{mu4e-view-hide-cited}, bound to @key{h}. If you want to do this
automatically for every message, invoke the function in your
@code{mu4e-view-mode-hook}.
@item For search-related operations, see @ref{Searching}.
@item You can scroll down the message using @key{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 @code{mu4e-view-scroll-to-next} to @code{nil}.
@end itemize
@node MSGV Keybindings
@section Keybindings
You can find most things you can do with this message in the @emph{View} menu,
or by using the keyboard; the default bindings are:
@verbatim
key description
==============================================================
n,p go to next, previous message
y select the headers view (if it's visible)
RET scroll down
M-RET open URL at point / attachment at point
SPC scroll down, if at end, move to next message