mu-0.9.9.5/0000775000175000017500000000000012125532705007322 500000000000000mu-0.9.9.5/Makefile.am0000644000175000017500000000457512125531126011303 00000000000000## Copyright (C) 2008-2013 Dirk-Jan C. Binnema ## ## This program is free software; you can redistribute it and/or modify ## it under the terms of the GNU General Public License as published by ## the Free Software Foundation; either version 3 of the License, or ## (at your option) any later version. ## ## This program is distributed in the hope that it will be useful, ## but WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ## GNU General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with this program; if not, write to the Free Software Foundation, ## Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. include $(top_srcdir)/gtest.mk if BUILD_GUILE guile=guile else guile= endif if BUILD_MU4E mu4e=mu4e else mu4e= endif SUBDIRS=m4 man lib $(guile) mu $(mu4e) contrib toys ACLOCAL_AMFLAGS=-I m4 # so we can say 'make test' check: test cleanupnote cleanupnote: @echo -e "\nNote: you can remove the mu-test- dir in your tempdir" @echo "after 'make check' has finished." tags: gtags # this warns about function that have a cyclomatic complexity of > 10, # which is a sign that it needs some refactoring. requires the pmccabe # tool. If all is fine, it outputs nothing cc10: @$(PMCCABE) `find . -name '*.c' -o -name '*.cc'` \ | grep -v mu-str-normalize.c \ | grep -v mu_str_subject_normalize \ | grep -v tests \ | sort -nr | awk '($$1 > 10)' # this warns about functions that are over 35 non-comment lines long, which is a # sign that they need some refactoring. requires the pmccabe tool. if # all is fine, it outputs nothing # note, some functions are exempted from this rule. line35: @$(PMCCABE) -c `find . -name '*.c' -o -name '*.cc'` \ | grep -v mu-str-normalize.c \ | grep -v mu_str_subject_normalize \ | grep -v config_options_group_find \ | grep -v SCM_DEFINE \ | grep -v tests \ | awk '($$5 > 35)' # get all todo/fixme messages fixme: @grep -i 'FIXME\|TODO' `find src -type f` # check whether we can run make distcheck from the repo version gitcheck: cd `mktemp -d`; \ git clone git://github.com/djcb/mu.git ; \ cd mu; \ autoreconf -i ; \ ./configure ; \ make distcheck EXTRA_DIST= \ TODO \ HACKING \ gtest.mk \ NEWS \ autogen.sh mu-0.9.9.5/depcomp0000755000175000017500000004755611723765300010640 00000000000000#! /bin/sh # depcomp - compile a program generating dependencies as side-effects scriptversion=2011-12-04.11; # UTC # Copyright (C) 1999, 2000, 2003, 2004, 2005, 2006, 2007, 2009, 2010, # 2011 Free Software Foundation, Inc. # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2, or (at your option) # any later version. # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # You should have received a copy of the GNU General Public License # along with this program. If not, see . # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a # configuration script generated by Autoconf, you may include it under # the same distribution terms that you use for the rest of that program. # Originally written by Alexandre Oliva . case $1 in '') echo "$0: No command. Try \`$0 --help' for more information." 1>&2 exit 1; ;; -h | --h*) cat <<\EOF Usage: depcomp [--help] [--version] PROGRAM [ARGS] Run PROGRAMS ARGS to compile a file, generating dependencies as side-effects. Environment variables: depmode Dependency tracking mode. source Source file read by `PROGRAMS ARGS'. object Object file output by `PROGRAMS ARGS'. DEPDIR directory where to store dependencies. depfile Dependency file to output. tmpdepfile Temporary file to use when outputting dependencies. libtool Whether libtool is used (yes/no). Report bugs to . EOF exit $? ;; -v | --v*) echo "depcomp $scriptversion" exit $? ;; esac if test -z "$depmode" || test -z "$source" || test -z "$object"; then echo "depcomp: Variables source, object and depmode must be set" 1>&2 exit 1 fi # Dependencies for sub/bar.o or sub/bar.obj go into sub/.deps/bar.Po. depfile=${depfile-`echo "$object" | sed 's|[^\\/]*$|'${DEPDIR-.deps}'/&|;s|\.\([^.]*\)$|.P\1|;s|Pobj$|Po|'`} tmpdepfile=${tmpdepfile-`echo "$depfile" | sed 's/\.\([^.]*\)$/.T\1/'`} rm -f "$tmpdepfile" # Some modes work just like other modes, but use different flags. We # parameterize here, but still list the modes in the big case below, # to make depend.m4 easier to write. Note that we *cannot* use a case # here, because this file can only contain one case statement. if test "$depmode" = hp; then # HP compiler uses -M and no extra arg. gccflag=-M depmode=gcc fi if test "$depmode" = dashXmstdout; then # This is just like dashmstdout with a different argument. dashmflag=-xM depmode=dashmstdout fi cygpath_u="cygpath -u -f -" if test "$depmode" = msvcmsys; then # This is just like msvisualcpp but w/o cygpath translation. # Just convert the backslash-escaped backslashes to single forward # slashes to satisfy depend.m4 cygpath_u='sed s,\\\\,/,g' depmode=msvisualcpp fi if test "$depmode" = msvc7msys; then # This is just like msvc7 but w/o cygpath translation. # Just convert the backslash-escaped backslashes to single forward # slashes to satisfy depend.m4 cygpath_u='sed s,\\\\,/,g' depmode=msvc7 fi case "$depmode" in gcc3) ## gcc 3 implements dependency tracking that does exactly what ## we want. Yay! Note: for some reason libtool 1.4 doesn't like ## it if -MD -MP comes after the -MF stuff. Hmm. ## Unfortunately, FreeBSD c89 acceptance of flags depends upon ## the command line argument order; so add the flags where they ## appear in depend2.am. Note that the slowdown incurred here ## affects only configure: in makefiles, %FASTDEP% shortcuts this. for arg do case $arg in -c) set fnord "$@" -MT "$object" -MD -MP -MF "$tmpdepfile" "$arg" ;; *) set fnord "$@" "$arg" ;; esac shift # fnord shift # $arg done "$@" stat=$? if test $stat -eq 0; then : else rm -f "$tmpdepfile" exit $stat fi mv "$tmpdepfile" "$depfile" ;; gcc) ## There are various ways to get dependency output from gcc. Here's ## why we pick this rather obscure method: ## - Don't want to use -MD because we'd like the dependencies to end ## up in a subdir. Having to rename by hand is ugly. ## (We might end up doing this anyway to support other compilers.) ## - The DEPENDENCIES_OUTPUT environment variable makes gcc act like ## -MM, not -M (despite what the docs say). ## - Using -M directly means running the compiler twice (even worse ## than renaming). if test -z "$gccflag"; then gccflag=-MD, fi "$@" -Wp,"$gccflag$tmpdepfile" stat=$? if test $stat -eq 0; then : else rm -f "$tmpdepfile" exit $stat fi rm -f "$depfile" echo "$object : \\" > "$depfile" alpha=ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz ## The second -e expression handles DOS-style file names with drive letters. sed -e 's/^[^:]*: / /' \ -e 's/^['$alpha']:\/[^:]*: / /' < "$tmpdepfile" >> "$depfile" ## This next piece of magic avoids the `deleted header file' problem. ## The problem is that when a header file which appears in a .P file ## is deleted, the dependency causes make to die (because there is ## typically no way to rebuild the header). We avoid this by adding ## dummy dependencies for each header file. Too bad gcc doesn't do ## this for us directly. tr ' ' ' ' < "$tmpdepfile" | ## Some versions of gcc put a space before the `:'. On the theory ## that the space means something, we add a space to the output as ## well. hp depmode also adds that space, but also prefixes the VPATH ## to the object. Take care to not repeat it in the output. ## Some versions of the HPUX 10.20 sed can't process this invocation ## correctly. Breaking it into two sed invocations is a workaround. sed -e 's/^\\$//' -e '/^$/d' -e "s|.*$object$||" -e '/:$/d' \ | sed -e 's/$/ :/' >> "$depfile" rm -f "$tmpdepfile" ;; hp) # This case exists only to let depend.m4 do its work. It works by # looking at the text of this script. This case will never be run, # since it is checked for above. exit 1 ;; sgi) if test "$libtool" = yes; then "$@" "-Wp,-MDupdate,$tmpdepfile" else "$@" -MDupdate "$tmpdepfile" fi stat=$? if test $stat -eq 0; then : else rm -f "$tmpdepfile" exit $stat fi rm -f "$depfile" if test -f "$tmpdepfile"; then # yes, the sourcefile depend on other files echo "$object : \\" > "$depfile" # Clip off the initial element (the dependent). Don't try to be # clever and replace this with sed code, as IRIX sed won't handle # lines with more than a fixed number of characters (4096 in # IRIX 6.2 sed, 8192 in IRIX 6.5). We also remove comment lines; # the IRIX cc adds comments like `#:fec' to the end of the # dependency line. tr ' ' ' ' < "$tmpdepfile" \ | sed -e 's/^.*\.o://' -e 's/#.*$//' -e '/^$/ d' | \ tr ' ' ' ' >> "$depfile" echo >> "$depfile" # The second pass generates a dummy entry for each header file. tr ' ' ' ' < "$tmpdepfile" \ | sed -e 's/^.*\.o://' -e 's/#.*$//' -e '/^$/ d' -e 's/$/:/' \ >> "$depfile" else # The sourcefile does not contain any dependencies, so just # store a dummy comment line, to avoid errors with the Makefile # "include basename.Plo" scheme. echo "#dummy" > "$depfile" fi rm -f "$tmpdepfile" ;; aix) # The C for AIX Compiler uses -M and outputs the dependencies # in a .u file. In older versions, this file always lives in the # current directory. Also, the AIX compiler puts `$object:' at the # start of each line; $object doesn't have directory information. # Version 6 uses the directory in both cases. dir=`echo "$object" | sed -e 's|/[^/]*$|/|'` test "x$dir" = "x$object" && dir= base=`echo "$object" | sed -e 's|^.*/||' -e 's/\.o$//' -e 's/\.lo$//'` if test "$libtool" = yes; then tmpdepfile1=$dir$base.u tmpdepfile2=$base.u tmpdepfile3=$dir.libs/$base.u "$@" -Wc,-M else tmpdepfile1=$dir$base.u tmpdepfile2=$dir$base.u tmpdepfile3=$dir$base.u "$@" -M fi stat=$? if test $stat -eq 0; then : else rm -f "$tmpdepfile1" "$tmpdepfile2" "$tmpdepfile3" exit $stat fi for tmpdepfile in "$tmpdepfile1" "$tmpdepfile2" "$tmpdepfile3" do test -f "$tmpdepfile" && break done if test -f "$tmpdepfile"; then # Each line is of the form `foo.o: dependent.h'. # Do two passes, one to just change these to # `$object: dependent.h' and one to simply `dependent.h:'. sed -e "s,^.*\.[a-z]*:,$object:," < "$tmpdepfile" > "$depfile" # That's a tab and a space in the []. sed -e 's,^.*\.[a-z]*:[ ]*,,' -e 's,$,:,' < "$tmpdepfile" >> "$depfile" else # The sourcefile does not contain any dependencies, so just # store a dummy comment line, to avoid errors with the Makefile # "include basename.Plo" scheme. echo "#dummy" > "$depfile" fi rm -f "$tmpdepfile" ;; icc) # Intel's C compiler understands `-MD -MF file'. However on # icc -MD -MF foo.d -c -o sub/foo.o sub/foo.c # ICC 7.0 will fill foo.d with something like # foo.o: sub/foo.c # foo.o: sub/foo.h # which is wrong. We want: # sub/foo.o: sub/foo.c # sub/foo.o: sub/foo.h # sub/foo.c: # sub/foo.h: # ICC 7.1 will output # foo.o: sub/foo.c sub/foo.h # and will wrap long lines using \ : # foo.o: sub/foo.c ... \ # sub/foo.h ... \ # ... "$@" -MD -MF "$tmpdepfile" stat=$? if test $stat -eq 0; then : else rm -f "$tmpdepfile" exit $stat fi rm -f "$depfile" # Each line is of the form `foo.o: dependent.h', # or `foo.o: dep1.h dep2.h \', or ` dep3.h dep4.h \'. # Do two passes, one to just change these to # `$object: dependent.h' and one to simply `dependent.h:'. sed "s,^[^:]*:,$object :," < "$tmpdepfile" > "$depfile" # Some versions of the HPUX 10.20 sed can't process this invocation # correctly. Breaking it into two sed invocations is a workaround. sed 's,^[^:]*: \(.*\)$,\1,;s/^\\$//;/^$/d;/:$/d' < "$tmpdepfile" | sed -e 's/$/ :/' >> "$depfile" rm -f "$tmpdepfile" ;; hp2) # The "hp" stanza above does not work with aCC (C++) and HP's ia64 # compilers, which have integrated preprocessors. The correct option # to use with these is +Maked; it writes dependencies to a file named # 'foo.d', which lands next to the object file, wherever that # happens to be. # Much of this is similar to the tru64 case; see comments there. dir=`echo "$object" | sed -e 's|/[^/]*$|/|'` test "x$dir" = "x$object" && dir= base=`echo "$object" | sed -e 's|^.*/||' -e 's/\.o$//' -e 's/\.lo$//'` if test "$libtool" = yes; then tmpdepfile1=$dir$base.d tmpdepfile2=$dir.libs/$base.d "$@" -Wc,+Maked else tmpdepfile1=$dir$base.d tmpdepfile2=$dir$base.d "$@" +Maked fi stat=$? if test $stat -eq 0; then : else rm -f "$tmpdepfile1" "$tmpdepfile2" exit $stat fi for tmpdepfile in "$tmpdepfile1" "$tmpdepfile2" do test -f "$tmpdepfile" && break done if test -f "$tmpdepfile"; then sed -e "s,^.*\.[a-z]*:,$object:," "$tmpdepfile" > "$depfile" # Add `dependent.h:' lines. sed -ne '2,${ s/^ *// s/ \\*$// s/$/:/ p }' "$tmpdepfile" >> "$depfile" else echo "#dummy" > "$depfile" fi rm -f "$tmpdepfile" "$tmpdepfile2" ;; tru64) # The Tru64 compiler uses -MD to generate dependencies as a side # effect. `cc -MD -o foo.o ...' puts the dependencies into `foo.o.d'. # At least on Alpha/Redhat 6.1, Compaq CCC V6.2-504 seems to put # dependencies in `foo.d' instead, so we check for that too. # Subdirectories are respected. dir=`echo "$object" | sed -e 's|/[^/]*$|/|'` test "x$dir" = "x$object" && dir= base=`echo "$object" | sed -e 's|^.*/||' -e 's/\.o$//' -e 's/\.lo$//'` if test "$libtool" = yes; then # With Tru64 cc, shared objects can also be used to make a # static library. This mechanism is used in libtool 1.4 series to # handle both shared and static libraries in a single compilation. # With libtool 1.4, dependencies were output in $dir.libs/$base.lo.d. # # With libtool 1.5 this exception was removed, and libtool now # generates 2 separate objects for the 2 libraries. These two # compilations output dependencies in $dir.libs/$base.o.d and # in $dir$base.o.d. We have to check for both files, because # one of the two compilations can be disabled. We should prefer # $dir$base.o.d over $dir.libs/$base.o.d because the latter is # automatically cleaned when .libs/ is deleted, while ignoring # the former would cause a distcleancheck panic. tmpdepfile1=$dir.libs/$base.lo.d # libtool 1.4 tmpdepfile2=$dir$base.o.d # libtool 1.5 tmpdepfile3=$dir.libs/$base.o.d # libtool 1.5 tmpdepfile4=$dir.libs/$base.d # Compaq CCC V6.2-504 "$@" -Wc,-MD else tmpdepfile1=$dir$base.o.d tmpdepfile2=$dir$base.d tmpdepfile3=$dir$base.d tmpdepfile4=$dir$base.d "$@" -MD fi stat=$? if test $stat -eq 0; then : else rm -f "$tmpdepfile1" "$tmpdepfile2" "$tmpdepfile3" "$tmpdepfile4" exit $stat fi for tmpdepfile in "$tmpdepfile1" "$tmpdepfile2" "$tmpdepfile3" "$tmpdepfile4" do test -f "$tmpdepfile" && break done if test -f "$tmpdepfile"; then sed -e "s,^.*\.[a-z]*:,$object:," < "$tmpdepfile" > "$depfile" # That's a tab and a space in the []. sed -e 's,^.*\.[a-z]*:[ ]*,,' -e 's,$,:,' < "$tmpdepfile" >> "$depfile" else echo "#dummy" > "$depfile" fi rm -f "$tmpdepfile" ;; msvc7) if test "$libtool" = yes; then showIncludes=-Wc,-showIncludes else showIncludes=-showIncludes fi "$@" $showIncludes > "$tmpdepfile" stat=$? grep -v '^Note: including file: ' "$tmpdepfile" if test "$stat" = 0; then : else rm -f "$tmpdepfile" exit $stat fi rm -f "$depfile" echo "$object : \\" > "$depfile" # The first sed program below extracts the file names and escapes # backslashes for cygpath. The second sed program outputs the file # name when reading, but also accumulates all include files in the # hold buffer in order to output them again at the end. This only # works with sed implementations that can handle large buffers. sed < "$tmpdepfile" -n ' /^Note: including file: *\(.*\)/ { s//\1/ s/\\/\\\\/g p }' | $cygpath_u | sort -u | sed -n ' s/ /\\ /g s/\(.*\)/ \1 \\/p s/.\(.*\) \\/\1:/ H $ { s/.*/ / G p }' >> "$depfile" rm -f "$tmpdepfile" ;; msvc7msys) # This case exists only to let depend.m4 do its work. It works by # looking at the text of this script. This case will never be run, # since it is checked for above. exit 1 ;; #nosideeffect) # This comment above is used by automake to tell side-effect # dependency tracking mechanisms from slower ones. dashmstdout) # Important note: in order to support this mode, a compiler *must* # always write the preprocessed file to stdout, regardless of -o. "$@" || exit $? # Remove the call to Libtool. if test "$libtool" = yes; then while test "X$1" != 'X--mode=compile'; do shift done shift fi # Remove `-o $object'. IFS=" " for arg do case $arg in -o) shift ;; $object) shift ;; *) set fnord "$@" "$arg" shift # fnord shift # $arg ;; esac done test -z "$dashmflag" && dashmflag=-M # Require at least two characters before searching for `:' # in the target name. This is to cope with DOS-style filenames: # a dependency such as `c:/foo/bar' could be seen as target `c' otherwise. "$@" $dashmflag | sed 's:^[ ]*[^: ][^:][^:]*\:[ ]*:'"$object"'\: :' > "$tmpdepfile" rm -f "$depfile" cat < "$tmpdepfile" > "$depfile" tr ' ' ' ' < "$tmpdepfile" | \ ## Some versions of the HPUX 10.20 sed can't process this invocation ## correctly. Breaking it into two sed invocations is a workaround. sed -e 's/^\\$//' -e '/^$/d' -e '/:$/d' | sed -e 's/$/ :/' >> "$depfile" rm -f "$tmpdepfile" ;; dashXmstdout) # This case only exists to satisfy depend.m4. It is never actually # run, as this mode is specially recognized in the preamble. exit 1 ;; makedepend) "$@" || exit $? # Remove any Libtool call if test "$libtool" = yes; then while test "X$1" != 'X--mode=compile'; do shift done shift fi # X makedepend shift cleared=no eat=no for arg do case $cleared in no) set ""; shift cleared=yes ;; esac if test $eat = yes; then eat=no continue fi case "$arg" in -D*|-I*) set fnord "$@" "$arg"; shift ;; # Strip any option that makedepend may not understand. Remove # the object too, otherwise makedepend will parse it as a source file. -arch) eat=yes ;; -*|$object) ;; *) set fnord "$@" "$arg"; shift ;; esac done obj_suffix=`echo "$object" | sed 's/^.*\././'` touch "$tmpdepfile" ${MAKEDEPEND-makedepend} -o"$obj_suffix" -f"$tmpdepfile" "$@" rm -f "$depfile" # makedepend may prepend the VPATH from the source file name to the object. # No need to regex-escape $object, excess matching of '.' is harmless. sed "s|^.*\($object *:\)|\1|" "$tmpdepfile" > "$depfile" sed '1,2d' "$tmpdepfile" | tr ' ' ' ' | \ ## Some versions of the HPUX 10.20 sed can't process this invocation ## correctly. Breaking it into two sed invocations is a workaround. sed -e 's/^\\$//' -e '/^$/d' -e '/:$/d' | sed -e 's/$/ :/' >> "$depfile" rm -f "$tmpdepfile" "$tmpdepfile".bak ;; cpp) # Important note: in order to support this mode, a compiler *must* # always write the preprocessed file to stdout. "$@" || exit $? # Remove the call to Libtool. if test "$libtool" = yes; then while test "X$1" != 'X--mode=compile'; do shift done shift fi # Remove `-o $object'. IFS=" " for arg do case $arg in -o) shift ;; $object) shift ;; *) set fnord "$@" "$arg" shift # fnord shift # $arg ;; esac done "$@" -E | sed -n -e '/^# [0-9][0-9]* "\([^"]*\)".*/ s:: \1 \\:p' \ -e '/^#line [0-9][0-9]* "\([^"]*\)".*/ s:: \1 \\:p' | sed '$ s: \\$::' > "$tmpdepfile" rm -f "$depfile" echo "$object : \\" > "$depfile" cat < "$tmpdepfile" >> "$depfile" sed < "$tmpdepfile" '/^$/d;s/^ //;s/ \\$//;s/$/ :/' >> "$depfile" rm -f "$tmpdepfile" ;; msvisualcpp) # Important note: in order to support this mode, a compiler *must* # always write the preprocessed file to stdout. "$@" || exit $? # Remove the call to Libtool. if test "$libtool" = yes; then while test "X$1" != 'X--mode=compile'; do shift done shift fi IFS=" " for arg do case "$arg" in -o) shift ;; $object) shift ;; "-Gm"|"/Gm"|"-Gi"|"/Gi"|"-ZI"|"/ZI") set fnord "$@" shift shift ;; *) set fnord "$@" "$arg" shift shift ;; esac done "$@" -E 2>/dev/null | sed -n '/^#line [0-9][0-9]* "\([^"]*\)"/ s::\1:p' | $cygpath_u | sort -u > "$tmpdepfile" rm -f "$depfile" echo "$object : \\" > "$depfile" sed < "$tmpdepfile" -n -e 's% %\\ %g' -e '/^\(.*\)$/ s:: \1 \\:p' >> "$depfile" echo " " >> "$depfile" sed < "$tmpdepfile" -n -e 's% %\\ %g' -e '/^\(.*\)$/ s::\1\::p' >> "$depfile" rm -f "$tmpdepfile" ;; msvcmsys) # This case exists only to let depend.m4 do its work. It works by # looking at the text of this script. This case will never be run, # since it is checked for above. exit 1 ;; none) exec "$@" ;; *) echo "Unknown depmode $depmode" 1>&2 exit 1 ;; esac exit 0 # Local Variables: # mode: shell-script # sh-indentation: 2 # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" # time-stamp-time-zone: "UTC" # time-stamp-end: "; # UTC" # End: mu-0.9.9.5/mu4e/0000775000175000017500000000000012125532705010174 500000000000000mu-0.9.9.5/mu4e/Makefile.am0000644000175000017500000000314612125531126012146 00000000000000## Copyright (C) 2008-2013 Dirk-Jan C. Binnema ## ## This program is free software; you can redistribute it and/or modify ## it under the terms of the GNU General Public License as published by ## the Free Software Foundation; either version 3 of the License, or ## (at your option) any later version. ## ## This program is distributed in the hope that it will be useful, ## but WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ## GNU General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with this program; if not, write to the Free Software Foundation, ## Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. include $(top_srcdir)/gtest.mk SUBDIRS= info_TEXINFOS=mu4e.texi mu4e_TEXINFOS=fdl.texi lispdir=${prefix}/share/emacs/site-lisp/mu4e/ dist_lisp_LISP= \ mu4e-about.el \ mu4e-actions.el \ mu4e-compose.el \ mu4e-draft.el \ mu4e-headers.el \ mu4e-lists.el \ mu4e-main.el \ mu4e-mark.el \ mu4e-message.el \ mu4e-meta.el \ mu4e-proc.el \ mu4e-speedbar.el \ mu4e-utils.el \ mu4e-vars.el \ mu4e-view.el \ mu4e.el \ org-mu4e.el mu4e-about.el: mu4e-about.org @echo ";; auto-generated" > mu4e-about.el @echo "(defconst mu4e-about \"" >> mu4e-about.el @sed 's/"/\\"/g' < mu4e-about.org >> mu4e-about.el @echo "\" \"About mu4e.\")" >> mu4e-about.el @echo "(provide 'mu4e-about)" >> mu4e-about.el EXTRA_DIST=$(elisp_DATA) mu4e-about.org CLEANFILES=*.elc ${BUILT_SOURCES} mu-0.9.9.5/mu4e/mu4e-meta.el0000664000175000017500000000034312125531220012223 00000000000000;; auto-generated (defconst mu4e-mu-version "0.9.9.5" "Required mu binary version; mu4e's version must agree with this.") (defconst mu4e-builddir "/home/djcb/Sources/mu" "Top-level build directory.") (provide 'mu4e-meta) mu-0.9.9.5/mu4e/mu4e-main.el0000644000175000017500000001342312106262361012230 00000000000000;;; mu4e-main.el -- part of mu4e, the mu mail user agent ;; ;; Copyright (C) 2011-2012 Dirk-Jan C. Binnema ;; Author: Dirk-Jan C. Binnema ;; Maintainer: Dirk-Jan C. Binnema ;; This file is not part of GNU Emacs. ;; ;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or ;; (at your option) any later version. ;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . ;;; Commentary: ;;; Code: ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (require 'smtpmail) ;; the queing stuff (silence elint) (require 'mu4e-utils) ;; utility functions (defconst mu4e~main-buffer-name " *mu4e-main*" "*internal* Name of the mu4e main view buffer.") (defvar mu4e-main-mode-map (let ((map (make-sparse-keymap))) (define-key map "b" 'mu4e-headers-search-bookmark) (define-key map "B" 'mu4e-headers-search-bookmark-edit) (define-key map "s" 'mu4e-headers-search) (define-key map "q" 'mu4e-quit) (define-key map "j" 'mu4e~headers-jump-to-maildir) (define-key map "C" 'mu4e-compose-new) (define-key map "m" 'mu4e~main-toggle-mail-sending-mode) (define-key map "f" 'smtpmail-send-queued-mail) ;; (define-key map "U" 'mu4e-update-mail-and-index) (define-key map (kbd "C-S-u") 'mu4e-update-mail-and-index) (define-key map "$" 'mu4e-show-log) (define-key map "A" 'mu4e-about) (define-key map "H" 'mu4e-display-manual) map) "Keymap for the *mu4e-main* buffer.") (fset 'mu4e-main-mode-map mu4e-main-mode-map) (defvar mu4e-main-mode-abbrev-table nil) (define-derived-mode mu4e-main-mode special-mode "mu4e:main" "Major mode for the mu4e main screen. \\{mu4e-main-mode-map}." (use-local-map mu4e-main-mode-map) (setq truncate-lines t overwrite-mode 'overwrite-mode-binary)) (defun mu4e~main-action-str (str &optional func-or-shortcut) "Highlight the first occurence of [..] in STR. If FUNC-OR-SHORTCUT is non-nil and if it is a function, call it when STR is clicked (using RET or mouse-2); if FUNC-OR-SHORTCUT is a string, execute the corresponding keyboard action when it is clicked." (let ((newstr (replace-regexp-in-string "\\[\\(\\w+\\)\\]" (lambda(m) (format "[%s]" (propertize (match-string 1 str) 'face 'mu4e-highlight-face))) str)) (map (make-sparse-keymap)) (func (if (functionp func-or-shortcut) func-or-shortcut (if (stringp func-or-shortcut) (lexical-let ((macro func-or-shortcut)) (lambda()(interactive) (execute-kbd-macro macro))))))) (define-key map [mouse-2] func) (define-key map (kbd "RET") func) (put-text-property 0 (length newstr) 'keymap map newstr) (put-text-property (string-match "\\w" newstr) (- (length newstr) 1) 'mouse-face 'highlight newstr) newstr)) (defun mu4e~main-view () "Show the mu4e main view." (let ((buf (get-buffer-create mu4e~main-buffer-name)) (inhibit-read-only t)) (with-current-buffer buf (erase-buffer) (insert "* " (propertize "mu4e - mu for emacs version " 'face 'mu4e-title-face) (propertize mu4e-mu-version 'face 'mu4e-view-header-key-face) ;; show some server properties; in this case; a big C when there's ;; crypto support, a big G when there's Guile support " " (propertize (concat (when (plist-get mu4e~server-props :crypto) "C") (when (plist-get mu4e~server-props :guile) "G")) 'face 'mu4e-title-face) "\n\n" (propertize " Basics\n\n" 'face 'mu4e-title-face) (mu4e~main-action-str "\t* [j]ump to some maildir\n" 'mu4e-jump-to-maildir) (mu4e~main-action-str "\t* enter a [s]earch query\n" 'mu4e-search) (mu4e~main-action-str "\t* [C]ompose a new message\n" 'mu4e-compose-new) "\n" (propertize " Bookmarks\n\n" 'face 'mu4e-title-face) ;; TODO: it's a bit uncool to hard-code the "b" shortcut... (mapconcat (lambda (bm) (let* ((query (nth 0 bm)) (title (nth 1 bm)) (key (nth 2 bm))) (mu4e~main-action-str (concat "\t* [b" (make-string 1 key) "] " title) (concat "b" (make-string 1 key))))) mu4e-bookmarks "\n") "\n\n" (propertize " Misc\n\n" 'face 'mu4e-title-face) (mu4e~main-action-str "\t* [U]pdate email & database\n" 'mu4e-update-mail-show-window) ;; show the queue functions if `smtpmail-queue-dir' is defined (if (file-directory-p smtpmail-queue-dir) (concat (mu4e~main-action-str "\t* toggle [m]ail sending mode " 'mu4e~main-toggle-mail-sending-mode) "(" (propertize (if smtpmail-queue-mail "queued" "direct") 'face 'mu4e-view-header-key-face) ")\n" (mu4e~main-action-str "\t* [f]lush queued mail\n" 'smtpmail-send-queued-mail)) "") "\n" (mu4e~main-action-str "\t* [A]bout mu4e\n" 'mu4e-about) (mu4e~main-action-str "\t* [H]elp\n" 'mu4e-display-manual) (mu4e~main-action-str "\t* [q]uit\n" 'mu4e-quit)) (mu4e-main-mode) (switch-to-buffer buf)))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Interactive functions (defun mu4e~main-toggle-mail-sending-mode () "Toggle sending mail mode, either queued or direct." (interactive) (unless (file-directory-p smtpmail-queue-dir) (mu4e-error "`smtpmail-queue-dir' does not exist")) (setq smtpmail-queue-mail (not smtpmail-queue-mail)) (message (concat "Outgoing mail will now be " (if smtpmail-queue-mail "queued" "sent directly"))) (mu4e~main-view)) (provide 'mu4e-main) mu-0.9.9.5/mu4e/mu4e-message.el0000664000175000017500000002114012066007462012731 00000000000000;;; mu4e-message.el -- part of mu4e, the mu mail user agent ;; ;; Copyright (C) 2012 Dirk-Jan C. Binnema ;; Author: Dirk-Jan C. Binnema ;; Maintainer: Dirk-Jan C. Binnema ;; This file is not part of GNU Emacs. ;; ;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or ;; (at your option) any later version. ;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . ;;; Commentary: ;; Functions to get data from mu4e-message plist structure ;;; Code: (eval-when-compile (byte-compile-disable-warning 'cl-functions)) (require 'mu4e-vars) (require 'mu4e-utils) (require 'cl) (require 'html2text) (defcustom mu4e-html2text-command nil "Shell command that converts from html to plain text. The command has to read html from stdin and output plain text on stdout. If this is not defined, the emacs `html2text' tool will be used when faced with html-only message. If you use htmltext, it's recommended you use \"html2text -utf8 -width 72\"." :type 'string :group 'mu4e-view :safe 'stringp) (defcustom mu4e-view-prefer-html nil "Whether to base the body display on the html-version. If the e-mail message has no html-version the plain-text version is always used." :type 'boolean :group 'mu4e-view) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defsubst mu4e-message-field-raw (msg field) "Retrieve FIELD from message plist MSG. FIELD is one of :from, :to, :cc, :bcc, :subject, :data, :message-id, :path, :maildir, :priority, :attachments, :references, :in-reply-to, :body-txt, :body-html Returns `nil' if the field does not exist. A message plist looks something like: \(:docid 32461 :from ((\"Nikola Tesla\" . \"niko@example.com\")) :to ((\"Thomas Edison\" . \"tom@example.com\")) :cc ((\"Rupert The Monkey\" . \"rupert@example.com\")) :subject \"RE: what about the 50K?\" :date (20369 17624 0) :size 4337 :message-id \"6BDC23465F79238C8233AB82D81EE81AF0114E4E74@123213.mail.example.com\" :path \"/home/tom/Maildir/INBOX/cur/133443243973_1.10027.atlas:2,S\" :maildir \"/INBOX\" :priority normal :flags (seen) :attachments ((:index 2 :name \"photo.jpg\" :mime-type \"image/jpeg\" :size 147331) (:index 3 :name \"book.pdf\" :mime-type \"application/pdf\" :size 192220)) :references (\"6BDC23465F79238C8384574032D81EE81AF0114E4E74@123213.mail.example.com\" \"6BDC23465F79238203498230942D81EE81AF0114E4E74@123213.mail.example.com\") :in-reply-to \"6BDC23465F79238203498230942D81EE81AF0114E4E74@123213.mail.example.com\" :body-txt \"Hi Tom, ...\" \)). 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 in `current-time' - Attachments are a list of elements with fields :index (the number of the MIME-part), :name (the file name, if any), :mime-type (the MIME-type, if any) and :size (the size in bytes, if any). - Messages in the Headers view come from the database and do not have :attachments, :body-txt or :body-html fields. Message in the Message view use the actual message file, and do include these fields." ;; after all this documentation, the spectacular implementation (if msg (plist-get msg field) (mu4e-error "message must be non-nil"))) (defsubst mu4e-message-field (msg field) "Retrieve FIELD from message plist MSG. Like `mu4e-message-field-nil', but will sanitize `nil' values: - all string field except body-txt/body-html: nil -> \"\" - numeric fields + dates : nil -> 0 - all others : return the value Thus, function will return nil for empty lists, non-existing body-txt or body-html." (let ((val (mu4e-message-field-raw msg field))) (cond (val val) ;; non-nil -> just return it ((member field '(:subject :message-id :path :maildir :in-reply-to)) "") ;; string fields except body-txt, body-html: nil -> "" ((member field '(:body-html :body-txt)) val) ((member field '(:docid :size)) 0) ;; numeric type: nil -> 0 (t val)))) ;; otherwise, just return nil (defsubst mu4e-message-has-field (msg field) "Return t if MSG contains FIELD, nil otherwise." (plist-member msg field)) (defsubst mu4e-message-at-point (&optional noerror) "Get the message s-expression for the message at point in either the headers buffer or the view buffer, or nil if there is no such message. If optional NOERROR is non-nil, do not raise an error when there is no message at point." (let ((msg (or (get-text-property (point) 'msg) mu4e~view-msg))) (if msg msg (unless noerror (mu4e-warn "No message at point"))))) (defsubst mu4e-message-field-at-point (field) "Get the field FIELD from the message at point. This is equivalent to: (mu4e-message-field (mu4e-message-at-point) FIELD)." (mu4e-message-field (mu4e-message-at-point) field)) (defun mu4e-message-body-text (msg) "Get the body in text form for this message. This is either :body-txt, or if not available, :body-html converted to text. By default, it uses the emacs built-in `html2text'. Alternatively, if `mu4e-html2text-command' is non-nil, it will use that. Normally, function prefers the text part, but this can be changed by setting `mu4e-view-prefer-html'." (let* ((txt (mu4e-message-field msg :body-txt)) (html (mu4e-message-field msg :body-html)) (body (cond ;; does it look like some text? ie., 10x the length of the text ;; should be longer than the html, an heuristic to guard against ;; 'This messages requires html' text bodies. ((and (> (* 10 (length txt)) (length html)) ;; use html if it's prefered, unless there is no html (or (not mu4e-view-prefer-html) (not html))) txt) ;; otherwise, it there some html? (html (with-temp-buffer (insert html) ;; if defined, use the external tool (if mu4e-html2text-command (shell-command-on-region (point-min) (point-max) mu4e-html2text-command nil t) ;; otherwise... (html2text)) (buffer-string))) (t ;; otherwise, an empty body "")))) ;; and finally, remove some crap from the remaining string; it seems ;; esp. outlook lies about its encoding (ie., it says 'iso-8859-1' but ;; really it's 'windows-1252'), thus giving us these funky chars. here, we ;; either remove them, or replace with 'what-was-meant' (heuristically) (with-temp-buffer (insert body) (goto-char (point-min)) (while (re-search-forward "[ ]" nil t) (replace-match (cond ((string= (match-string 0) "") "'") (t "")))) (buffer-string)))) (defun mu4e-message-contact-field-matches (msg cfield rx) "Checks whether any of the of the contacts in field CFIELD (either :to, :from, :cc or :bcc) of msg MSG matches (with their name or e-mail address) regular expressions RX. If there is a match, return non-nil; otherwise return nil. RX can also be a list of regular expressions, in which case any of those are tried for a match." (unless (member cfield '(:to :from :bcc :cc)) (mu4e-error "Not a contacts field (%S)" cfield)) (if (listp rx) ;; if rx is a list, try each one of them for a match (find-if (lambda (a-rx) (mu4e-message-contact-field-matches msg cfield a-rx)) rx) ;; not a list, check the rx (find-if (lambda (ct) (let ((name (car ct)) (email (cdr ct))) (or (and name (string-match rx name)) (and email (string-match rx email))))) (mu4e-message-field msg cfield)))) (defsubst mu4e-message-part-field (msgpart field) "Get some field in a message part; a part would look something like: (:index 2 :name \"photo.jpg\" :mime-type \"image/jpeg\" :size 147331)." (plist-get msgpart field)) ;; backward compatibility ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defalias 'mu4e-msg-field 'mu4e-message-field) (defalias 'mu4e-body-text 'mu4e-message-body-text) ;; backward compatibility (defun mu4e-field-at-point (field) "Get FIELD (a symbol, see `mu4e-header-info') for the message at point in eiter the headers buffer or the view buffer." (plist-get (mu4e-message-at-point) field)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (provide 'mu4e-message) mu-0.9.9.5/mu4e/mu4e.el0000664000175000017500000000565312051015620011307 00000000000000;;; mu4e.el -- part of mu4e, the mu mail user agent ;; ;; Copyright (C) 2011-2012 Dirk-Jan C. Binnema ;; Author: Dirk-Jan C. Binnema ;; Maintainer: Dirk-Jan C. Binnema ;; Keywords: email ;; Version: 0.0 ;; This file is not part of GNU Emacs. ;; ;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or ;; (at your option) any later version. ;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . ;;; Commentary: ;;; Code: (eval-when-compile (require 'cl)) (require 'mu4e-meta) ;; autogenerated file with metadata (version etc.) (require 'mu4e-headers) ;; headers view (require 'mu4e-view) ;; message view (require 'mu4e-main) ;; main screen (require 'mu4e-compose) ;; message composition / sending (require 'mu4e-proc) ;; communication with backend (require 'mu4e-utils) ;; utility functions (require 'mu4e-speedbar) ;; support for speedbar ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; register our handler functions; these connect server messages to functions ;; to handle them. ;; ;; ;; these are all defined in mu4e-headers (setq mu4e-update-func 'mu4e~headers-update-handler) (setq mu4e-header-func 'mu4e~headers-header-handler) (setq mu4e-found-func 'mu4e~headers-found-handler) (setq mu4e-view-func 'mu4e~headers-view-handler) (setq mu4e-remove-func 'mu4e~headers-remove-handler) (setq mu4e-erase-func 'mu4e~headers-clear) ;; these ones are defined in mu4e-utils (setq mu4e-info-func 'mu4e-info-handler) (setq mu4e-error-func 'mu4e-error-handler) ;; note: mu4e-utils also dynamically (temporarily) ;; registers mu4e-pong func ;; this one is defined in mu4e-compose (setq mu4e-compose-func 'mu4e~compose-handler) ;; note: mu4e-compose.el dynamically registers mu4e-sent-func ;; we don't do that here, because it's only a local (temporary) ;; handler ;; this one is defined in mu4e-view (setq mu4e-temp-func 'mu4e~view-temp-handler) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;;###autoload (defun mu4e () "Start mu4e." (interactive) ;; start mu4e, then show the main view (mu4e~start 'mu4e~main-view)) (defun mu4e-quit() "Quit the mu4e session." (interactive) (if mu4e-confirm-quit (when (y-or-n-p (mu4e-format "Are you sure you want to quit?")) (mu4e~stop)) (mu4e~stop))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (provide 'mu4e) mu-0.9.9.5/mu4e/mu4e-compose.el0000644000175000017500000005346012113227366012762 00000000000000;; mu4e-compose.el -- part of mu4e, the mu mail user agent for emacs ;; ;; Copyright (C) 2011-2012 Dirk-Jan C. Binnema ;; Author: Dirk-Jan C. Binnema ;; Maintainer: Dirk-Jan C. Binnema ;; This file is not part of GNU Emacs. ;; ;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or ;; (at your option) any later version. ;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . ;;; Commentary: ;; In this file, various functions to compose/send messages, piggybacking on ;; gnus' message mode ;; Magic / Rupe Goldberg ;; 1) When we reply/forward a message, we get it from the backend, ie: ;; we send to the backend (mu4e-compose): ;; compose type:reply docid:30935 ;; backend responds with: ;; (:compose reply :original ( .... )) ;; 2) When we compose a message, message and headers are separated by ;; `mail-header-separator', ie. '--text follows this line--. We use ;; before-save-hook and after-save-hook to remove/re-add this special line, so ;; it stays in the buffer, but never hits the disk. ;; see: ;; mu4e~compose-insert-mail-header-separator ;; mu4e~compose-remove-mail-header-separator ;; ;; (maybe we can get away with remove it only just before sending? what does ;; gnus do?) ;; 3) When sending a message, we want to do a few things: ;; a) move the message from drafts to the sent folder (maybe; depends on ;; `mu4e-sent-messages-behavior') ;; b) if it's a reply, mark the replied-to message as "R", i.e. replied ;; if it's a forward, mark the forwarded message as "P", i.e. passed (forwarded) ;; c) kill all buffers looking at the sent message ;; a) is dealt with by message-mode, but we need to tell it where to move the ;; sent message. We do this by adding an Fcc: header with the target folder, ;; see `mu4e~compose-setup-fcc-maybe'. Since message-mode does not natively ;; understand maildirs, we also need to tell it what to do, so we also set ;; `message-fcc-handler-function' there. Finally, we add the the message in ;; the sent-folder to the database. ;; ;; b) this is handled in `mu4e~compose-set-parent-flag' ;; ;; c) this is handled in our handler for the `sent'-message from the backend ;; (`mu4e-sent-handler') ;; ;;; Code: (eval-when-compile (byte-compile-disable-warning 'cl-functions)) (require 'cl) (require 'message) (require 'mail-parse) (require 'smtpmail) (require 'rfc2368) (require 'mu4e-utils) (require 'mu4e-vars) (require 'mu4e-proc) (require 'mu4e-actions) (require 'mu4e-message) (require 'mu4e-draft) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Composing / Sending messages (defgroup mu4e-compose nil "Customizations for composing/sending messages." :group 'mu4e) (defcustom mu4e-sent-messages-behavior 'sent "Determines what mu4e does with sent messages. This is one of the symbols: * `sent' move the sent message to the Sent-folder (`mu4e-sent-folder') * `trash' move the sent message to the Trash-folder (`mu4e-trash-folder') * `delete' delete the sent message. Note, when using GMail/IMAP, you should set this to either `trash' or `delete', since GMail already takes care of keeping copies in the sent folder." :type '(choice (const :tag "move message to mu4e-sent-folder" sent) (const :tag "move message to mu4e-trash-folder" trash) (const :tag "delete message" delete)) :safe 'symbolp :group 'mu4e-compose) (defvar mu4e-compose-pre-hook nil "Hook run just *before* message composition starts. If the compose-type is either /reply/ or /forward/, the variable `mu4e-compose-parent-message' points to the message replied to / being forwarded / edited.") ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defun mu4e-compose-attach-captured-message () "Insert the last captured message file as an attachment. Messages are captured with `mu4e-action-capture-message'." (interactive) (unless mu4e-captured-message (mu4e-warn "No message has been captured")) (let ((path (plist-get mu4e-captured-message :path))) (unless (file-exists-p path) (mu4e-warn "Captured message file not found")) (mml-attach-file path "message/rfc822" (or (plist-get mu4e-captured-message :subject) "No subject") "attachment"))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; 'fcc' refers to saving a copy of a sent message to a certain folder. that's ;; what these 'Sent mail' folders are for! ;; ;; We let message mode take care of this by adding a field ;; Fcc: ;; in the "message-send-hook" (ie., just before sending). message mode will ;; then take care of the saving when the message is actually sent. ;; ;; note, where and if you make this copy depends on the value of ;; `mu4e-sent-messages-behavior'. (defun mu4e~compose-setup-fcc-maybe () "Maybe setup Fcc, based on `mu4e-sent-messages-behavior'. If needed, set the Fcc header, and register the handler function." (let* ((mdir (case mu4e-sent-messages-behavior (delete nil) (trash (mu4e-get-trash-folder mu4e-compose-parent-message)) (sent (mu4e-get-sent-folder mu4e-compose-parent-message)) (otherwise (mu4e-error "unsupported value '%S' `mu4e-sent-messages-behavior'." mu4e-sent-messages-behavior)))) (fccfile (and mdir (concat mu4e-maildir mdir "/cur/" (mu4e~draft-message-filename-construct "S"))))) ;; if there's an fcc header, add it to the file (when fccfile (message-add-header (concat "Fcc: " fccfile "\n")) ;; sadly, we cannot define as 'buffer-local'... this will screw up gnus ;; etc. if you run it after mu4e so, (hack hack) we reset it to the old ;; handler after we've done our thing. (setq message-fcc-handler-function (lexical-let ((maildir mdir) (old-handler message-fcc-handler-function)) (lambda (file) (setq message-fcc-handler-function old-handler) ;; reset the fcc handler (write-file file) ;; writing maildirs files is easy (mu4e~proc-add file maildir))))))) ;; update the database (defun mu4e~compose-register-message-save-hooks () "Just before saving, we remove the mail-header-separator; just after saving we restore it; thus, the separator should never appear on disk." (add-hook 'before-save-hook 'mu4e~draft-remove-mail-header-separator nil t) (add-hook 'after-save-hook (lambda () (mu4e~compose-set-friendly-buffer-name) (mu4e~draft-insert-mail-header-separator) (set-buffer-modified-p nil) ;; update the file on disk -- ie., without the separator (mu4e~proc-add (buffer-file-name) mu4e~draft-drafts-folder)) nil t)) (defconst mu4e~compose-hidden-headers `("^References:" "^Face:" "^X-Face:" "^X-Draft-From:" "^User-agent:") "Hidden headers when composing.") (defconst mu4e~compose-address-fields-regexp "^\\(To\\|B?Cc\\|Reply-To\\|From\\):") (defun mu4e~compose-find-completion-style (some-style) "Find completion style SOME-STYLE in completion-styles-alist, or return nil." (find-if (lambda (style) (eq some-style (car style))) completion-styles-alist)) (defconst mu4e~completion-cycle-treshold 5 "mu4e value for `completion-cycle-treshold'.") (defun mu4e~compose-setup-completion () "Set up autocompletion of addresses." (let ((compstyle (or (mu4e~compose-find-completion-style 'substring) (mu4e~compose-find-completion-style 'partial-completion)))) ;; emacs-24+ has 'substring, otherwise we try partial-completion, otherwise ;; we leave it at the default (when compstyle (make-local-variable 'completion-styles) (add-to-list 'completion-styles (car compstyle))) (when (boundp 'completion-cycle-threshold) (make-local-variable 'completion-cycle-threshold) (setq completion-cycle-threshold mu4e~completion-cycle-treshold)) (add-to-list 'completion-at-point-functions 'mu4e~compose-complete-contact) ;; needed for emacs 23... (when (= emacs-major-version 23) (make-local-variable 'message-completion-alist) (setq message-completion-alist (cons (cons mu4e~compose-address-fields-regexp 'completion-at-point) message-completion-alist))))) (defvar mu4e-compose-mode-abbrev-table nil) (define-derived-mode mu4e-compose-mode message-mode "mu4e:compose" "Major mode for the mu4e message composition, derived from `message-mode'. \\{message-mode-map}." (let ((message-hidden-headers mu4e~compose-hidden-headers)) (use-local-map mu4e-compose-mode-map) (make-local-variable 'message-default-charset) ;; if the default charset is not set, use UTF-8 (unless message-default-charset (setq message-default-charset 'utf-8)) ;; make completion case-insensitive (set (make-local-variable 'completion-ignore-case) t) ;; make sure mu4e is started in the background (ie. we don't want to error ;; out when sending the message; better to do it now if there's a problem) (mu4e~start) ;; start mu4e in background, if needed (mu4e~compose-register-message-save-hooks) ;; set the default directory to the user's home dir; this is probably more ;; useful e.g. when finding an attachment file the directory the current ;; mail files lives in... (setq default-directory (expand-file-name "~/")) ;; offer completion for e-mail addresses (when (and mu4e-compose-complete-addresses (boundp 'completion-at-point-functions)) (mu4e~compose-setup-completion)) (define-key mu4e-compose-mode-map (kbd "C-S-u") 'mu4e-update-mail-and-index) ;; setup the fcc-stuff, if needed (add-hook 'message-send-hook (defun mu4e~compose-save-before-sending () ;; for safety, always save the draft before sending (set-buffer-modified-p t) (save-buffer) (mu4e~compose-setup-fcc-maybe)) nil t) ;; when the message has been sent. (add-hook 'message-sent-hook (defun mu4e~compose-mark-after-sending () (setq mu4e-sent-func 'mu4e-sent-handler) (mu4e~proc-sent (buffer-file-name) mu4e~draft-drafts-folder)) nil)) ;; mark these two hooks as permanent-local, so they'll survive mode-changes ;; (put 'mu4e~compose-save-before-sending 'permanent-local-hook t) (put 'mu4e~compose-mark-after-sending 'permanent-local-hook t)) (defconst mu4e~compose-buffer-max-name-length 30 "Maximum length of the mu4e-send-buffer-name.") (defun mu4e~compose-set-friendly-buffer-name (&optional compose-type) "Set some user-friendly buffer name based on the compose type." (let* ((subj (message-field-value "subject")) (subj (unless (and subj (string-match "^[:blank:]*$" subj)) subj)) (str (or subj (case compose-type (reply "*reply*") (forward "*forward*") (otherwise "*draft*"))))) (rename-buffer (generate-new-buffer-name (truncate-string-to-width str mu4e~compose-buffer-max-name-length nil nil t))))) (defconst mu4e~compose-hidden-headers '("^References:" "^Face:" "^X-Face:" "^X-Draft-From:" "^User-Agent:" "^In-Reply-To:") "List of regexps with message headers that are to be hidden.") (defun mu4e~compose-handler (compose-type &optional original-msg includes) "Create a new draft message, or open an existing one. COMPOSE-TYPE determines the kind of message to compose and is a symbol, either `reply', `forward', `edit', `new'. `edit' is for editing existing messages. When COMPOSE-TYPE is `reply' or `forward', MSG should be a message plist. If COMPOSE-TYPE is `new', ORIGINAL-MSG should be nil. Optionally (when forwarding, replying) ORIGINAL-MSG is the original message we will forward / reply to. Optionally (when forwarding) INCLUDES contains a list of (:file-name :mime-type :disposition ) for the attachements to include; file-name refers to a file which our backend has conveniently saved for us (as a tempfile)." ;; Run the hooks defined for `mu4e-compose-pre-hook'. If compose-type is ;; `reply', `forward' or `edit', `mu4e-compose-parent-message' points to the ;; message being forwarded or replied to, otherwise it is nil. (set (make-local-variable 'mu4e-compose-parent-message) original-msg) (put 'mu4e-compose-parent-message 'permanent-local t) (run-hooks 'mu4e-compose-pre-hook) ;; this opens (or re-opens) a messages with all the basic headers set. (mu4e-draft-open compose-type original-msg) ;; insert mail-header-separator, which is needed by message mode to separate ;; headers and body. will be removed before saving to disk (mu4e~draft-insert-mail-header-separator) (insert "\n") ;; insert a newline after header separator ;; include files -- e.g. when forwarding a message with attachments, ;; we take those from the original. (save-excursion (goto-char (point-max)) ;; put attachments at the end (dolist (att includes) (mml-attach-file (plist-get att :file-name) (plist-get att :mime-type)))) ;; include the message signature (if it's set); but not when editing an ;; existing message. (unless (eq compose-type 'edit) (message-insert-signature)) ;; hide some headers (let ((message-hidden-headers mu4e~compose-hidden-headers)) (message-hide-headers)) ;; buffer is not user-modified yet (mu4e~compose-set-friendly-buffer-name compose-type) (set-buffer-modified-p nil) ;; now jump to some useful positions, and start writing that mail! (if (member compose-type '(new forward)) (message-goto-to) (message-goto-body)) ;; bind to `mu4e-compose-parent-message' of compose buffer (set (make-local-variable 'mu4e-compose-parent-message) original-msg) (put 'mu4e-compose-parent-message 'permanent-local t) ;; switch on the mode (mu4e-compose-mode)) (defun mu4e-sent-handler (docid path) "Handler function, called with DOCID and PATH for the just-sent message. For Forwarded ('Passed') and Replied messages, try to set the appropriate flag at the message forwarded or replied-to." (mu4e~compose-set-parent-flag path) (when (file-exists-p path) ;; maybe the draft was not saved at all (mu4e~proc-remove docid)) ;; kill any remaining buffers for the draft file, or they will hang around... ;; this seems a bit hamfisted... (dolist (buf (buffer-list)) (when (and (buffer-file-name buf) (string= (buffer-file-name buf) path)) (kill-buffer buf))) ;; now, try to go back to some previous buffer, in the order ;; view->headers->main (if (buffer-live-p mu4e~view-buffer) (switch-to-buffer mu4e~view-buffer) (if (buffer-live-p mu4e~headers-buffer) (switch-to-buffer mu4e~headers-buffer) ;; if all else fails, back to the main view (when (fboundp 'mu4e) (mu4e)))) (mu4e-message "Message sent")) (defun mu4e~compose-set-parent-flag (path) "Set the 'replied' \"R\" flag on messages we replied to, and the 'passed' \"F\" flag on message we have forwarded. If a message has an 'in-reply-to' header, it is considered a reply to the message with the corresponding message id. If it does not have an 'in-reply-to' header, but does have a 'references' header, it is considered to be a forward message for the message corresponding with the /last/ message-id in the references header. Now, if the message has been determined to be either a forwarded message or a reply, we instruct the server to update that message with resp. the 'P' (passed) flag for a forwarded message, or the 'R' flag for a replied message. Function assumes that it's executed in the context of the message buffer." (let ((buf (find-file-noselect path))) (when buf (with-current-buffer buf (let ((in-reply-to (message-fetch-field "in-reply-to")) (forwarded-from) (references (message-fetch-field "references"))) (unless in-reply-to (when references (with-temp-buffer ;; inspired by `message-shorten-references'. (insert references) (goto-char (point-min)) (let ((refs)) (while (re-search-forward "<[^ <]+@[^ <]+>" nil t) (push (match-string 0) refs)) ;; the last will be the first (setq forwarded-from (first refs)))))) ;; remove the <> (when (and in-reply-to (string-match "<\\(.*\\)>" in-reply-to)) (mu4e~proc-move (match-string 1 in-reply-to) nil "+R")) (when (and forwarded-from (string-match "<\\(.*\\)>" forwarded-from)) (mu4e~proc-move (match-string 1 forwarded-from) nil "+P"))))))) (defun mu4e-compose (compose-type) "Start composing a message of COMPOSE-TYPE, where COMPOSE-TYPE is a symbol, one of `reply', `forward', `edit', `new'. All but `new' take the message at point as input. Symbol `edit' is only allowed for draft messages." (let ((msg (mu4e-message-at-point 'noerror))) ;; some sanity checks (unless (or msg (eq compose-type 'new)) (mu4e-warn "No message at point")) (unless (member compose-type '(reply forward edit new)) (mu4e-error "Invalid compose type '%S'" compose-type)) (when (and (eq compose-type 'edit) (not (member 'draft (mu4e-message-field msg :flags)))) (mu4e-warn "Editing is only allowed for draft messages")) ;; 'new is special, since it takes no existing message as arg; therefore, we ;; don't need to involve the backend, and call the handler *directly* (if (eq compose-type 'new) (mu4e~compose-handler 'new) ;; otherwise, we need the doc-id (let ((docid (mu4e-message-field msg :docid))) ;; if there's a visible view window, select that before starting composing ;; a new message, so that one will be replaced by the compose window. The ;; 10-or-so line headers buffer is not a good place to write it... (let ((viewwin (get-buffer-window mu4e~view-buffer))) (when (window-live-p viewwin) (select-window viewwin))) ;; talk to the backend (mu4e~proc-compose compose-type docid))))) (defun mu4e-compose-reply () "Compose a reply for the message at point in the headers buffer." (interactive) (mu4e-compose 'reply)) (defun mu4e-compose-forward () "Forward the message at point in the headers buffer." (interactive) (mu4e-compose 'forward)) (defun mu4e-compose-edit () "Edit the draft message at point in the headers buffer. This is only possible if the message at point is, in fact, a draft message." (interactive) (mu4e-compose 'edit)) (defun mu4e-compose-new () "Start writing a new message." (interactive) (mu4e-compose 'new)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; address completion; inspired by org-contacts.el (defun mu4e~compose-complete-contact (&optional start) "Complete the text at START with a contact. Ie. either 'name ' or 'email')." (interactive) (let ((mail-abbrev-mode-regexp mu4e~compose-address-fields-regexp) (eoh ;; end-of-headers (save-excursion (goto-char (point-min)) (search-forward-regexp mail-header-separator nil t)))) ;; try to complete only when we're in the headers area, ;; looking at an address field. (when (and eoh (> eoh (point)) (mail-abbrev-in-expansion-header-p)) (let* ((end (point)) (start (or start (save-excursion (re-search-backward "\\(\\`\\|[\n:,]\\)[ \t]*") (goto-char (match-end 0)) (point))))) (list start end mu4e~contacts-for-completion))))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; mu4e-compose-func and mu4e-send-func are wrappers so we can set ourselves ;; as default emacs mailer (define-mail-user-agent etc.) ;;;###autoload (defun mu4e~compose-mail (&optional to subject other-headers continue switch-function yank-action send-actions return-action) "This is mu4e's implementation of `compose-mail'." ;; create a new draft message 'resetting' (as below) is not actually needed in ;; this case, but let's prepare for the re-edit case as well (mu4e~compose-handler 'new) (when (message-goto-to) ;; reset to-address, if needed (message-delete-line)) (message-add-header (concat "To: " to "\n")) (when (message-goto-subject) ;; reset subject, if needed (message-delete-line)) (message-add-header (concat "Subject: " subject "\n")) ;; add any other headers specified (when other-headers (message-add-header other-headers)) ;; yank message (if (bufferp yank-action) (list 'insert-buffer yank-action) yank-action) ;; try to put the user at some reasonable spot... (if (not to) (message-goto-to) (if (not subject) (message-goto-subject) (message-goto-body)))) ;; happily, we can re-use most things from message mode ;;;###autoload (define-mail-user-agent 'mu4e-user-agent 'mu4e~compose-mail 'message-send-and-exit 'message-kill-buffer 'message-send-hook) ;; Without this `mail-user-agent' cannot be set to `mu4e-user-agent' ;; through customize, as the custom type expects a function. Not ;; sure whether this function is actually ever used; if it is then ;; returning the symbol is probably the correct thing to do, as other ;; such functions suggest. (defun mu4e-user-agent () 'mu4e-user-agent) (defun mu4e~compose-browse-url-mail (url &optional ignored) "Adapter for `browse-url-mailto-function." (let* ((headers (rfc2368-parse-mailto-url url)) (to (cdr (assoc "To" headers))) (subject (cdr (assoc "Subject" headers))) (body (cdr (assoc "Body" headers)))) (mu4e~compose-mail to subject) (if body (progn (message-goto-body) (insert body) (if (not to) (message-goto-to) (if (not subject) (message-goto-subject) (message-goto-body))))))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (provide 'mu4e-compose) ;; Load mu4e completely even when this file was loaded through ;; autoload. (require 'mu4e) mu-0.9.9.5/mu4e/mu4e-proc.el0000644000175000017500000004512612122771415012257 00000000000000;; mu4e-proc.el -- part of mu4e, the mu mail user agent ;; ;; Copyright (C) 2011-2012 Dirk-Jan C. Binnema ;; Author: Dirk-Jan C. Binnema ;; Maintainer: Dirk-Jan C. Binnema ;; This file is not part of GNU Emacs. ;; ;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or ;; (at your option) any later version. ;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . ;;; Commentary: ;;; Code: (require 'mu4e-vars) (require 'mu4e-utils) (require 'mu4e-meta) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; internal vars (defvar mu4e~proc-buf nil "Buffer (string) for data received from the backend.") (defconst mu4e~proc-name " *mu4e-proc*" "Name of the server process, buffer.") (defvar mu4e~proc-process nil "The mu-server process.") ;; dealing with the length cookie that precedes expressions (defconst mu4e~cookie-pre "\376" "Each expression we get from the backend (mu server) starts with a length cookie: <`mu4e~cookie-pre'><`mu4e~cookie-post'>.") (defconst mu4e~cookie-post "\377" "Each expression we get from the backend (mu server) starts with a length cookie: <`mu4e~cookie-pre'><`mu4e~cookie-post'>.") (defconst mu4e~cookie-matcher-rx (purecopy (concat mu4e~cookie-pre "\\([[:xdigit:]]+\\)" mu4e~cookie-post)) "Regular expression matching the length cookie. Match 1 will be the length (in hex).") ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defun mu4e~proc-start () "Start the mu server process." (unless (file-executable-p mu4e-mu-binary) (mu4e-error (format "`mu4e-mu-binary' (%S) not found" mu4e-mu-binary))) (let* ((process-connection-type nil) ;; use a pipe (args '("server")) (args (append args (when mu4e-mu-home (list (concat "--muhome=" mu4e-mu-home)))))) (setq mu4e~proc-buf "") (setq mu4e~proc-process (apply 'start-process mu4e~proc-name mu4e~proc-name mu4e-mu-binary args)) ;; register a function for (:info ...) sexps (unless mu4e~proc-process (mu4e-error "Failed to start the mu4e backend")) (set-process-query-on-exit-flag mu4e~proc-process nil) (set-process-coding-system mu4e~proc-process 'binary 'utf-8-unix) (set-process-filter mu4e~proc-process 'mu4e~proc-filter) (set-process-sentinel mu4e~proc-process 'mu4e~proc-sentinel))) (defun mu4e~proc-kill () "Kill the mu server process." (let* ((buf (get-buffer mu4e~proc-name)) (proc (and (buffer-live-p buf) (get-buffer-process buf)))) (when proc (let ((delete-exited-processes t)) ;; the mu server signal handler will make it quit after 'quit' (mu4e~proc-send-command "quit")) ;; try sending SIGINT (C-c) to process, so it can exit gracefully (ignore-errors (signal-process proc 'SIGINT)))) (setq mu4e~proc-process nil mu4e~proc-buf nil)) (defun mu4e~proc-running-p () "Whether the mu process is running." (when (and mu4e~proc-process (memq (process-status mu4e~proc-process) '(run open listen connect stop))) t)) (defsubst mu4e~proc-eat-sexp-from-buf () "'Eat' the next s-expression from `mu4e~proc-buf'. Note: this is a string, not an emacs-buffer. `mu4e~proc-buf gets its contents from the mu-servers in the following form: <`mu4e~cookie-pre'><`mu4e~cookie-post'> Function returns this sexp, or nil if there was none. `mu4e~proc-buf' is updated as well, with all processed sexp data removed." (ignore-errors ;; the server may die in the middle... ;; mu4e~cookie-matcher-rx: ;; (concat mu4e~cookie-pre "\\([[:xdigit:]]+\\)]" mu4e~cookie-post) (let ((b (string-match mu4e~cookie-matcher-rx mu4e~proc-buf)) (sexp-len) (objcons)) (when b (setq sexp-len (string-to-number (match-string 1 mu4e~proc-buf) 16)) ;; does mu4e~proc-buf contain the full sexp? (when (>= (length mu4e~proc-buf) (+ sexp-len (match-end 0))) ;; clear-up start (setq mu4e~proc-buf (substring mu4e~proc-buf (match-end 0))) ;; note: we read the input in binary mode -- here, we take the part ;; that is the sexp, and convert that to utf-8, before we interpret ;; it. (setq objcons (read-from-string (decode-coding-string (substring mu4e~proc-buf 0 sexp-len) 'utf-8 t))) (when objcons (setq mu4e~proc-buf (substring mu4e~proc-buf sexp-len)) (car objcons))))))) (defsubst mu4e~proc-filter (proc str) "A process-filter for the 'mu server' output. It accumulates the strings into valid sexps by checking of the ';;eox' end-of-sexp marker, and then evaluating them. The server output is as follows: 1. an error (:error 2 :message \"unknown command\") ;; eox => this will be passed to `mu4e-error-func'. 2a. a message sexp looks something like: \( :docid 1585 :from ((\"Donald Duck\" . \"donald@example.com\")) :to ((\"Mickey Mouse\" . \"mickey@example.com\")) :subject \"Wicked stuff\" :date (20023 26572 0) :size 15165 :references (\"200208121222.g7CCMdb80690@msg.id\") :in-reply-to \"200208121222.g7CCMdb80690@msg.id\" :message-id \"foobar32423847ef23@pluto.net\" :maildir: \"/archive\" :path \"/home/mickey/Maildir/inbox/cur/1312254065_3.32282.pluto,4cd5bd4e9:2,\" :priority high :flags (new unread) :attachments ((2 \"hello.jpg\" \"image/jpeg\") (3 \"laah.mp3\" \"audio/mp3\")) :body-txt \" \" \) ;; eox => this will be passed to `mu4e-header-func'. 2b. After the list of message sexps has been returned (see 2a.), we'll receive a sexp that looks like (:found ) with n the number of messages found. The will be passed to `mu4e-found-func'. 3. a view looks like: (:view ) => the (see 2.) will be passed to `mu4e-view-func'. 4. a database update looks like: (:update :move ) => the (see 2.) will be passed to `mu4e-update-func', :move tells us whether this is a move to another maildir, or merely a flag change. 5. a remove looks like: (:remove ) => the docid will be passed to `mu4e-remove-func' 6. a compose looks like: (:compose [:original] [:include ]) `mu4e-compose-func'." (mu4e-log 'misc "* Received %d byte(s)" (length str)) (setq mu4e~proc-buf (concat mu4e~proc-buf str)) ;; update our buffer (let ((sexp (mu4e~proc-eat-sexp-from-buf))) (with-local-quit (while sexp (mu4e-log 'from-server "%S" sexp) (cond ;; a header plist can be recognized by the existence of a :date field ((plist-get sexp :date) (funcall mu4e-header-func sexp)) ;; the found sexp, we receive after getting all the headers ((plist-get sexp :found) (funcall mu4e-found-func (plist-get sexp :found))) ;; viewing a specific message ((plist-get sexp :view) (funcall mu4e-view-func (plist-get sexp :view))) ;; receive an erase message ((plist-get sexp :erase) (funcall mu4e-erase-func)) ;; receive a :sent message ((plist-get sexp :sent) (funcall mu4e-sent-func (plist-get sexp :docid) (plist-get sexp :path))) ;; received a pong message ((plist-get sexp :pong) (funcall mu4e-pong-func (plist-get sexp :props))) ;; received a contacts message ;; note: we use 'member', to match (:contacts nil) ((plist-member sexp :contacts) (funcall mu4e-contacts-func (plist-get sexp :contacts))) ;; something got moved/flags changed ((plist-get sexp :update) (funcall mu4e-update-func (plist-get sexp :update) (plist-get sexp :move))) ;; a message got removed ((plist-get sexp :remove) (funcall mu4e-remove-func (plist-get sexp :remove))) ;; start composing a new message ((plist-get sexp :compose) (funcall mu4e-compose-func (plist-get sexp :compose) (plist-get sexp :original) (plist-get sexp :include))) ;; do something with a temporary file ((plist-get sexp :temp) (funcall mu4e-temp-func (plist-get sexp :temp) ;; name of the temp file (plist-get sexp :what) ;; what to do with it ;; (pipe|emacs|open-with...) (plist-get sexp :docid) ;; docid of the message (plist-get sexp :param)));; parameter for the action ;; get some info ((plist-get sexp :info) (funcall mu4e-info-func sexp)) ;; receive an error ((plist-get sexp :error) (funcall mu4e-error-func (plist-get sexp :error) (plist-get sexp :message))) (t (mu4e-message "Unexpected data from server [%S]" sexp))) (setq sexp (mu4e~proc-eat-sexp-from-buf)))))) ;; error codes are defined in src/mu-util.h ;;(defconst mu4e-xapian-empty 19 "Error code: xapian is empty/non-existent") (defun mu4e~proc-sentinel (proc msg) "Function that will be called when the mu-server process terminates." (let ((status (process-status proc)) (code (process-exit-status proc))) (setq mu4e~proc-process nil) (setq mu4e~proc-buf "") ;; clear any half-received sexps (cond ((eq status 'signal) (cond ((eq code 9) (message nil)) ;;(message "the mu server process has been stopped")) (t (error (format "mu server process received signal %d" code))))) ((eq status 'exit) (cond ((eq code 0) (message nil)) ;; don't do anything ((eq code 11) (error "Database is locked by another process")) ((eq code 15) (error "Database needs upgrade; try `mu index --rebuild' from the command line")) ((eq code 19) (error "Database empty; try indexing some messages")) (t (error "mu server process ended with exit code %d" code)))) (t (error "Something bad happened to the mu server process"))))) (defsubst mu4e~proc-send-command (frm &rest args) "Send as command to the mu server process. Start the process if needed." (unless (mu4e~proc-running-p) (mu4e~proc-start)) (let ((cmd (apply 'format frm args))) (mu4e-log 'to-server "%s" cmd) (process-send-string mu4e~proc-process (concat cmd "\n")))) (defsubst mu4e--docid-msgid-param (docid-or-msgid) "Construct a backend parameter based on DOCID-OR-MSGID." (format (if (stringp docid-or-msgid) "msgid:\"%s\"" "docid:%d") docid-or-msgid)) (defun mu4e~proc-remove (docid) "Remove message identified by docid. The results are reporter through either (:update ... ) or (:error) sexp, which are handled my `mu4e-error-func', respectively." (mu4e~proc-send-command "remove docid:%d" docid)) (defun mu4e~proc-escape-query (query) "Escape the query QUERY for transport. In particular, backslashes and double-quotes." (let ((esc (replace-regexp-in-string "\\\\" "\\\\\\\\" query))) (replace-regexp-in-string "\"" "\\\\\"" esc))) (defun mu4e~proc-find (query threads sortfield sortdir maxnum skip-dups include-related) "Start a database query for QUERY. If THREADS is non-nil, show results in threaded fasion, SORTFIELD is a symbol describing the field to sort by (or nil); see `mu4e~headers-sortfield-choices'. If SORT is `descending', sort Z->A, if it's `ascending', sort A->Z. MAXNUM determines the maximum number of results to return, or nil for 'unlimited'. If SKIP-DUPS is non-nil, show only one of duplicate messages (see `mu4e-headers-skip-duplicates'). If INCLUDE-RELATED is non-nil, include messages related to the messages matching the search query (see `mu4e-headers-include-related'). For each result found, a function is called, depending on the kind of result. The variables `mu4e-error-func' contain the function that will be called for, resp., a message (header row) or an error." (mu4e~proc-send-command (concat "find query:\"%s\" threads:%s sortfield:%s reverse:%s maxnum:%d " "skip-dups:%s include-related:%s") (mu4e~proc-escape-query query) (if threads "true" "false") ;; sortfield is e.g. ':subject'; this removes the ':' (if (null sortfield) "nil" (substring (symbol-name sortfield) 1)) ;; TODO: use ascending/descending in backend too (it's clearer than 'reverse' (if (eq sortdir 'descending) "true" "false") (if maxnum maxnum -1) (if skip-dups "true" "false") (if include-related "true" "false"))) (defun mu4e~proc-move (docid-or-msgid &optional maildir flags) "Move message identified by DOCID-OR-MSGID. At least one of MAILDIR and FLAGS should be specified. Note, even if MAILDIR is nil, this is still a move, since a change in flags still implies a change in message filename. MAILDIR (), optionally setting FLAGS (keyword argument :flags). optionally setting FLAGS in the process. If MAILDIR is nil, message will be moved within the same maildir. MAILDIR must be a maildir, that is, the part _without_ cur/ or new/ or the root-maildir-prefix. E.g. \"/archive\". This directory must already exist. The FLAGS parameter can have the following forms: 1. a list of flags such as '(passed replied seen) 2. a string containing the one-char versions of the flags, e.g. \"PRS\" 3. a delta-string specifying the changes with +/- and the one-char flags, e.g. \"+S-N\" to set Seen and remove New. The flags are any of `deleted', `flagged', `new', `passed', `replied' `seen' or `trashed', or the corresponding \"DFNPRST\" as defined in [1]. See `mu4e-string-to-flags' and `mu4e-flags-to-string'. The server reports the results for the operation through `mu4e-update-func'. The results are reported through either (:update ... ) or (:error ) sexp, which are handled my `mu4e-update-func' and `mu4e-error-func', respectively." (unless (or maildir flags) (mu4e-error "At least one of maildir and flags must be specified")) (unless (or (not maildir) (file-exists-p (concat mu4e-maildir "/" maildir "/"))) (mu4e-error "Target dir does not exist")) (let* ((idparam (mu4e--docid-msgid-param docid-or-msgid)) (flagstr (when flags (concat " flags:" (if (stringp flags) flags (mu4e-flags-to-string flags))))) (path (when maildir (format " maildir:\"%s\"" maildir)))) (mu4e~proc-send-command "move %s %s %s" idparam (or flagstr "") (or path "")))) (defun mu4e~proc-index (path my-addresses) "Update the message database for filesystem PATH, which should point to some maildir directory structure. MY-ADDRESSES is a list of 'my' email addresses (see `mu4e-user-mail-address-list')." (let ((addrs (when my-addresses (mapconcat 'identity my-addresses ",")))) (if addrs (mu4e~proc-send-command "index path:\"%s\" my-addresses:%s" path addrs) (mu4e~proc-send-command "index path:\"%s\"" path)))) (defun mu4e~proc-add (path maildir) "Add the message at PATH to the database. With MAILDIR set to the maildir this message resides in, e.g. '/drafts'; if this works, we will receive (:info add :path :docid ) as well as (:update )." (mu4e~proc-send-command "add path:\"%s\" maildir:\"%s\"" path maildir)) (defun mu4e~proc-sent (path maildir) "Add the message at PATH to the database. With MAILDIR set to the maildir this message resides in, e.g. '/drafts'. if this works, we will receive (:info add :path :docid :fcc )." (mu4e~proc-send-command "sent path:\"%s\" maildir:\"%s\"" path maildir)) (defun mu4e~proc-compose (type &optional docid) "Start composing a message of certain TYPE (a symbol, either `forward', `reply', `edit' or `new', based on an original message (ie, replying to, forwarding, editing) with DOCID or nil for type `new'. The result will be delivered to the function registered as `mu4e-compose-func'." (unless (member type '(forward reply edit new)) (mu4e-error "Unsupported compose-type %S" type)) (unless (eq (null docid) (eq type 'new)) (mu4e-error "`new' implies docid not-nil, and vice-versa")) (mu4e~proc-send-command "compose type:%s docid:%d" (symbol-name type) docid)) (defun mu4e~proc-mkdir (path) "Create a new maildir-directory at filesystem PATH." (mu4e~proc-send-command "mkdir path:\"%s\"" path)) (defun mu4e~proc-extract (action docid partidx &optional path what param) "Extract an attachment with index PARTIDX from message with DOCID and perform ACTION on it (as symbol, either `save', `open', `temp') which mean: * save: save the part to PARAM1 (a path) (non-optional for save) * open: open the part with the default application registered for doing so * temp: save to a temporary file, then respond with (:temp :what :param )." (let ((cmd (concat "extract " (case action (save (format "action:save docid:%d index:%d path:\"%s\"" docid partidx path)) (open (format "action:open docid:%d index:%d" docid partidx)) (temp (format "action:temp docid:%d index:%d what:%s%s" docid partidx what (if param (format " param:\"%s\"" param) ""))) (otherwise (mu4e-error "Unsupported action %S" action)))))) (mu4e~proc-send-command "%s" cmd))) (defun mu4e~proc-ping () "Sends a ping to the mu server, expecting a (:pong ...) in response." (mu4e~proc-send-command "ping")) (defun mu4e~proc-contacts (personal after) "Sends the contacts command to the mu server. A (:contacts ()) is expected in response. If PERSONAL is non-nil, only get personal contacts, if AFTER is non-nil, get only contacts seen AFTER (the time_t value)." (mu4e~proc-send-command "contacts personal:%s after:%d" (if personal "true" "false") (or after 0))) (defun mu4e~proc-view (docid-or-msgid &optional images decrypt) "Get one particular message based on its DOCID-OR-MSGID. Optionally, if IMAGES is non-nil, backend will any images attached to the message, and return them as temp files. The result will be delivered to the function registered as `mu4e-message-func'." (mu4e~proc-send-command "view %s extract-images:%s extract-encrypted:%s use-agent:true" (mu4e--docid-msgid-param docid-or-msgid) (if images "true" "false") (if decrypt "true" "false"))) (defun mu4e~proc-view-path (path &optional images decrypt) "View message at PATH (keyword argument). Optionally, if IMAGES is non-nil, backend will any images attached to the message, and return them as temp files. The result will be delivered to the function registered as `mu4e-message-func'." (mu4e~proc-send-command "view path:\"%s\" extract-images:%s extract-encrypted:%s use-agent:true" path (if images "true" "false") (if decrypt "true" "false"))) (provide 'mu4e-proc) ;; End of mu4e-proc.el mu-0.9.9.5/mu4e/mu4e.texi0000664000175000017500000040412412122147627011670 00000000000000\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-.tar.gz # use the specific version $ cd mu- # 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 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 searching --------- s search e edit last query / narrow the search b search bookmark B edit bookmark before search j jump to maildir M-left previous query M-right next query marking ------- d mark for moving to the trash folder DEL,D mark for complete deletion m mark for moving to another maildir folder r mark for refiling +,- mark for flagging/unflagging u unmark message at point U unmark *all* messages % mark based on a regular expression T,t mark whole thread, subthread 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: or M-RET with point on url) e extract (save) attachment (asks for number) (or: or S-RET with point on attachment) C-u e extracts multiple attachments o open attachment (asks for number) (or: or M-RET with point on attachment) a execute some custom action on the message A execute some custom action on an attachment misc ---- w toggle line wrapping h toggle showing cited parts v show details about the cryptographic signature . show the raw message view. 'q' takes you back. C-+,C-- increase / decrease the number of headers shown H get help C-S-u update mail & reindex q,z leave the message view @end verbatim For the marking commands, please refer to @ref{Marking messages}. @node Opening and saving attachments @section Opening and saving attachments By default, @t{mu4e} uses the @t{xdg-open}-program @footnote{@url{http://portland.freedesktop.org/wiki/}} or (on MacOS) the @t{open} program for opening attachments. If you want to use another program, you do so by setting the @t{MU_PLAY_PROGRAM} environment variable to the program to be used. The default directory for extracting (saving) attachments is your home directory (@file{~/}); you can change this using the variable @code{mu4e-attachment-dir}, for example: @lisp (setq mu4e-attachment-dir "~/Downloads") @end lisp For more flexibility, @code{mu4e-attachment-dir} can also be a user-provided function. This function receives two parameters: the file-name and the mime-type@footnote{sadly, often @t{application/octet-stream} is used for the mime-type, even if a better type is available} of the attachment, either or both of which can be @t{nil}. For example: @lisp (setq mu4e-attachment-dir (lambda (fname mtype) (cond ;; docfiles go to ~/Desktop ((and fname (string-match "\\.doc$" fname)) "~/Desktop") ;; ... other cases ... (t "~/Downloads")))) ;; everything else @end lisp You can extract multiple attachments at once by prefixing the extracting command by @key{C-u}; so @kbd{C-u e} asks you for a range of attachments to extract (for example, @kbd{1 3-6 8}). The range "@samp{a}" is a shortcut for @emph{all} attachments. @node Viewing images inline @section Viewing images inline It is possible to show images inline in the message view buffer if you run @command{emacs} in GUI-mode. You can enable this by setting the variable @code{mu4e-view-show-images} to @t{t}. Since @command{emacs} does not always handle images correctly, this is not enabled by default. If you are using @command{emacs} 24 with @emph{ImageMagick}@footnote{@url{http://www.imagemagick.org}} support, make sure you call @code{imagemagick-register-types} in your configuration, so it is used for images. @lisp ;; enable inline images (setq mu4e-view-show-images t) ;; use imagemagick, if available (when (fboundp 'imagemagick-register-types) (imagemagick-register-types)) @end lisp @node Displaying rich-text messages @section Displaying rich-text messages @t{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 change this by setting @code{mu4e-view-prefer-html} to @t{t}. If there is only an html-version, or if the plain-text version is too short in comparison with the html part@footnote{this is for the case where the text-part only warns that you should use the html-version}, @t{mu4e} tries to convert the html into plain-text for display. The default way to do that is to use the @command{emacs} built-in @code{html2text} function. However, you can set the variable @code{mu4e-html2text-command} to use some external program instead. This program is expected to take html from standard input and write plain text in @t{utf-8} encoding on standard output. An example of such a program is the program that is actually @emph{called} @t{html2text}@footnote{@url{http://www.mbayer.de/html2text/}}. After installation, you can set it up with something like the following: @lisp (setq mu4e-html2text-command "html2text -utf8 -width 72") @end lisp An alternative to this is the Python @t{python-html2text} package; after installing that, you can tell @t{mu4e} to use it with something like: @lisp (setq mu4e-html2text-command "html2markdown | grep -v ' _place_holder;'") @end lisp @node MSGV Crypto @section Crypto The @t{mu4e} message view supports@footnote{Crypto-support in @t{mu4e} requires @t{mu} to have been build with crypto-support; see the @ref{FAQ}} decryption of encrypted messages, as well as verification of signatures. For signing/encrypting messages your outgoing messages, see @ref{Signing and encrypting}. Currently, only PGP/MIME is supported; PGP-inline and S/MIME are not. For all of this to work, @command{gpg-agent} must be running, and it must set the environment variable @t{GPG_AGENT_INFO}. You can check from @command{emacs} with @key{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 @command{gpg-agent}, you can do so by hand: @verbatim $ eval $(gpg-agent --daemon) @end verbatim @noindent This starts the daemon, and sets the environment variable. @subsection Decryption @anchor{Decryption} If you receive messages that are encrypted (using PGP/MIME), @t{mu4e} can try to decrypt them, base on the setting of @code{mu4e-decryption-policy}. If you set it to @t{t}, @t{mu4e} attempts to decrypt messages automatically; this is the default. If you set it to @t{nil}, @t{mu4e} @emph{won't} attempt to decrypt anything. Finally, if you set it to @t{'ask}, it asks you what to do, each time an encrypted message is encountered. When opening an encrypted message, @t{mu} consults @t{gpg-agent} to see 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. @subsection Verifying signatures @anchor{Verifying signatures} Some e-mail messages are cryptographically signed, and @t{mu4e} can check the validity of these signatures. If a message has one or more signatures, the message view shows an extra header @t{Signature:} (assuming it is part of your @code{mu4e-view-fields}), and one or more 'verdicts' of the signatures found; either @t{verified}, @t{unverified} or @t{error}. For instance: @verbatim Signature: unverified (Details) @end verbatim You can see the details of the signature verification by activating the @t{Details} or pressing @key{v}. This pops up a little window with the details of the signatures found and whether they could be verified or not. For more information, see the @command{mu-verify} manual page. @node MSGV Actions @section Actions You can perform custom functions (``actions'') on messages and their attachments. For a general discussion on how to define your own, see see @ref{Actions}. @subsection Message actions @code{mu4e-view-action} (@key{a}) lets you pick some custom action to perform on the current message. You can specify these actions using the variable @code{mu4e-view-actions}; @t{mu4e} defines a number of example actions. @subsection Attachment actions Similarly, there is @code{mu4e-view-attachment-action} (@key{A}) for actions on attachments, which you can specify with @code{mu4e-view-attachment-actions}. @t{mu4e} predefines a number of attachment-actions: @itemize @item @t{open-with} (@key{w}): open the attachment with some arbitrary program. For example, suppose you have received a message with a picture attachment; then, @kbd{A w 1 RET gimp RET} opens that attachment in @emph{The Gimp} @item @t{pipe} (@key{|}: process the attachment with some Unix shell-pipe and see the results. Suppose you receive a patch file, and would like to get an overview of the changes, using the @t{diffstat} program. You can use something like: @kbd{A | 1 RET diffstat -b RET}. @item @command{emacs} (@key{e}): open the attachment in your running @command{emacs}. For example, if you receive some text file you'd like to open in @command{emacs}: @kbd{A e 1 RET}. @end itemize These actions all work on a @emph{temporary copy} of the attachment. @node Editor view @chapter The editor view Writing e-mail messages takes place in the Editor View. @t{mu4e}'s editor view builds on top of Gnu's @t{message-mode}. Most of the @t{message-mode} functionality is available, as well some @t{mu4e}-specifics. Its major mode is @code{mu4e-compose-mode}. @menu * EV Overview:: * Useful keybindings:: * Address autocompletion:: * Compose hooks:: * Signing and encrypting:: * Queuing mail:: * Other settings:: @end menu @node EV Overview @section Overview @cartouche @verbatim From: Rupert the Monkey To: Wally the Walrus Subject: Re: Eau-qui d'eau qui? --text follows this line-- On Mon 16 Jan 2012 10:18:47 AM EET, Wally the Walrus wrote: > Hi Rupert, > > Dude - how are things? > > Later -- wally. @end verbatim @end cartouche @node Useful keybindings @section Useful keybindings @t{mu4e}'s editor view derives from Gnu's message editor and shares most of its keybindings. Here are some of the more useful ones (you can use the menu to find more): @verbatim key description --- ----------- C-c C-c send message C-c C-d save to drafts and leave C-c C-k kill the message C-c C-a attach a file (pro-tip: drag & drop works as well) (mu4e-specific) C-S-u update mail & reindex @end verbatim @node Address autocompletion @section Address autocompletion @t{mu4e} supports@footnote{@command{emacs} 23.2 or higher is required} autocompleting addresses when composing e-mail messages. @t{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 @t{mu4e-compose-complete-addresses} to @t{nil}. Emacs 24 also supports cycling through the alternatives. When there are more than @emph{5} matching addresses, they are shown in a @t{*Completions*} buffer. Once the number of matches gets below this number, one is inserted in the address field and you can cycle through the alternatives using @key{TAB}. @subsection Limiting the number of addresses If you have a lot of mail, especially from mailing lists and the like, there can be a @emph{lot} of e-mail addresses, many of which may not be very useful when auto-completing. For this reason, @t{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: @itemize @item @code{mu4e-compose-complete-only-personal} - when set to @t{t}, only consider addresses that were seen in @emph{personal} messages -- that is, messages in which one of my e-mail addresses was seen in one of the address fields. This is to exclude mailing list posts. You can define what is considered 'my e-mail address' using @code{mu4e-user-mail-address-list}, a list of e-mail address (defaults to @code{user-mail-address}, and when indexing from the command line, the @t{--my-address} parameter for @t{mu index}. @item @code{mu4e-compose-complete-only-after} - only consider e-mail addresses last seen after some date. Parameter is a string, parseable by @code{org-parse-time-string}. This excludes old e-mail addresses. The default is @t{"2010-01-01"}, i.e., only consider e-mail addresses seen since the start of 2010. @item @code{mu4e-compose-complete-ignore-address-regexp} - a regular expression to filter out other 'junk' e-mail addresses; defaults to ``@t{no-?reply}''. @end itemize @node Compose hooks @section Compose hooks If you want to change some setting, or execute some custom action before message composition starts, you can define a @emph{hook function}. @t{mu4e} offers two hooks: @itemize @item @code{mu4e-compose-pre-hook}: this hook is run @emph{before} composition starts; if you are composing a @emph{reply}, @emph{forward} a message, or @emph{edit} an existing message, the variable @code{mu4e-compose-parent-message} points to the message being replied to, forwarded or edited, and you can use @code{mu4e-message-field} to get the value of various properties (and see @ref{Message functions}). @item @code{mu4e-compose-mode-hook}: this hook is run just before composition starts, when the whole buffer has already been set up. This is a good place for editing-related settings. @code{mu4e-compose-parent-message} (see above) is also at your disposal. @end itemize @noindent Let's look at some examples. First, suppose we want to set the @t{From:}-address for a reply message based on the receiver of the original: @lisp ;; 1) messages to me@@foo.com should be replied with From:me@@foo.com ;; 2) messages to me@@bar.com should be replied with From:me@@bar.com ;; 3) all other mail should use From:me@@cuux.com (add-hook 'mu4e-compose-pre-hook (defun my-set-from-address () "Set the From address based on the To address of the original." (let ((msg mu4e-compose-parent-message)) ;; msg is shorter... (setq user-mail-address (cond ((mu4e-message-contact-field-matches msg :to "me@@foo.com") "me@@foo.com") ((mu4e-message-contact-field-matches msg :to "me@@bar.com") "me@@bar.com") (t "me@@cuux.com")))))) @end lisp Second, as mentioned, @code{mu4e-compose-mode-hook} is especially useful for editing-related settings. For example: @lisp (add-hook 'mu4e-compose-mode-hook (defun my-do-compose-stuff () "My settings for message composition." (set-fill-column 72) (flyspell-mode))) @end lisp This hook is also useful for adding headers or changing headers, since the message is fully formed when this hook runs. For example, to add a @t{Bcc:}-header, you could add something like the following, using @code{message-add-header} from @code{message-mode}. @lisp (add-hook 'mu4e-compose-mode-hook (defun my-add-bcc () "Add a Bcc: header." (save-excursion (message-add-header "Bcc: me@@example.com\n")))) @end lisp @noindent For a more general discussion about extending @t{mu4e}, see @ref{Extending mu4e}. @node Signing and encrypting @section Signing and encrypting Signing and encrypting of messages is possible using @t{emacs-mime} (@inforef{Composing,,emacs-mime}), most easily accessed through the @t{Attachments}-menu while composing a message, or with @kbd{M-x mml-secure-message-encrypt-pgp}, @kbd{M-x mml-secure-message-sign-pgp}. The support for encryption and signing is @emph{independent} of the support for their counterparts, decrypting and signature verification (as discussed in @ref{MSGV Crypto}). Even if your @t{mu4e} does have support for the latter two, you can still sign/encrypt messages. Currently, decryption and signature verification only works for PGP/MIME; inline-PGP and S/MIME are not supported. @node Queuing mail @section Queuing mail If you cannot send mail right now, for example because you are currently offline, you can @emph{queue} the mail, and send it when you have restored your internet connection. You can control this from the @ref{Main view}. To allow for queuing, you need to tell @t{smtpmail} where you want to store the queued messages. For example: @lisp (setq smtpmail-queue-mail nil ;; start in non-queuing mode smtpmail-queue-dir "~/Maildir/queue/cur") @end lisp For convenience, we put the queue directory somewhere in our normal maildir. If you want to use queued mail, you should create this directory before starting @t{mu4e}. The @command{mu mkdir} command may be useful here, so for example: @verbatim $ mu mkdir ~/Maildir/queue $ touch ~/Maildir/queue/.noindex @end verbatim The file created by the @command{touch} command tells @t{mu} to ignore this directory for indexing, which makes sense since it contains @t{smtpmail} meta-data rather than 'normal' messages; see the @t{mu-mkdir} and @t{mu-index} man pages for details. @emph{Warning}: when you switch on queued-mode, your messages @emph{won't} reach their destination until you switch it off again; so, be careful not to do this accidentally! @node Other settings @section Other settings @itemize @item If you want use @t{mu4e} as @command{emacs}' default program for sending mail, see @ref{Setting the default emacs mail program}. @item Normally, @t{mu4e} @emph{buries} the message buffer after sending; if you want to kill the buffer instead, add something like the following to your configuration: @lisp (setq message-kill-buffer-on-exit t) @end lisp @end itemize @node Searching @chapter Searching @t{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. Normally, queries return up to @code{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 @emph{all} results; you can enable this with @kbd{M-x mu4e-headers-toggle-full-search}, or by customizing the variable @code{mu4e-headers-full-search}. This applies to all search commands. You can also influence the sort order and whether threads are shown or not; see @ref{Sort order and threading}. @menu * Queries::Searching for messages * Bookmarks::Remembering queries * Maildir searches::Queries for maildirs * Other search functionality::Some more tricks @end menu @node Queries @section Queries @t{mu4e} queries are the same as the ones that @t{mu find} understands@footnote{with the caveat that command-line queries are subject to the shell's interpretation before @t{mu} sees them}. Let's look at some examples here, please refer to the @code{mu-find} and @code{mu-easy} man pages for details and even more examples. @verbatim # get all messages regarding bananas: bananas # get all messages regarding bananas from John with an attachment: from:john flag:attach bananas # get all messages with subject wombat in June 2009 subject:wombat date:20090601..20090630 # get all messages with PDF attachments in the /projects folder maildir:/projects mime:application/pdf # get all messages about Rupert in the Sent Items folder maildir:"/Sent Items" rupert # note: terms with spaces need quoting # get all important messages which are signed: flag:signed prio:high # get all messages from Jim without an attachment: from:jim AND NOT flag:attach # get all message with Alice in one of the contacts fields (to, from, cc, # bcc): contact:alice # get all unread messages where the subject mentions Angstrom: # (search is case-insensitive and accent-insensitive) subject:angstrom flag:unread # get all unread messages between Mar-2002 and Aug-2003 about some bird: date:20020301..20030831 nightingale flag:unread # get today's messages: date:today..now # get all messages we got in the last two weeks regarding emacs: date:2w..now emacs # get messages from the the Mu mailing list: mu find list:mu-discuss.googlegroups.com # get messages with a subject soccer, Socrates, society...: subject:soc* # note: the '*' wildcard can only appear as the term's rightmost character # get all mails with attachment with filenames starting with 'pic': file:pic* # note: the '*' wildcard can only appear as the term's rightmost character # get all messages with PDF attachments: mime:application/pdf # get all messages with image attachments: mime:image/* # note: the '*' wildcard can only appear as the term's @emph{rightmost} # character @end verbatim @node Bookmarks @section Bookmarks If you have queries that you use often, you may want to store them as @emph{bookmarks}. Bookmark searches are available in the main view @ref{Main view}, header view @xref{Headers view}, and message view @xref{Message view}, using (by default) the key @key{b} (@kbd{M-x mu4e-search-bookmark}), or @key{B} (@kbd{M-x mu4e-search-bookmark-edit}) which lets you edit the bookmark first. @subsection Setting up bookmarks @t{mu4e} provides a number of default bookmarks. Their definition is instructive: @lisp (defvar mu4e-bookmarks '( ("flag:unread AND NOT flag:trashed" "Unread messages" ?u) ("date:today..now" "Today's messages" ?t) ("date:7d..now" "Last 7 days" ?w) ("mime:image/*" "Messages with images" ?p)) "A list of pre-defined queries; these show up in the main screen. Each of the list elements is a three-element list of the form (QUERY DESCRIPTION KEY), where QUERY is a string with a mu query, DESCRIPTION is a short description of the query (this shows up in the UI), and KEY is a shortcut key for the query.") @end lisp You can replace these or add your own items, by putting in your configuration (@file{~/.emacs}) something like: @lisp (add-to-list 'mu4e-bookmarks '("size:5M..500M" "Big messages" ?b)) @end lisp This prepends your bookmark to the list, and assigns the key @key{b} to it. If you want to @emph{append} your bookmark, you can use @code{t} as the third argument to @code{add-to-list}. In the various @t{mu4e} views, pressing @key{b} lists all the bookmarks defined in the echo area, with the shortcut key highlighted. So, to invoke the bookmark we just defined (to get the list of "Big Messages"), all you need to type is @kbd{bb}. @subsection Editing bookmarks before searching There is also @kbd{M-x mu4e-headers-search-bookmark-edit} (key @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 @samp{"date:today..now AND "}@footnote{Not a valid search query by itself}, which limits any result to today's messages. @node Maildir searches @section Maildir searches Maildir searches are quite similar to bookmark searches (see @ref{Bookmarks}), with the difference being that the target is always a maildir -- maildir queries provide a 'traditional' folder-like interface to a search-based e-mail client. By default, maildir searches are available in the @ref{Main view}, @ref{Headers view}, and @ref{Message view}, with the key @key{j} (@code{mu4e-jump-to-maildir}). @subsection Setting up maildir shortcuts You can search for maildirs like can for any other messsage property (e.g. with a query like @t{maildir:/myfolder}), but since it is so common, @t{mu4e} offers a shortcut for this. For this to work, you need to set the variable @code{mu4e-maildir-shortcuts} to the list of maildirs you want to have quick access to, for example: @lisp (setq mu4e-maildir-shortcuts '( ("/inbox" . ?i) ("/archive" . ?a) ("/lists" . ?l) ("/work" . ?w) ("/sent" . ?s)) @end lisp This sets @key{i} as a shortcut for the @t{/inbox} folder -- effectively a query @t{maildir:/inbox}. There is a special shortcut @key{o} or @key{/} for @emph{other} (so don't use those for your own shortcuts!), which allows you to choose from @emph{all} maildirs that you have. There is support for autocompletion; note that the list of maildirs is determined when @t{mu4e} starts; if there are changes in the maildirs while @t{mu4e} is running, you need to restart @t{mu4e}. Each of the folder names is relative to your top-level maildir directory; so if you keep your mail in @file{~/Maildir}, @file{/inbox} would refer to @file{~/Maildir/inbox}. With these shortcuts, you can jump around your maildirs (folders) very quickly - for example, getting to the @t{/lists} folder only requires you to type @kbd{jl}, then change to @t{/work} with @kbd{jw}. The very same shortcuts are used by @kbd{M-x mu4e-mark-for-move} (default shortcut @key{m}); so, for example, if you want to move a message the @t{/archive} folder, you can do so by typing @kbd{ma}. @node Other search functionality @section Other search functionality @subsection Navigating through search queries You can navigate through previous/next queries using @code{mu4e-headers-query-prev} and @code{mu4e-headers-query-next}, which are bound to @key{M-left} and @key{M-right}, similar to what some web browsers do. @t{mu4e} tries to be smart and not record duplicate queries. Also, the number of queries remembered has a fixed limit, so @t{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 @kbd{M-x mu4e-headers-forget-queries}. @subsection 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 the some mailing list, perhaps by jumping to a maildir (@kbd{M-x mu4e-headers-jump-to-maildir}, @key{j}) or because you followed some bookmark (@kbd{M-x mu4e-headers-search-bookmark}, @key{b}). Now, you want to narrow things down to only those messages that have attachments. 1 This is when @kbd{M-x mu4e-headers-search-narrow} (@key{/}) 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. @key{\} takes you back to the previous query, so, effectively 'widens' the search. Technically, narrowing the results of query @t{x} with expression @t{y} implies doing a search @t{(x) AND y}. Note, messages that were not in your in your original search results because of @code{mu4e-headers-results-limit}, may show up in the narrowed query. @subsection Including related messages @anchor{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 thread are included in the results, just like e.g. Gmail does it. You can enable this behavior by setting @code{mu4e-headers-include-related} to @code{t}, and you can toggle between including/not-including with @key{W}. @subsection Skipping duplicates @anchor{Skipping duplicates} Another useful features is skipping 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 in the combination of Gmail and @t{offlineimap}, since that is the way the labels / virtual folders in Gmail are represented. You can enable skipping duplicates by setting @code{mu4e-headers-skip-duplicates} to @code{t}, and you can toggle between the skipping/not skipping with @key{V}. Note, messages are considered duplicates when they have the same @t{Message-Id}. @node Marking @chapter Marking In @t{mu4e}, the common way to do things with messages is a two-step process - first you @emph{mark} them for a certain action, then you @emph{execute} (@key{x}) those marks. This is similar to the way @t{dired} operates. Marking can happen in both the @ref{Headers view} and the @ref{Message view}. @menu * Selecting messages for marking:: * What to mark for:: * Executing the marks:: * Leaving the headers buffer:: * Built-in marking functions:: * Custom mark functions:: @end menu @node Selecting messages for marking @section Selecting messages for marking There are multiple ways to mark messages: @itemize @item @emph{message at point}: you can put a mark on the message-at-point in either the @ref{Headers view} or @ref{Message view} @item @emph{region}: you can put a mark on all messages in the current region (selection) in the @ref{Headers view} @item @emph{pattern}: you can put a mark on all messages in the @ref{Headers view} matching a certain pattern with @kbd{M-x mu4e-headers-mark-pattern} (@key{%}) @item @emph{thread/subthread}: You can put a mark on all the messages in the thread/subthread at point with @kbd{M-x mu4e-headers-mark-thread} and @kbd{M-x mu4e-headers-mark-subthread}, respectively @end itemize @node What to mark for @section What to mark for @t{mu4e} supports a number of different marks - i.e., different actions to apply to messages: @cartouche @verbatim mark for/as | keybinding | description --------------+-------------+-------------------------- 'something' | | mark now, decide later delete | D, | 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 unflag | - | remove 'flagged' mark unmark | u | remove mark at point unmark all | U | remove all marks unread | ? | marks as unread @end verbatim @end cartouche After marking a message for something, the left-most columns in the headers view show some information to indicate what it is marked. This is informative, but if you mark many (thousands) messages, this slows things down significantly@footnote{this uses an @command{emacs} feature called @emph{overlays}, which are slow when used a lot in a buffer}. For this reason, you can disable this by setting @code{mu4e-headers-show-target} to @code{nil}. @t{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@footnote{This kind of 'deferred marking' is similar to the facility in @t{midnight commander} (@url{http://www.midnight-commander.org/}) and the like, and uses the same key binding (@key{insert}).} , using @kbd{M-x mu4e-mark-resolve-deferred-marks} (@key{#}). Alternatively, @t{mu4e} will ask you when you execute the marks (@key{x}). @node Executing the marks @section Executing the marks After you have marked some messages, you can execute them with @key{x} (@kbd{M-x mu4e-mark-execute-all}). @node Leaving the headers buffer @section Leaving the headers buffer When you quit or update a headers buffer that has marked messages (for example, by doing a new search), @t{mu4e} asks you what to do with them, depending on the value of the variable @code{mu4e-headers-leave-behavior} -- see its documentation. @node Built-in marking functions @section Built-in marking functions Some examples of @t{mu4e}'s built-in marking functions. @itemize @item @emph{Mark the message at point for trashing}: press @key{d} @item @emph{Mark all messages in the buffer as unread}: press @kbd{C-x h o} @item @emph{Delete the messages in the current thread}: press @kbd{T D} @item @emph{Mark messages with a subject matching ``hello'' for flagging}: press @kbd{% s hello RET}. @end itemize @node Custom mark functions @section Custom mark functions Sometimes, the built-in functions to mark messages may not be sufficient for your needs. For this, @t{mu4e} offers an easy way to define your own custom mark functions. You can choose one of the custom marker functions by pressing @key{&} in the @ref{Headers view} and @ref{Message view}. Custom mark functions are to be appended to the list @code{mu4e-headers-custom-markers}. Each of the elements of this list ('markers') is a list with two or three elements: @enumerate @item The name of the marker - a short string describing this marker. The first character of this string determines its shortcut, so these should be unique. If necessary, simply prefix the name with a unique character. @item a predicate function, taking two arguments @var{msg} and @var{param}. @var{msg} is the message plist (see @ref{Message functions} and @var{param} is a parameter provided by the third of the marker elements (see the next item). The predicate function should return non-@t{nil} if the message matches. @item (optionally) a function that is evaluated once, and the result is passed as a parameter to the predicate function. This is useful when user-input is needed. @end enumerate Let's look at an example: suppose we want to match all messages that have more than @emph{n} recipients -- we could do this with the following recipe: @lisp (add-to-list 'mu4e-headers-custom-markers '("More than n recipients" (lambda (msg n) (> (+ (length (mu4e-message-field msg :to)) (length (mu4e-message-field msg :cc))) n)) (lambda () (read-number "Match messages with more recipients than: "))) t) @end lisp After evaluating this expression, you can use it by pressing @key{&} in the headers buffer to select a custom marker function, and then @key{M} to choose this particular one (@t{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 @code{mu4e-headers-custom-markers}; see @file{mu4e-headers.el} and see @ref{Extending mu4e} for general information about writing your own functions. @node Dynamic folders @chapter Dynamic folders In @ref{Folders}, we explained how you can set up @t{mu4e}'s special folders: @lisp (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 @end lisp 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 @emph{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 @t{mu4e} and writing your own functions, see @ref{Extending mu4e}. @menu * Smart refiling:: Automatically choose the target folder * Other dynamic folders:: Flexible folders for sent, trash, drafts @end menu @node Smart refiling @section 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 (@code{mu4e-refile-folder}) to a function that returns the actual refiling folder for the particular message. An example should clarify this: @lisp (setq mu4e-refile-folder (lambda (msg) (cond ;; messages to the mu mailing list go to the /mu folder ((mu4e-message-contact-field-matches msg :to "mu-discuss@@googlegroups.com") "/mu") ;; messages sent directly to me go to /archive ;; also `mu4e-user-mail-address-p' can be used ((mu4e-message-contact-field-matches msg :to "me@@example.com") "/private") ;; messages with football or soccer in the subject go to /football ((string-match "football\\|soccer" (mu4e-message-field msg :subject)) "/football") ;; messages sent by me go to the sent folder ((find-if (lambda (addr) (mu4e-message-contact-field-matches msg :from addr)) mu4e-user-mail-address-list) mu4e-sent-folder) ;; everything else goes to /archive ;; important to have a catch-all at the end! (t "/archive")))) @end lisp @noindent This can be very powerful; you can select some messages in the headers view, then press @key{r}, and have them all marked for refiling to their particular folders. Some notes: @itemize @item We set @code{mu4e-refile-folder} to an anonymous (@t{lambda}) function. This function takes one argument, a message plist@footnote{a property list describing a message}. The plist corresponds to the message at point. See @ref{Message functions} for a discussion on how to deal with them. @item In our function, we use a @t{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 @emph{some} folder. @item We use the convenience function @code{mu4e-message-contact-field-matches}, which evaluates to @code{t} if any of the names or e-mail addresses in a contact field (in this case, the @t{To:}-field) matches the regular expression. @end itemize @node Other dynamic folders @section 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 @emph{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 @t{nil}. Let's look at an example. Suppose you want a different trash folder for work-email. You can achieve this with something like: @lisp (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.com")) "/trash-work" "/trash"))) @end lisp @noindent Good to remember: @itemize @item The @var{msg} parameter you receive in the function refers to the @emph{original message}, that is, the message being replied to or forwarded. When re-editing a message, it refers to the message being edited. When you compose a totally new message, the @var{msg} parameter is @code{nil}. @item When re-editing messages, the value of @code{mu4e-drafts-folder} is ignored. @end itemize @node Actions @chapter Actions @t{mu4e} lets you define custom actions for messages in the @ref{Headers view} and for both messages and attachments in the @ref{Message view}. Custom actions allow you to easily extend @t{mu4e} for specific needs -- for example, marking messages as spam in a spam filter or applying an attachment with a source code patch. You can invoke the actions with key @key{a} for actions on messages, and key @key{A} for actions on attachments. For general information extending @t{mu4e} and writing your own functions, see @ref{Extending mu4e}. @menu * Defining actions:: * Adding an action in the headers view:: * Adding an action in the message view:: * Adding an attachment action:: * More example actions:: @end menu @node Defining actions @section 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 @var{msg} parameter, which corresponds to the message at point. Something like: @lisp (defun my-action-func (msg) "Describe my message function." ;; do stuff ) @end lisp @noindent Messages that operate on attachments receive a @var{msg} parameter, which corresponds to the message at point, and an @var{attachment-num}, which is the number of the attachment as seen in the message view. An attachment function looks like: @lisp (defun my-attachment-action-func (msg attachment-num) "Describe my attachment function." ;; do stuff ) @end lisp @noindent After you have defined your function, you can add it to the list of actions@footnote{Instead of defining the functions separately, you can obviously also add a @code{lambda}-function directly to the list; however, separate functions are easier to change}, either @code{mu4e-headers-actions}, @code{mu4e-view-actions} or @code{mu4e-view-attachment-actions}. The format@footnote{Note, the format of the actions has changed since version 0.9.8.4, and you must change your configuration to use the new format; @t{mu4e} warns you when you are using the old format.} of each action is a cons-cell, @code{(DESCRIPTION . VALUE)}; see below for some examples. If your shortcut is not also the first character of the description, simply prefix the description with that character. Let's look at some examples. @node Adding an action in the headers view @section Adding an action in the headers view Suppose we want to inspect the number of recipients for a message in the @ref{Headers view}. We add the following to our configuration: @lisp (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) @end lisp After evaluating this, @kbd{a N} in the headers view shows the number of recipients for the message at point. @node Adding an action in the message view @section Adding an action in the message view As another example, suppose we would like to search for messages by the sender of the message at point: @lisp (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) @end lisp @indent If you wonder why we use @code{cdar}, remember that the @t{From:}-field is a list of @code{(NAME . EMAIL)} cells; thus, @code{cdar} gets us the e-mail address of the first in the list. @t{From:}-fields rarely contain multiple cells. @node Adding an attachment action @section Adding an attachment action Finally, let's define an attachment action. As mentioned, attachment-action functions receive @emph{2} arguments, the message and the attachment number to use. The following example action counts the number of lines in an attachment, and defines @key{n} as its shortcut key (the @key{n} is prefixed to the description). @lisp (defun count-lines-in-attachment (msg attachnum) "Count the number of lines in an attachment." (mu4e-view-pipe-attachment msg attachnum "wc -l")) ;; defining 'n' as the shortcut (add-to-list 'mu4e-view-attachment-actions '("ncount lines" . count-lines-in-attachment) t) @end lisp @node More example actions @section More example actions @t{mu4e} includes a number of example actions in the file @file{mu4e-actions.el} in the source distribution (see @kbd{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. @node Extending mu4e @chapter Extending mu4e @t{mu4e} is designed to be easily extendible - that is, write your own emacs-lisp to make @t{mu4e} behave exactly as you want. Here, we provide some guidelines for doing so. @menu * Extension points:: * Available functions:: * Message functions:: * Utility functions:: @end menu @node Extension points @section Extension points There are a number of places where @t{mu4e} lets you plug in your own functions: @itemize @item Using message-specific folders for drafts, trash, sent messages and refiling, based on a function - see @ref{Dynamic folders} @item Using an attachment-specific download-directory - see the variable @code{mu4e-attachment-dir}. @item Apply a function to a message in the headers view - see @ref{Adding an action in the headers view} @item Apply a function to a message in the message view - see @ref{Adding an action in the message view} @item Apply a function to to an attachment - see @ref{Adding an attachment action} @item Custom function to mark certain messages - see @ref{Custom mark functions} @item Using various @emph{mode}-hooks, @code{mu4e-compose-pre-hook} (see @ref{Compose hooks}), @code{mu4e-index-updated-hook} (see @ref{FAQ}) @end itemize @noindent You can also write your own functions without using the above. If you want to do so, key useful functions are @code{mu4e-message-at-point} (see below), @code{mu4e-headers-for-each} (to iterate over all headers, see its docstring) and @code{mu4e-view-for-each-part} (to iterate over all parts/attachments, see its docstring). @node Available functions @section Available functions The whole of @t{mu4e} consists of hundreds of elisp functions. However, the majority of those are for @emph{internal} use only; you can recognize them easily, because they all start with @code{mu4e~}. These function make all kinds of assumptions, and they are subject to change, and should therefore @emph{not} be used. The same is true for @emph{variables} that start with @code{mu4e~}; don't touch them. Let me repeat that: @verbatim Do not use mu4e~... functions or variables! @end verbatim @noindent In addition, you should use functions in the right context; functions that start with @t{mu4e-view-} are only applicable to the message view, while functions starting with @t{mu4e-headers-} are only applicable to the headers view. Functions without such prefixes are applicable everywhere. @node Message functions @section Message functions Many functions in @t{mu4e} deal with message plist (property lists). They contain information about messages, such as sender and recipient, subject, date and so on. To deal with these plists, there are a number of @code{mu4e-message-} functions (in @file{mu4e-message.el}), such as @code{mu4e-message-field} and @code{mu4e-message-at-point} For example, to get the subject of the message at point, in either the headers view or the message view, you could write: @lisp (mu4e-message-field (mu4e-message-at-point) :subject) @end lisp @noindent Note that: @itemize @item The contact fields (To, From, Cc, Bcc) are lists of cons-pairs @code{(name . email)}; @code{name} may be @code{nil}. So, for example: @lisp (mu4e-message-field some-msg :to) ;; => (("Jack" . "jack@@example.com") (nil . "foo@@example.com")) @end lisp 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 @code{mu4e-message-contact-field-matches} to make this easy. @item The message body is only available in the message view, not in the headers view. @end itemize @node Utility functions @section Utility functions @file{mu4e-utils} contains a number of utility functions; we list a few here; see their docstrings for the details: @itemize @item @code{mu4e-read-option}: read one option from a list. For example: @lisp (mu4e-read-option "Choose an animal: " '(("Monkey" . monkey) ("Gnu" . gnu) ("xMoose" . moose))) @end lisp The user is presented with: @example Choose an animal: [M]onkey, [G]nu, [x]Moose @end example @item @code{mu4e-ask-maildir}: ask for a maildir; try one of the shortcuts (@code{mu4e-maildir-shortcuts}), or the full set of available maildirs. @item @code{mu4e-running-p}: return @code{t} if the @t{mu4e} process is running, @code{nil} otherwise. @item @code{(mu4e-user-mail-address-p addr)}: return @code{t} if @var{addr} is one of the user's e-mail addresses (as per @code{mu4e-user-mail-address-list}). @item @code{mu4e-log} logs to the @t{mu4e} debugging log if it is enabled; see @code{mu4e-toggle-logging}. @item @code{mu4e-message}, @code{mu4e-warning}, @code{mu4e-error} are the @t{mu4e} equivalents of the normal @t{elisp} @code{message}, @code{user-error}@footnote{@code{user-error} only appears in @command{emacs} 24.2 and later; in older versions it falls back to @code{error}} and @code{error} functions. @end itemize @node Interaction with other tools @appendix Interaction with other tools In this chapter we discuss some ways in ways in which @t{mu4e} can cooperate with other tools. @menu * Setting the default emacs mail program:: * Creating org-mode links:: * Rich-text messages with org-mode:: * Maintaining an address-book with org-contacts:: * Getting new mail notifications with Sauron:: * Speedbar support:: * Citations with mu-cite:: * Attaching files with dired:: @end menu @node Setting the default emacs mail program @section Setting the default @command{emacs} mail program @command{emacs} allows you to select an e-mail program as the default program it uses when you press @key{C-x m} (@code{compose-mail}), call @code{report-emacs-bug} and so on. If you want to use @t{mu4e} for this, you do so by adding the following to your configuration: @lisp (setq mail-user-agent 'mu4e-user-agent) @end lisp @noindent At the present time, support is experimental. @node Creating org-mode links @section Creating @t{org-mode} links It can be useful to include links to e-mail messages or even search queries in your org-mode files. @t{mu4e} supports this with the @t{org-mu4e} module; you can set it up by adding it to your configuration: @lisp (require 'org-mu4e) @end lisp @noindent After this, you can use the normal @t{org-mode} mechanisms to store links: @kbd{M-x org-store-link} stores a link to a particular message when you're in @ref{Message view}, and a link to a query when you are in @ref{Headers view}. You can insert this link later with @kbd{M-x org-insert-link}. From @t{org-mode}, you can go to the query or message the link points to with either @kbd{M-x org-agenda-open-link} in agenda buffers, or @kbd{M-x org-open-at-point} elsewhere - both typically bound to @kbd{C-c C-o}. @node Rich-text messages with org-mode @section Rich-text messages with @t{org-mode} @t{org-mode} has some nice facilities for editing texts -- creating lists, tables, mathematical formulae etc. In addition, it can convert them to @abbr{HTML}. An @emph{experimental} @t{mu4e} feature lets you edit your messages with @t{org-mode}, and (optionally) convert them on the fly (when sending them) to messages with an HTML-part containing the rich-text version of your messages. To enable this, make sure you have @lisp (require 'org-mu4e) @end lisp somewhere in your setup, and also make sure that the @t{dvipng} program is available in your path. Then, when composing a message, you can use @kbd{M-x org-mu4e-compose-org-mode} to enable this mode. @code{org-mu4e-compose-org-mode} behaves more or less like a minor-mode. When it is active, editing the message body takes place in @t{org-mode}, while editing the headers uses the normal message editing mode, @code{mu4e-compose-mode}. If you want to automatically convert the @t{org-mode} markup to rich-text when sending messages, you need to set the variable @code{org-mu4e-convert-to-html} to non-nil: @lisp (setq org-mu4e-convert-to-html t) @end lisp @noindent To send the message or execute other @code{mu4e-compose-mode}/@code{message-mode} commands on the message, first press @key{M-m}. Thus, for example, to send the message, you'd press @key{M-m C-c}. The code for doing the conversion is based on Eric Schultze's @t{org-mime}@footnote{@url{http://orgmode.org/worg/org-contrib/org-mime.php}}, but has been customized for use with @t{mu4e}. In particular, the mode-switching between @code{org-mode} and @code{mu4e-compose-mode} is @t{mu4e-specific}. @subsection Some caveats It is better @emph{not} to put @t{org-mu4e-compose-org-mode} in a mode-hook for @t{mu4e-compose-mode}, since that makes it impossible to shut it off again for the particular message@footnote{This is because @t{mu4e-compose-mode} in invoked again internally when switching, which re-triggers the hook-function.}. In addition, currently the rich-text code does not work well with the @abbr{MIME}-functionality, such as adding attachments or signing/encrypting messages. If you need any of that, it's better to use plain-text messages. @node Maintaining an address-book with org-contacts @section Maintaining an address-book with org-contacts Note, @t{mu4e} supports built-in address autocompletion; @ref{Address autocompletion}, and that is the recommended way to do this. However, it is also possible to manage your addresses with @t{org-mode}, using @t{org-contacts}@footnote{@url{http://julien.danjou.info/software/org-contacts.el}}. @t{mu4e-actions} defines a useful action (@ref{Actions}) for adding a contact based on the @t{From:}-address in the message at point. To enable this, add to your configuration something like: @lisp (setq mu4e-org-contacts-file ) (add-to-list 'mu4e-headers-actions '("org-contact-add" . mu4e-action-add-org-contact) t) (add-to-list 'mu4e-view-actions '("org-contact-add" . mu4e-action-add-org-contact) t) @end lisp @noindent After this, you should be able to add contacts using @key{a o} in the headers view and the message view, using the @t{org-capture} mechanism. Note, the shortcut character @key{o} is due to the first character of @t{org-contact-add}. @node Getting new mail notifications with Sauron @section Getting new mail notifications with Sauron The @command{emacs}-package @t{sauron}@footnote{Sauron can be found at @url{https://github.com/djcb/sauron}, or in the Marmalade package-repository at @url{http://http://marmalade-repo.org/}} (by the same author) can be used to get notifications about new mails. If you put something like the below script in your @t{crontab} (or have some other way of having it execute every @emph{n} minutes) you receive notifications in the sauron-buffer when new messages arrive. @verbatim #!/bin/sh # put the path to your Inbox folder here CHECKDIR="/home/$LOGNAME/Maildir/Inbox" sauron-msg () { DBUS_COOKIE="/home/$LOGNAME/.sauron-dbus" if test "x$DBUS_SESSION_BUS_ADDRESS" = "x"; then if test -e $DBUS_COOKIE; then export DBUS_SESSION_BUS_ADDRESS="`cat $DBUS_COOKIE`" fi fi if test -n "x$DBUS_SESSION_BUS_ADDRESS"; then dbus-send --session \ --dest="org.gnu.Emacs" \ --type=method_call \ "/org/gnu/Emacs/Sauron" \ "org.gnu.Emacs.Sauron.AddMsgEvent" \ string:shell uint32:3 string:"$1" fi } # # -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`; do subject=`$MU view $f | grep '^Subject:' | sed 's/^Subject://'` sauron-msg "mail: $subject" done @end verbatim @noindent You might want to put: @lisp (setq sauron-dbus-cookie t) @end lisp @noindent in your setup, to allow the script to find the D-Bus session bus, even when running outside its session. @node Speedbar support @section Speedbar support @code{speedbar} is an @command{emacs}-extension that shows navigational information for an @command{emacs} buffer in a separate frame. Using @code{mu4e-speedbar}, @t{mu4e} lists your bookmarks and maildir folders and allows for one-click access to them. @t{mu4e} loads @t{mu4e-speedbar} automatically; all you need to do to activate it is @kbd{M-x speedbar}. Then, when then switching to the @ref{Main view}, the speedbar-frame is updated with your bookmarks and maildirs. For speed reasons, the list of maildirs is determined when @t{mu4e} starts; if the list of maildirs changes while @t{mu4e} is running, you need to restart @t{mu4e} to have those changes reflected in the speedbar and in other places that use this list, such as auto-completion when jumping to a maildir. @code{mu4e-speedbar} was contributed by @emph{Antono Vasiljev}. @node Citations with mu-cite @section Citations with @t{mu-cite} @t{mu-cite}@footnote{Note, despite its name, @t{mu-cite} is a project unconnected to @t{mu}/@t{mu4e}} is a package to control the way message citations look like (i.e., the message you responded to when you reply to them or forward them), with its latest version available at @url{http://www.jpl.org/elips/mu/}. After installing @t{mu-cite}, you can use something like the following to make it work with @t{mu4e}: @lisp (require 'mu-cite) (setq message-cite-function 'mu-cite-original) (setq mu-cite-top-format '("On " date ", " from " wrote:\n\n")) (setq mu-cite-prefix-format '(" > "))) @end lisp @node Attaching files with dired @section Attaching files with @t{dired} It is possible to attach files to @t{mu4e} messages using @t{dired} (@inforef{Dired,,emacs}), using the following steps (based on a post on the @t{mu-discuss} mailing list by @emph{Stephen Eglen}). To prepare for this, you need a special version of the @code{gnus-dired-mail-buffers} function so it understands @t{mu4e} buffers as well; so put in your configuration: @lisp (require 'gnus-dired) ;; make the `gnus-dired-mail-buffers' function also work on ;; message-mode derived modes, such as mu4e-compose-mode (defun gnus-dired-mail-buffers () "Return a list of active message buffers." (let (buffers) (save-current-buffer (dolist (buffer (buffer-list t)) (set-buffer buffer) (when (and (derived-mode-p 'message-mode) (null message-sent-message-via)) (push (buffer-name buffer) buffers)))) (nreverse buffers))) (setq gnus-dired-mail-mode 'mu4e-user-agent) (add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode) @end lisp Then, mark the file(s) in @t{dired} you would like to attach and press @t{C-c RET C-a}, and you'll be asked whether to attach them to an existing message, or create a new one. @node Example configurations @appendix Example configurations In this chapter, we show some example configurations. While it is very useful to see some working settings, we'd like to warn against blindly copying such things. @menu * Minimal configuration:: * Longer configuration:: * Gmail configuration:: * Some other useful settings:: @end menu @node Minimal configuration @section Minimal configuration An (almost) minimal configuration for @t{mu4e} might look like this - as you see most is commented-out. @lisp ;; example configuration for mu4e ;; make sure mu4e is in your load-path (require 'mu4e) ;; Only needed if your maildir is _not_ ~/Maildir ;;(setq mu4e-maildir "/home/user/Maildir") ;; these must start with a "/", and must exist ;; (i.e.. /home/user/Maildir/sent must exist) ;; you use e.g. 'mu mkdir' to make the Maildirs if they don't ;; already exist ;; below are the defaults; if they do not exist yet, mu4e offers to ;; create them. they can also functions; see their docstrings. ;; (setq mu4e-sent-folder "/sent") ;; (setq mu4e-drafts-folder "/drafts") ;; (setq mu4e-trash-folder "/trash") ;; smtp mail setting; these are the same that `gnus' uses. (setq message-send-mail-function 'smtpmail-send-it smtpmail-default-smtp-server "smtp.example.com" smtpmail-smtp-server "smtp.example.com" smtpmail-local-domain "example.com") @end lisp @node Longer configuration @section Longer configuration A somewhat longer configuration, showing some more things that you can customize. @lisp ;; example configuration for mu4e (require 'mu4e) ;; path to our Maildir directory (setq mu4e-maildir "/home/user/Maildir") ;; the next are relative to `mu4e-maildir' ;; instead of strings, they can be functions too, see ;; their docstring or the chapter 'Dynamic folders' (setq mu4e-sent-folder "/sent" mu4e-drafts-folder "/drafts" mu4e-trash-folder "/trash") ;; the maildirs you use frequently; access them with 'j' ('jump') (setq mu4e-maildir-shortcuts '(("/archive" . ?a) ("/inbox" . ?i) ("/work" . ?w) ("/sent" . ?s))) ;; a list of user's e-mail addresses (setq mu4e-user-mail-address-list '("foo@@bar.com" "cuux@@example.com") ;; when you want to use some external command for text->html ;; conversion, e.g. the 'html2text' program ;; (setq mu4e-html2text-command "html2text") ;; the headers to show in the headers list -- a pair of 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) (:flags . 6) (:from . 22) (:subject . nil))) ;; program to get mail; alternatives are 'fetchmail', 'getmail' ;; isync or your own shellscript. called when 'U' is pressed in ;; main view. ;; 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-reply-to-address "foo@@bar.com" user-mail-address "foo@@bar.com" user-full-name "Foo X. Bar") ;; include in message with C-c C-w (setq message-signature "Foo X. Bar\nhttp://www.example.com\n") ;; smtp mail setting (setq message-send-mail-function 'smtpmail-send-it smtpmail-default-smtp-server "smtp.example.com" smtpmail-smtp-server ""smtp.example.com" smtpmail-local-domain "example.com" ;; if you need offline mode, set these -- and create the queue dir ;; with 'mu mkdir', i.e.. mu mkdir /home/user/Maildir/queue smtpmail-queue-mail nil smtpmail-queue-dir "/home/user/Maildir/queue/cur") ;; don't keep message buffers around (setq message-kill-buffer-on-exit t) @end lisp @node Gmail configuration @section Gmail configuration @emph{Gmail} is a popular e-mail provider; let's see how we can make it work with @t{mu4e}. Since we are using @abbr{IMAP}, you must enable that in the Gmail web interface (in the settings, under the ``Forwarding and POP/IMAP''-tab). Gmail users may also be interested in @ref{Including related messages, skipping duplicates}. @subsection Setting up offlineimap First of all, we need a program to get the e-mail from Gmail to our local machine; for this we use @t{offlineimap}; on Debian (and derivatives like Ubuntu), this is as easy as: @verbatim $ sudo apt-get install offlineimap @end verbatim while on Fedora (and similar) you need: @verbatim $ sudo yum install offlineimap @end verbatim Then, we can configure @t{offlineimap} by editing @file{~/.offlineimaprc}: @verbatim [general] accounts = Gmail maxsyncaccounts = 3 [Account Gmail] localrepository = Local remoterepository = Remote [Repository Local] type = Maildir localfolders = ~/Maildir [Repository Remote] type = IMAP remotehost = imap.gmail.com remoteuser = USERNAME@gmail.com remotepass = PASSWORD ssl = yes maxconnections = 1 realdelete = no @end verbatim Obviously, you need to replace @t{USERNAME} and @t{PASSWORD} with your actual Gmail username and password. After this, you should be able to download your mail: @verbatim $ offlineimap OfflineIMAP 6.3.4 Copyright 2002-2011 John Goerzen & contributors. Licensed under the GNU GPL v2+ (v2 or any later version). Account sync Gmail: ***** Processing account Gmail Copying folder structure from IMAP to Maildir Establishing connection to imap.gmail.com:993. Folder sync [Gmail]: Syncing INBOX: IMAP -> Maildir Syncing [Gmail]/All Mail: IMAP -> Maildir Syncing [Gmail]/Drafts: IMAP -> Maildir Syncing [Gmail]/Sent Mail: IMAP -> Maildir Syncing [Gmail]/Spam: IMAP -> Maildir Syncing [Gmail]/Starred: IMAP -> Maildir Syncing [Gmail]/Trash: IMAP -> Maildir Account sync Gmail: ***** Finished processing account Gmail @end verbatim We can now run @command{mu} to make sure things work: @verbatim $ mu index mu: indexing messages under /home/foo/Maildir [/home/foo/.mu/xapian] | processing mail; processed: 520; updated/new: 520, cleaned-up: 0 mu: elapsed: 3 second(s), ~ 173 msg/s mu: cleaning up messages [/home/foo/.mu/xapian] / processing mail; processed: 520; updated/new: 0, cleaned-up: 0 mu: elapsed: 0 second(s) @end verbatim We can run both the @t{offlineimap} and the @t{mu index} from within @t{mu4e}, but running it from the command line makes it a bit easier to troubleshoot as we are setting things up. @subsection Settings Next step: let's make a @t{mu4e} configuration for this: @lisp (require 'mu4e) ;; default ;; (setq mu4e-maildir "~/Maildir") (setq mu4e-drafts-folder "/[Gmail].Drafts") (setq mu4e-sent-folder "/[Gmail].Sent Mail") (setq mu4e-trash-folder "/[Gmail].Trash") ;; don't save message to Sent Messages, Gmail/IMAP takes care of this (setq mu4e-sent-messages-behavior 'delete) ;; setup some handy shortcuts ;; you can quickly switch to your Inbox -- press ``ji'' ;; then, when you want archive some messages, move them to ;; the 'All Mail' folder by pressing ``ma''. (setq mu4e-maildir-shortcuts '( ("/INBOX" . ?i) ("/[Gmail].Sent Mail" . ?s) ("/[Gmail].Trash" . ?t) ("/[Gmail].All Mail" . ?a))) ;; allow for updating mail using 'U' in the main view: (setq mu4e-get-mail-command "offlineimap") ;; something about ourselves (setq user-mail-address "USERNAME@@gmail.com" user-full-name "Foo X. Bar" message-signature (concat "Foo X. Bar\n" "http://www.example.com\n")) ;; sending mail -- replace USERNAME with your gmail username ;; also, make sure the gnutls command line utils are installed ;; package 'gnutls-bin' in Debian/Ubuntu (require 'smtpmail) (setq message-send-mail-function 'smtpmail-send-it starttls-use-gnutls t smtpmail-starttls-credentials '(("smtp.gmail.com" 587 nil nil)) smtpmail-auth-credentials '(("smtp.gmail.com" 587 "USERNAME@@gmail.com" nil)) smtpmail-default-smtp-server "smtp.gmail.com" smtpmail-smtp-server "smtp.gmail.com" smtpmail-smtp-service 587) ;; alternatively, for emacs-24 you can use: ;;(setq message-send-mail-function 'smtpmail-send-it ;; smtpmail-stream-type 'starttls ;; smtpmail-default-smtp-server "smtp.gmail.com" ;; smtpmail-smtp-server "smtp.gmail.com" ;; smtpmail-smtp-service 587) ;; don't keep message buffers around (setq message-kill-buffer-on-exit t) @end lisp And that's it -- put the above in your @file{~/.emacs}, change @t{USERNAME} etc. to your own, and restart @command{emacs}, and run @kbd{M-x mu4e}. @node Some other useful settings @section Some other useful settings Finally, here are some more settings that are useful, but not enabled by default for various reasons. @lisp ;; use 'fancy' non-ascii characters in various places in mu4e (setq mu4e-use-fancy-chars t) ;; save attachment to my desktop (this can also be a function) (setq mu4e-attachment-dir "~/Desktop") ;; attempt to show images when viewing messages (setq mu4e-view-show-images t mu4e-view-image-max-width 800) @end lisp @node FAQ @appendix FAQ - Frequently Asked Questions In this chapter we list a number of actual and anticipated questions and their answers. @menu * General:: * Reading messages:: * Writing messages:: * Known issues:: @end menu @node General @section General @enumerate @item @emph{How can I quickly delete/move/trash a lot of messages?} You can select ('mark' in @command{emacs}-speak) the messages like you would select text in a buffer; the actions you then take (e.g., @key{DEL} for delete, @key{m} for move and @key{t} for trash) apply to all selected messages. You can also use functions like @code{mu4e-headers-mark-thread} (@key{T}), @code{mu4e-headers-mark-subthread} (@key{t}) to mark whole threads at the same time, and @code{mu4e-headers-mark-pattern} (@key{%}) to mark all messages matching a certain regular expression. @item @emph{@t{mu4e} seems to return a subset of all matches - how can I get all?} For speed reasons, @t{mu4e} returns only up to the value of the variable @code{m4ue-search-result-limit} (default: 500) matches. To show @emph{all}, use @kbd{M-x mu4e-headers-toggle-full-search} (@key{Q}), or customize the variable @code{mu4e-headers-full-search}. This applies to all search commands. @item @emph{How can I get notifications when receiving mail?} There is @code{mu4e-index-updated-hook}, which gets triggered when the indexing process triggered sees an update (not just new mail though). To use this hook, put something like the following in your setup (assuming you have @t{aplay} and some soundfile, change as needed): @lisp (add-hook 'mu4e-index-updated-hook (defun new-mail-sound () (shell-command "aplay ~/Sounds/boing.wav&"))) @end lisp @item @emph{It seems my headers-buffer is automatically updated when new messages are found during the indexing process -- can I disable this somehow?} Yes - set @code{mu4e-headers-auto-update} to @code{nil}. @item @emph{I don't use @t{offlineimap}, @t{fetchmail} etc., I get my mail through my own mailserver. What should I use for @code{mu4e-get-mail-command}}? Use @t{"true"} (or don't do anything, it's the default). This makes getting mail a no-op, but the messages are still re-indexed. @item @emph{How can I re-index my messages without getting new mail?} Use @kbd{M-x mu4e-update-index} @item @emph{When I try to run @t{mu index} while @t{mu4e} is running I get errors like:} @verbatim mu: mu_store_new_writable: xapian error 'Unable to get write lock on ~/.mu/xapian: already locked @end verbatim @emph{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 @t{mu4e} can do about this, but if is another @command{mu} instance that is holding the lock, you can ask it to (gracefully) terminate: @verbatim pkill -2 -u $UID mu # send SIGINT sleep 1 mu index @end verbatim @t{mu4e} automatically restarts @t{mu} when it needs it. In practice, this seems to work quite well. @item @emph{Can I automatically apply the marks on messages when leaving the headers buffer?} Yes you can -- see the documentation for the variable @t{mu4e-headers-leave-behavior}. @item @emph{Is there context-sensitive help available?} Yes - pressing @key{H} should take you to the right place in this manual. @item @emph{How can I set @t{mu4e} as the default e-mail client in @command{emacs}?} See @ref{Setting the default emacs mail program}. @item @emph{Can @t{mu4e} use some fancy Unicode characters instead of these boring plain-ASCII ones?} Glad you asked! Yes, if you set @code{mu4e-use-fancy-chars} to @t{t}, @t{mu4e} uses such fancy characters in a number of places. @end enumerate @node Reading messages @section Reading messages @enumerate @item @emph{How can I show attached images in my message view buffers?} See @ref{Viewing images inline}. @item @emph{How can I word-wrap long lines in when viewing a message?} You can toggle between wrapped and non-wrapped states using @key{w}. If you want to do this automatically, invoke @code{longlines-mode} in your @code{mu4e-view-mode-hook}. @item @emph{What about hiding cited parts?} Toggle between hiding and showing of cited parts with @key{h}. If you want to hide parts automatically, call @code{mu4e-view-toggle-hide-cited} in your @code{mu4e-view-mode-hook}. @item @emph{How can I perform custom actions on messages and attachments?} See @ref{Actions}. @item @emph{Does @t{mu4e} support crypto (i.e., decrypting messages and verifying signatures)?} Yes -- if @t{mu} was built with @t{GMime} 2.6 or later, it is possible to do both (note, only PGP/MIME is supported). In the @ref{Main view} the support is indicated by a big letter @t{C} on the right hand side of the @t{mu4e} version. See @ref{Decryption} and @ref{Verifying signatures}. For encryption and signing messages, see the @ref{Writing messages}. @item @emph{Does @t{mu4e} support including all related messages in a thread, like Gmail does?} Yes -- see @ref{Including related messages}. @item @emph{There seem to be a lot of duplicate messages -- how can I get rid of them?} See @ref{Skipping duplicates}. @item @emph{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 @emph{action} (@ref{Adding an action in the message view}) defined for this. Simply add to your configuration: @lisp (add-to-list 'mu4e-view-actions '("ViewInBrowser" . mu4e-action-view-in-browser) t) @end lisp Now, when viewing such a difficult message, type @kbd{aV}, and the message opens inside a webbrowser. You can influence the browser with @code{browse-url-generic-program}. @end enumerate @node Writing messages @section Writing messages @enumerate @item @emph{How can I automatically set the @t{From:}-address for a reply-message, based on some field in the original?} See @ref{Compose hooks}. @item @emph{And what about customizable folders for draft messages, sent messages, trashed messages, based on e.g. the @t{From:} header?} See @ref{Dynamic folders}. @item @emph{How can I automatically add some header to an outgoing message?} Once more, see @ref{Compose hooks}. @item @emph{How can I influence the way the original message looks when replying or forwarding?} Since @code{mu4e-compose-mode} derives from @code{message-mode}, you can re-use many of the latter's facilities. @inforef{Insertion Variables,,message}. @item @emph{How can I easily include attachments in the messages I write?} You can drag-and-drop from your desktop; alternatively, you can use @t{dired} -- see @ref{Attaching files with dired}. @item @emph{@t{mu4e} seems to remove myself from the @t{Cc:}-list; how can I prevent that?} Set @code{mu4e-compose-keep-self-cc} to @t{t} in your configuration. @item @emph{How can I sign or encrypt messages?} You can do so using @command{emacs}' MIME-support -- check the @t{Attachments}-menu while composing a message. Also see @ref{Signing and encrypting}. @item @emph{Can I use @t{BBDB} with @t{mu4e}?} It should be possible, but there is no built-in support. Instead, we recommend using @t{mu4e}'s @ref{Address autocompletion}. @item @emph{After sending some messages, it seems the buffer for these messages stay around. How can I get rid of those?} @lisp (setq message-kill-buffer-on-exit t) @end lisp @item @emph{Sending big messages is slow and blocks emacs - what can I do about it?} For this, there's @url{https://github.com/jwiegley/emacs-async} (also available from the Emacs package repository); add the following snippet to your configuration: @lisp (require 'smtpmail-async) (setq send-mail-function 'async-smtpmail-send-it message-send-mail-function 'async-smtpmail-send-it) @end lisp With this, messages are sent using background emacs-instance. @end enumerate @node Known issues @section Known issues Although they are not really @emph{questions}, we end this chapter with a list of known issue and/or missing features in @t{mu4e}. Thus, users won't have to search in vain for things that are not there (yet), and the author can use it as a todo-list. @itemize @item @emph{mu4e does not work well if the @command{emacs} language environment is not utf-8}; so, if you problems with encodings, be sure to have @code{(set-language-environment "UTF-8")} in your @file{~/.emacs}. @item @emph{Thread handling is incomplete.} While threads are calculated and are visible in the headers buffer, you can not collapse/open them. @item @emph{The key-bindings are @emph{somewhat} hard-coded.} That is, the main menu assumes the default key-bindings, as do the clicks-on-bookmarks. @end itemize @node Tips and Tricks @appendix Tips and Tricks @menu * Multiple accounts:: * Refiling message:: * Saving outgoing messages:: @end menu @node Multiple accounts @section Multiple accounts Using mu4e with multiple email accounts is fairly easy. Although variables such as @code{user-mail-address}, @code{mu4e-sent-folder}, @code{message-*}, @code{smtpmail-*}, etc. typically only take one value, it is easy to change their values using @code{mu4e-compose-pre-hook}. The setup described here is one way of doing this (though certainly not the only way). This setup assumes that you have multiple mail accounts under @code{mu4e-maildir}. As an example, we'll use @t{~/Maildir/Account1} and @t{~/Maildir/Account2}, but the setup works just as well if @code{mu4e-maildir} points to something else. First, you need to make sure that all variables that you wish to change based on user account are set to some initial value. So set up your environment with e.g., your main account: @lisp (setq mu4e-sent-folder "/Account1/Saved Items" mu4e-drafts-folder "/Account1/Drafts" user-mail-address "my.address@@account1.tld" message-signature-file ".Signature1.txt" smtpmail-default-smtp-server "smtp.account1.tld" smtpmail-local-domain "account1.tld" smtpmail-smtp-server "smtp.account1.tld" smtpmail-stream-type starttls smtpmail-smtp-service 25) @end lisp Then create a variable @code{my-mu4e-account-alist}, which should contain a list for each of your accounts. Each list should start with the account name, (which @emph{must} be identical to the account's directory name under @t{~/Maildir}), followed by @code{(variable value)} pairs: @lisp (defvar my-mu4e-account-alist '(("Account1" (mu4e-sent-folder "/Account1/Saved Items") (mu4e-drafts-folder "/Account1/Drafts") (user-mail-address "my.address@@account1.tld") (message-signature-file ".Signature1.txt") (smtpmail-default-smtp-server "smtp.account1.tld") (smtpmail-local-domain "account1.tld") (smtpmail-smtp-server "smtp.account1.tld") (smtpmail-stream-type starttls) (smtpmail-smtp-service 25)) ("Account2" (mu4e-sent-folder "/Account2/Saved Items") (mu4e-drafts-folder "/Account2/Drafts") (user-mail-address "my.address@@account2.tld) (message-signature-file ".Signature2.txt") (smtpmail-default-smtp-server "smtp.account2.tld) (smtpmail-local-domain "account2.tld") (smtpmail-smtp-server "smtp.account2.tld) (smtpmail-stream-type starttls) (smtpmail-smtp-service 587)))) @end lisp You can put any variables you want in the account lists, just make sure that you put in @emph{all} the variables that differ for each account. Variables that do not differ do not be included. For example, if you use the same smtp server for both accounts, you don't need to include the smtp-related variables in @code{my-mu4e-account-alist}. Now, the following function can be used to select an account and set the variables in @code{my-mu4e-account-alist} to the correct values: @lisp (defun my-mu4e-set-account () "Set the account for composing a message." (let* ((account (if mu4e-compose-parent-message (let ((maildir (mu4e-message-field mu4e-compose-parent-message :maildir))) (string-match "/\\(.*?\\)/" maildir) (match-string 1 maildir)) (completing-read (format "Compose with account: (%s) " (mapconcat #'(lambda (var) (car var)) my-mu4e-account-alist "/")) (mapcar #'(lambda (var) (car var)) my-mu4e-account-alist) nil t nil nil (caar my-mu4e-account-alist)))) (account-vars (cdr (assoc account my-mu4e-account-alist)))) (if account-vars (mapc #'(lambda (var) (set (car var) (cadr var))) account-vars) (error "No email account found")))) @end lisp This function then needs to be added to @code{mu4e-compose-pre-hook}: @lisp (add-hook 'mu4e-compose-pre-hook 'my-mu4e-set-account) @end lisp This way, @code{my-mu4e-set-account} will be called every time you edit a message. If you compose a new message, it simply asks you for the account you wish to send the message from (TAB completion works). If you're replying or forwarding a message, or editing an existing draft, the account is chosen automatically, based on the first component of the maildir of the message being replied to, forwarded or edited (i.e., the directory under @t{~/Maildir}). @node Refiling message @section Refiling message By setting @code{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 @code{my-mu4e-subject-alist} containing regexes plus associated mail folders: @lisp (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.") @end lisp Now you can use the following function to automatically refile messages based on their subject line: @lisp (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)) @end lisp Note the @t{"/General"} folder: it is the default folder in case the subject does not match any of the regexes in @code{my-mu4e-subject-alist}. In order to make this work, you'll of course need to set @code{mu4e-refile-folder} to this function: @lisp (setq mu4e-refile-folder 'my-mu4e-refile-folder-function) @end lisp If you have multiple accounts, you can accommodate them as well: @lisp (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)) @end lisp This function actually uses different methods to determine the refile folder, depending on the account: For Account2, it uses @code{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: @lisp (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.") @end lisp @node Saving outgoing messages @section Saving outgoing messages Like @code{mu4e-refile-folder}, the variable @code{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). If you have set up the variable @code{my-mu4e-mailing-lists} as above, you can use the following function to determine a save folder: @lisp (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.tld" 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: "))))) @end lisp Note that this function doesn't use @code{(mu4e-message-field msg :maildir)} to determine which account the message is being sent from. The reason is that that the function in @code{mu4e-sent-folder} is called when you send the message, but before mu4e has created the message struct from the compose buffer, so that @code{mu4e-message-field} cannot be used. Instead, the function uses @code{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 (@t{my.address@@account1.tld}) it uses @code{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 @t{/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 @code{mu4e-ask-maildir-check-exists} to ask the user for a maildir to save the message in. @node How it works @appendix How it works While perhaps not interesting for all users of @t{mu4e}, some curious souls may want to know how @t{mu4e} does its job. @menu * High-level overview:: * mu server:: * Reading from the server:: * The message s-expression:: @end menu @node High-level overview @section High-level overview At a high level, we can summarize the structure of the @t{mu4e} system using some ascii-art: @cartouche @example +---------+ | emacs | | +------+ +----| mu4e | --> send mail (smtpmail) +------+ | A V | ---/ search, view, move mail +---------+ \ | mu | +---------+ | A V | +---------+ | Maildir | <--- receive mail (fetchmail, +---------+ offlineimap, ...) @end example @end cartouche In words: @itemize @item Your e-mail messages are stored in a Maildir-directory (typically, @file{~/Maildir} and its subdirectories), and new mail comes in using tools like @t{fetchmail}, @t{offlineimap}, or through a local mail server. @item @t{mu} indexes these messages periodically, so you can quickly search for them. @t{mu} can run in a special @t{server}-mode, where it provides services to client software. @item @t{mu4e}, which runs inside @command{emacs} is such a client; it communicates with @command{mu} (in its @t{server}-mode to search for messages, and manipulate them. @item @t{mu4e} uses the facilities offered by @command{emacs} (the Gnus message editor and @t{smtpmail}) to send messages. @end itemize @node mu server @section @t{mu server} @t{mu4e} is based on the @t{mu} e-mail searching/indexer. The latter is a C-program; there are different ways to communicate with a client that is emacs-based. One way to implement this, would be to call the @t{mu} command-line tool with some parameters and then parse the output. In fact, that was the first approach -- @t{mu4e} would invoke e.g., @t{mu find} and process the output in @command{emacs}. However, with this approach, we need to load the entire e-mail @emph{Xapian} database (in which the message is stored) for each invocation. Wouldn't it be nicer to keep a running @t{mu} instance around? Indeed, it would - and thus, the @t{mu server} sub-command was born. Running @t{mu server} starts a simple shell, in which you can give commands to @command{mu}, which then spits out the results/errors. @command{mu server} is not meant for humans, but it can be used manually, which is great for debugging. @node Reading from the server @section Reading from the server In the design, the next question was what format @t{mu} should use for its output for @t{mu4e} (@command{emacs}) to process. Some other programs use @abbr{JSON} here, but it seemed easier (and possibly, more efficient) just to talk to @command{emacs} in its native language: @emph{s-expressions}, and interpret those using the @command{emacs}-function @code{read-from-string}. See @ref{The message s-expression} for details on the format. So, now let's look how we process the data from @t{mu server} in @command{emacs}. We'll leave out a lot of detail, @t{mu4e}-specifics, and look at a bit more generic approach. The first thing to do is to create a process (for example, with @code{start-process}), and then register a filter function for it, which is invoked whenever the process has some data for us. Something like: @lisp (let ((proc (start-process ))) (set-process-filter proc 'my-process-filter) (set-process-sentinel proc 'my-process-sentinel)) @end lisp Note, the process sentinel is invoked when the process is terminated -- so there you can clean things up. The function @code{my-process-filter} is a user-defined function that takes the process and the chunk of output as arguments; in @t{mu4e} it looks something like (pseudo-lisp): @lisp (defun my-process-filter (proc str) ;; mu4e-buf: a global string variable to which data gets appended ;; as we receive it (setq mu4e-buf (concat mu4e-buf str)) (when )) @end lisp @code{} de-multiplexes the s-expression we got. For example, if the s-expression looks like an e-mail message header, it is processed by the header-handling function, which appends it to the header list. If the s-expression looks like an error message, it is reported to the user. And so on. The language between frontend and backend is documented in the @t{mu-server} man-page. @t{mu4e} can log these communications; you can use @kbd{M-x mu4e-toggle-logging} to turn logging on and off, and you can view the log using @kbd{M-x mu4e-show-log} (@key{$}). @node The message s-expression @section The message s-expression A typical message s-expression looks something like the following: @lisp (:docid 32461 :from (("Nikola Tesla" . "niko@@example.com")) :to (("Thomas Edison" . "tom@@example.com")) :cc (("Rupert The Monkey" . "rupert@@example.com")) :subject "RE: what about the 50K?" :date (20369 17624 0) :size 4337 :message-id "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, .... ")) @end lisp This s-expression forms a property list (@t{plist}), and we can get values from it using @t{plist-get}; for example @code{(plist-get msg :subject)} would get you the message subject. However, it's better to use the function @code{mu4e-message-field} to shield you from some of the implementation details that are subject to change; and see the other convenience functions in @file{mu4e-message.el}. Some notes on the format: @itemize @item The address fields are @emph{lists} of pairs @code{(name . email)}, where @t{name} can be nil. @item The date is in format @command{emacs} uses (for example in @code{current-time}).@footnote{Emacs 32-bit integers have only 29 bits available for the actual number; the other bits are use by @command{emacs} for internal purposes. Therefore, we need to split @t{time_t} in two numbers.} @item Attachments are a list of elements with fields @t{:index} (the number of the MIME-part), @t{:name} (the file name, if any), @t{:mime-type} (the MIME-type, if any) and @t{:size} (the size in bytes, if any). @item Messages in the @ref{Headers view} come from the database and do not have @t{:attachments}. @t{:body-txt} or @t{:body-html} fields. Message in the @ref{Message view} use the actual message file, and do include these fields. @end itemize @subsection Example: ping-pong As an example of the communication between @t{mu4e} and @command{mu}, let's look at the @t{ping-pong}-sequence. When @t{mu4e} starts, it sends a command @t{ping} to the the @t{mu server} backend, to learn about its version. @t{mu server} then responds with a @t{pong} s-expression to provide this information (this is implemented in @file{mu-cmd-server.c}). We start this sequence when @t{mu4e} is invoked (when the program is started). It calls @t{mu4e-proc-ping}, and registers a (lambda) function for @t{mu4e-proc-pong-func}, to handle the response. @verbatim -> ping <- (pong "mu" :version "x.x.x" :doccount 10000) @end verbatim When we receive such a @t{pong} (in @file{mu4e-proc.el}), the lambda function we registered is called, and it compares the version we got from the @t{pong} with the version we expected, and raises an error, if they differ. @node Logging and debugging @appendix Logging and debugging As explained in @ref{How it works}, @t{mu4e} communicates with its backend (@t{mu server}) by sending commands and receiving responses (s-expressions). For debugging purposes, it can be very useful to see this data. For this reason, @t{mu4e} can log all these messages. Note that the 'protocol' is documented to some extent in the @t{mu-server} manpage. You can enable (and disable) logging with @kbd{M-x mu4e-toggle-logging}. The log-buffer is called @t{*mu4e-log*}, and in the @ref{Main view}, @ref{Headers view} and @ref{Message view}, there's a keybinding @key{$} that takes you there. You can quit it by pressing @key{q}. Logging can be a bit resource-intensive, so you may not want to leave it on all the time. By default, the log only maintains the most recent 1200 lines. @t{mu} itself keeps a log as well, you can find this it in @t{/log/mu.log}, typically @t{~/.mu/log/mu.log}. @node GNU Free Documentation License @appendix GNU Free Documentation License @include fdl.texi @bye mu-0.9.9.5/mu4e/texi.texi.in0000644000175000017500000000011712040516626012362 00000000000000@c the version for mu for including in texinfo docs @set mu-version @VERSION@ mu-0.9.9.5/mu4e/mdate-sh0000755000175000017500000001371711743341532011554 00000000000000#!/bin/sh # Get modification time of a file or directory and pretty-print it. scriptversion=2010-08-21.06; # UTC # Copyright (C) 1995, 1996, 1997, 2003, 2004, 2005, 2007, 2009, 2010 # Free Software Foundation, Inc. # written by Ulrich Drepper , June 1995 # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2, or (at your option) # any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program. If not, see . # As a special exception to the GNU General Public License, if you # distribute this file as part of a program that contains a # configuration script generated by Autoconf, you may include it under # the same distribution terms that you use for the rest of that program. # This file is maintained in Automake, please report # bugs to or send patches to # . if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then emulate sh NULLCMD=: # Pre-4.2 versions of Zsh do word splitting on ${1+"$@"}, which # is contrary to our usage. Disable this feature. alias -g '${1+"$@"}'='"$@"' setopt NO_GLOB_SUBST fi case $1 in '') echo "$0: No file. Try \`$0 --help' for more information." 1>&2 exit 1; ;; -h | --h*) cat <<\EOF Usage: mdate-sh [--help] [--version] FILE Pretty-print the modification day of FILE, in the format: 1 January 1970 Report bugs to . EOF exit $? ;; -v | --v*) echo "mdate-sh $scriptversion" exit $? ;; esac error () { echo "$0: $1" >&2 exit 1 } # Prevent date giving response in another language. LANG=C export LANG LC_ALL=C export LC_ALL LC_TIME=C export LC_TIME # GNU ls changes its time format in response to the TIME_STYLE # variable. Since we cannot assume `unset' works, revert this # variable to its documented default. if test "${TIME_STYLE+set}" = set; then TIME_STYLE=posix-long-iso export TIME_STYLE fi save_arg1=$1 # Find out how to get the extended ls output of a file or directory. if ls -L /dev/null 1>/dev/null 2>&1; then ls_command='ls -L -l -d' else ls_command='ls -l -d' fi # Avoid user/group names that might have spaces, when possible. if ls -n /dev/null 1>/dev/null 2>&1; then ls_command="$ls_command -n" fi # A `ls -l' line looks as follows on OS/2. # drwxrwx--- 0 Aug 11 2001 foo # This differs from Unix, which adds ownership information. # drwxrwx--- 2 root root 4096 Aug 11 2001 foo # # To find the date, we split the line on spaces and iterate on words # until we find a month. This cannot work with files whose owner is a # user named `Jan', or `Feb', etc. However, it's unlikely that `/' # will be owned by a user whose name is a month. So we first look at # the extended ls output of the root directory to decide how many # words should be skipped to get the date. # On HPUX /bin/sh, "set" interprets "-rw-r--r--" as options, so the "x" below. set x`$ls_command /` # Find which argument is the month. month= command= until test $month do test $# -gt 0 || error "failed parsing \`$ls_command /' output" shift # Add another shift to the command. command="$command shift;" case $1 in Jan) month=January; nummonth=1;; Feb) month=February; nummonth=2;; Mar) month=March; nummonth=3;; Apr) month=April; nummonth=4;; May) month=May; nummonth=5;; Jun) month=June; nummonth=6;; Jul) month=July; nummonth=7;; Aug) month=August; nummonth=8;; Sep) month=September; nummonth=9;; Oct) month=October; nummonth=10;; Nov) month=November; nummonth=11;; Dec) month=December; nummonth=12;; esac done test -n "$month" || error "failed parsing \`$ls_command /' output" # Get the extended ls output of the file or directory. set dummy x`eval "$ls_command \"\\\$save_arg1\""` # Remove all preceding arguments eval $command # Because of the dummy argument above, month is in $2. # # On a POSIX system, we should have # # $# = 5 # $1 = file size # $2 = month # $3 = day # $4 = year or time # $5 = filename # # On Darwin 7.7.0 and 7.6.0, we have # # $# = 4 # $1 = day # $2 = month # $3 = year or time # $4 = filename # Get the month. case $2 in Jan) month=January; nummonth=1;; Feb) month=February; nummonth=2;; Mar) month=March; nummonth=3;; Apr) month=April; nummonth=4;; May) month=May; nummonth=5;; Jun) month=June; nummonth=6;; Jul) month=July; nummonth=7;; Aug) month=August; nummonth=8;; Sep) month=September; nummonth=9;; Oct) month=October; nummonth=10;; Nov) month=November; nummonth=11;; Dec) month=December; nummonth=12;; esac case $3 in ???*) day=$1;; *) day=$3; shift;; esac # Here we have to deal with the problem that the ls output gives either # the time of day or the year. case $3 in *:*) set `date`; eval year=\$$# case $2 in Jan) nummonthtod=1;; Feb) nummonthtod=2;; Mar) nummonthtod=3;; Apr) nummonthtod=4;; May) nummonthtod=5;; Jun) nummonthtod=6;; Jul) nummonthtod=7;; Aug) nummonthtod=8;; Sep) nummonthtod=9;; Oct) nummonthtod=10;; Nov) nummonthtod=11;; Dec) nummonthtod=12;; esac # For the first six month of the year the time notation can also # be used for files modified in the last year. if (expr $nummonth \> $nummonthtod) > /dev/null; then year=`expr $year - 1` fi;; *) year=$3;; esac # The result. echo $day $month $year # Local Variables: # mode: shell-script # sh-indentation: 2 # eval: (add-hook 'write-file-hooks 'time-stamp) # time-stamp-start: "scriptversion=" # time-stamp-format: "%:y-%02m-%02d.%02H" # time-stamp-time-zone: "UTC" # time-stamp-end: "; # UTC" # End: mu-0.9.9.5/mu4e/mu4e-draft.el0000664000175000017500000003501212067306775012422 00000000000000;; mu4e-draft.el -- part of mu4e, the mu mail user agent for emacs ;; ;; Copyright (C) 2011-2012 Dirk-Jan C. Binnema ;; Author: Dirk-Jan C. Binnema ;; Maintainer: Dirk-Jan C. Binnema ;; This file is not part of GNU Emacs. ;; ;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or ;; (at your option) any later version. ;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . ;;; Commentary: ;; In this file, various functions to create draft messages ;; Code (eval-when-compile (byte-compile-disable-warning 'cl-functions)) (require 'cl) (require 'mu4e-vars) (require 'mu4e-utils) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defun mu4e~draft-user-agent-construct () "Return the User-Agent string for mu4e. This is either the value of `mu4e-user-agent', or, if not set, a string based on the versions of mu4e and emacs." (format "mu4e %s; emacs %s" mu4e-mu-version emacs-version)) (defun mu4e~draft-cite-original (msg) "Return a cited version of the original message MSG as a plist. This function use gnus' `message-cite-function', and as such all its settings apply." (with-temp-buffer (when (fboundp 'mu4e-view-message-text) ;; keep bytecompiler happy (insert (mu4e-view-message-text msg)) ;; this seems to be needed, otherwise existing signatures ;; won't be stripped (message-yank-original) (goto-char (point-min)) (push-mark (point-max)) (funcall message-cite-function) (pop-mark) (buffer-string)))) (defun mu4e~draft-header (hdr val) "Return a header line of the form \"HDR: VAL\". If VAL is nil, return nil." (when val (format "%s: %s\n" hdr val))) (defun mu4e~draft-references-construct (msg) "Construct the value of the References: header based on MSG as a comma-separated string. Normally, this the concatenation of thedmesg q existing References + In-Reply-To (which may be empty, an note that :references includes the old in-reply-to as well) and the message-id. If the message-id is empty, returns the old References. If both are empty, return nil." (let* ( ;; these are the ones from the message being replied to / forwarded (refs (mu4e-message-field msg :references)) (msgid (mu4e-message-field msg :message-id)) ;; now, append in (refs (if (and msgid (not (string= msgid ""))) (append refs (list msgid)) refs)) ;; no doubles (refs (delete-duplicates refs :test #'equal))) (mapconcat (lambda (id) (format "<%s>" id)) refs " "))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; determine the recipient fields for new messages (defun mu4e~draft-recipients-list-to-string (lst) "Convert a lst LST of address cells into a string with a list of e-mail addresses. If LST is nil, returns nil." (when lst (mapconcat (lambda (addrcell) (let ((name (car addrcell)) (email (cdr addrcell))) (if name (format "\"%s\" <%s>" name email) (format "%s" email)))) lst ", "))) (defun mu4e~draft-address-cell-equal (cell1 cell2) "Return t if CELL1 and CELL2 have the same e-mail address. The comparison is done case-insensitively. If the cells done match return nil. CELL1 and CELL2 are cons cells of the form (NAME . EMAIL)." (string= (downcase (or (cdr cell1) "")) (downcase (or (cdr cell2) "")))) (defun mu4e~draft-create-to-lst (origmsg) "Create a list of address for the To: in a new message, based on the original message ORIGMSG. If the Reply-To address is set, use that, otherwise use the From address. Note, whatever was in the To: field before, goes to the Cc:-list (if we're doing a reply-to-all)." (let ((reply-to (or (plist-get origmsg :reply-to) (plist-get origmsg :from)))) (delete-duplicates reply-to :test #'mu4e~draft-address-cell-equal))) (defun mu4e~draft-create-cc-lst (origmsg reply-all) "Create a list of address for the Cc: in a new message, based on the original message ORIGMSG, and whether it's a reply-all." (when reply-all (let* ((cc-lst ;; get the cc-field from the original, remove dups (delete-duplicates (append (plist-get origmsg :to) (plist-get origmsg :cc)) :test #'mu4e~draft-address-cell-equal)) ;; now we have the basic list, but we must remove ;; addresses also in the to list (cc-lst (delete-if (lambda (cc-cell) (find-if (lambda (to-cell) (mu4e~draft-address-cell-equal cc-cell to-cell)) (mu4e~draft-create-to-lst origmsg))) cc-lst)) ;; finally, we need to remove ourselves from the cc-list ;; unless mu4e-compose-keep-self-cc is non-nil (cc-lst (if (or mu4e-compose-keep-self-cc (null user-mail-address)) cc-lst (delete-if (lambda (cc-cell) (member-if (lambda (addr) (string= (downcase addr) (downcase (cdr cc-cell)))) mu4e-user-mail-address-list)) cc-lst)))) cc-lst))) (defun mu4e~draft-recipients-construct (field origmsg &optional reply-all) "Create value (a string) for the recipient field FIELD (a symbol, :to or :cc), based on the original message ORIGMSG, and (optionally) REPLY-ALL which indicates this is a reply-to-all message. Return nil if there are no recipients for the particular field." (mu4e~draft-recipients-list-to-string (case field (:to (mu4e~draft-create-to-lst origmsg)) (:cc (mu4e~draft-create-cc-lst origmsg reply-all)) (otherwise (mu4e-error "Unsupported field"))))) (defun mu4e~draft-from-construct () "Construct a value for the From:-field of the reply to MSG, based on `user-full-name' and `user-mail-address'; if the latter is nil, function returns nil." (when user-mail-address (if user-full-name (format "%s <%s>" user-full-name user-mail-address) (format "%s" user-mail-address)))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (defun mu4e~draft-insert-mail-header-separator () "Insert `mail-header-separator' in the first empty line of the message. `message-mode' needs this line to know where the headers end and the body starts. Note, in `mu4e-compose-mode', we use `before-save-hook' and `after-save-hook' to ensure that this separator is never written to the message file. Also see `mu4e-remove-mail-header-separator'." ;; we set this here explicitly, since (as it has happened) a wrong ;; value for this (such as "") breaks address completion and other things (set (make-local-variable 'mail-header-separator) (purecopy "--text follows this line--")) (put 'mail-header-separator 'permanent-local t) (save-excursion (let ((sepa (propertize mail-header-separator 'intangible t 'read-only "Can't touch this" 'rear-nonsticky t 'font-lock-face 'mu4e-system-face))) (goto-char (point-min)) ;; search for the first empty line (if (search-forward-regexp "^$" nil t) (replace-match (concat sepa)) (progn ;; no empty line? then prepend one (goto-char (point-max)) (insert "\n" sepa)))))) (defun mu4e~draft-remove-mail-header-separator () "Remove `mail-header-separator; we do this before saving a file (and restore it afterwards), to ensure that the separator never hits the disk. Also see `mu4e~draft-insert-mail-header-separator." (save-excursion (goto-char (point-min)) ;; remove the --text follows this line-- separator (when (search-forward-regexp (concat "^" mail-header-separator)) (let ((inhibit-read-only t)) (replace-match ""))))) (defun mu4e~draft-user-wants-reply-all (origmsg) "Ask user whether she wants to reply to *all* recipients. If there is just one recipient of ORIGMSG do nothing." (let* ((recipnum (+ (length (mu4e~draft-create-to-lst origmsg)) (length (mu4e~draft-create-cc-lst origmsg t)))) (response (if (= recipnum 1) 'all ;; with one recipient, we can reply to 'all'.... (mu4e-read-option "Reply to " `( (,(format "all %d recipients" recipnum) . all) ("sender only" . sender-only)))))) (eq response 'all))) (defun mu4e~draft-message-filename-construct (&optional flagstr) "Construct a randomized name for a message file with flags FLAGSTR. It looks something like