<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.21">
<TITLE>The Mutt E-Mail Client: Advanced Usage</TITLE>
<LINK HREF="manual-5.html" REL=next>
<LINK HREF="manual-3.html" REL=previous>
<LINK HREF="manual.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="manual-5.html">Next</A>
<A HREF="manual-3.html">Previous</A>
<A HREF="manual.html#toc4">Contents</A>
<HR>
<H2><A NAME="s4">4.</A> <A HREF="manual.html#toc4">Advanced Usage</A></H2>
<H2><A NAME="regexp"></A> <A NAME="ss4.1">4.1</A> <A HREF="manual.html#toc4.1">Regular Expressions</A>
</H2>
<P>All string patterns in Mutt including those in more complex
<A HREF="#patterns">patterns</A> must be specified
using regular expressions (regexp) in the ``POSIX extended'' syntax (which
is more or less the syntax used by egrep and GNU awk). For your
convenience, we have included below a brief description of this syntax.</P>
<P>The search is case sensitive if the pattern contains at least one upper
case letter, and case insensitive otherwise. Note that ``\''
must be quoted if used for a regular expression in an initialization
command: ``\\''.</P>
<P>A regular expression is a pattern that describes a set of strings.
Regular expressions are constructed analogously to arithmetic
expressions, by using various operators to combine smaller expressions.</P>
<P>Note that the regular expression can be enclosed/delimited by either "
or ' which is useful if the regular expression includes a white-space
character. See
<A HREF="manual-3.html#muttrc-syntax">Syntax of Initialization Files</A>
for more information on " and ' delimiter processing. To match a
literal " or ' you must preface it with \ (backslash).</P>
<P>The fundamental building blocks are the regular expressions that match
a single character. Most characters, including all letters and digits,
are regular expressions that match themselves. Any metacharacter with
special meaning may be quoted by preceding it with a backslash.</P>
<P>The period ``.'' matches any single character. The caret ``^'' and
the dollar sign ``$'' are metacharacters that respectively match
the empty string at the beginning and end of a line.</P>
<P>A list of characters enclosed by ``['' and ``]'' matches any
single character in that list; if the first character of the list
is a caret ``^'' then it matches any character <B>not</B> in the
list. For example, the regular expression <B>[0123456789]</B>
matches any single digit. A range of ASCII characters may be specified
by giving the first and last characters, separated by a hyphen
``‐''. Most metacharacters lose their special meaning inside
lists. To include a literal ``]'' place it first in the list.
Similarly, to include a literal ``^'' place it anywhere but first.
Finally, to include a literal hyphen ``‐'' place it last.</P>
<P>Certain named classes of characters are predefined. Character classes
consist of ``[:'', a keyword denoting the class, and ``:]''.
The following classes are defined by the POSIX standard:</P>
<P>
<DL>
<DT><B>[:alnum:]</B><DD><P>Alphanumeric characters.</P>
<DT><B>[:alpha:]</B><DD><P>Alphabetic characters.</P>
<DT><B>[:blank:]</B><DD><P>Space or tab characters.</P>
<DT><B>[:cntrl:]</B><DD><P>Control characters.</P>
<DT><B>[:digit:]</B><DD><P>Numeric characters.</P>
<DT><B>[:graph:]</B><DD><P>Characters that are both printable and visible. (A space is printable,
but not visible, while an ``a'' is both.)</P>
<DT><B>[:lower:]</B><DD><P>Lower-case alphabetic characters.</P>
<DT><B>[:print:]</B><DD><P>Printable characters (characters that are not control characters.)</P>
<DT><B>[:punct:]</B><DD><P>Punctuation characters (characters that are not letter, digits, control
characters, or space characters).</P>
<DT><B>[:space:]</B><DD><P>Space characters (such as space, tab and formfeed, to name a few).</P>
<DT><B>[:upper:]</B><DD><P>Upper-case alphabetic characters.</P>
<DT><B>[:xdigit:]</B><DD><P>Characters that are hexadecimal digits.</P>
</DL>
</P>
<P>A character class is only valid in a regular expression inside the
brackets of a character list. Note that the brackets in these
class names are part of the symbolic names, and must be included
in addition to the brackets delimiting the bracket list. For
example, <B>[[:digit:]]</B> is equivalent to
<B>[0-9]</B>.</P>
<P>Two additional special sequences can appear in character lists. These
apply to non-ASCII character sets, which can have single symbols (called
collating elements) that are represented with more than one character,
as well as several characters that are equivalent for collating or
sorting purposes:</P>
<P>
<DL>
<DT><B>Collating Symbols</B><DD><P>A collating symbol is a multi-character collating element enclosed in
``[.'' and ``.]''. For example, if ``ch'' is a collating
element, then <B>[[.ch.]]</B> is a regexp that matches
this collating element, while <B>[ch]</B> is a regexp that
matches either ``c'' or ``h''.</P>
<DT><B>Equivalence Classes</B><DD><P>An equivalence class is a locale-specific name for a list of
characters that are equivalent. The name is enclosed in ``[=''
and ``=]''. For example, the name ``e'' might be used to
represent all of ``è'' ``é'' and ``e''. In this case,
<B>[[=e=]]</B> is a regexp that matches any of
``è'', ``é'' and ``e''.</P>
</DL>
</P>
<P>A regular expression matching a single character may be followed by one
of several repetition operators:</P>
<P>
<DL>
<DT><B>?</B><DD><P>The preceding item is optional and matched at most once.</P>
<DT><B>*</B><DD><P>The preceding item will be matched zero or more times.</P>
<DT><B>+</B><DD><P>The preceding item will be matched one or more times.</P>
<DT><B>{n}</B><DD><P>The preceding item is matched exactly <EM>n</EM> times.</P>
<DT><B>{n,}</B><DD><P>The preceding item is matched <EM>n</EM> or more times.</P>
<DT><B>{,m}</B><DD><P>The preceding item is matched at most <EM>m</EM> times.</P>
<DT><B>{n,m}</B><DD><P>The preceding item is matched at least <EM>n</EM> times, but no more than
<EM>m</EM> times.</P>
</DL>
</P>
<P>Two regular expressions may be concatenated; the resulting regular
expression matches any string formed by concatenating two substrings
that respectively match the concatenated subexpressions.</P>
<P>Two regular expressions may be joined by the infix operator ``|'';
the resulting regular expression matches any string matching either
subexpression.</P>
<P>Repetition takes precedence over concatenation, which in turn takes
precedence over alternation. A whole subexpression may be enclosed in
parentheses to override these precedence rules.</P>
<P><B>Note:</B> If you compile Mutt with the GNU <EM>rx</EM> package, the
following operators may also be used in regular expressions:</P>
<P>
<DL>
<DT><B>\\y</B><DD><P>Matches the empty string at either the beginning or the end of a word.</P>
<DT><B>\\B</B><DD><P>Matches the empty string within a word.</P>
<DT><B>\\<</B><DD><P>Matches the empty string at the beginning of a word.</P>
<DT><B>\\></B><DD><P>Matches the empty string at the end of a word.</P>
<DT><B>\\w</B><DD><P>Matches any word-constituent character (letter, digit, or underscore).</P>
<DT><B>\\W</B><DD><P>Matches any character that is not word-constituent.</P>
<DT><B>\\`</B><DD><P>Matches the empty string at the beginning of a buffer (string).</P>
<DT><B>\\'</B><DD><P>Matches the empty string at the end of a buffer.</P>
</DL>
</P>
<P>Please note however that these operators are not defined by POSIX, so
they may or may not be available in stock libraries on various systems.</P>
<H2><A NAME="patterns"></A> <A NAME="ss4.2">4.2</A> <A HREF="manual.html#toc4.2">Patterns</A>
</H2>
<P>Many of Mutt's commands allow you to specify a pattern to match
(limit, tag-pattern, delete-pattern, etc.). There are several ways to select
messages:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
~A all messages
~b EXPR messages which contain EXPR in the message body
~B EXPR messages which contain EXPR in the whole message
~c USER messages carbon-copied to USER
~C EXPR message is either to: or cc: EXPR
~D deleted messages
~d [MIN]-[MAX] messages with ``date-sent'' in a Date range
~E expired messages
~e EXPR message which contains EXPR in the ``Sender'' field
~F flagged messages
~f USER messages originating from USER
~g cryptographically signed messages
~G cryptographically encrypted messages
~H EXPR messages with a spam attribute matching EXPR
~h EXPR messages which contain EXPR in the message header
~k message contains PGP key material
~i ID message which match ID in the ``Message-ID'' field
~L EXPR message is either originated or received by EXPR
~l message is addressed to a known mailing list
~m [MIN]-[MAX] message in the range MIN to MAX *)
~n [MIN]-[MAX] messages with a score in the range MIN to MAX *)
~N new messages
~O old messages
~p message is addressed to you (consults alternates)
~P message is from you (consults alternates)
~Q messages which have been replied to
~R read messages
~r [MIN]-[MAX] messages with ``date-received'' in a Date range
~S superseded messages
~s SUBJECT messages having SUBJECT in the ``Subject'' field.
~T tagged messages
~t USER messages addressed to USER
~U unread messages
~v message is part of a collapsed thread.
~V cryptographically verified messages
~x EXPR messages which contain EXPR in the `References' field
~y EXPR messages which contain EXPR in the `X-Label' field
~z [MIN]-[MAX] messages with a size in the range MIN to MAX *)
~= duplicated messages (see $duplicate_threads)
~$ unreferenced messages (requires threaded view)
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Where EXPR, USER, ID, and SUBJECT are
<A HREF="#regexp">regular expressions</A>. Special attention has to be
made when using regular expressions inside of patterns. Specifically,
Mutt's parser for these patterns will strip one level of backslash (\),
which is normally used for quoting. If it is your intention to use a
backslash in the regular expression, you will need to use two backslashes
instead (\\).</P>
<P>*) The forms <CODE><[MAX]</CODE>, <CODE>>[MIN]</CODE>,
<CODE>[MIN]-</CODE> and <CODE>-[MAX]</CODE>
are allowed, too.</P>
<H3>Pattern Modifier</H3>
<P>Note that patterns matching 'lists' of addresses (notably c,C,p,P and t)
match if there is at least one match in the whole list. If you want to
make sure that all elements of that list match, you need to prefix your
pattern with ^.
This example matches all mails which only has recipients from Germany.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
^~C \.de$
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H3>Complex Patterns</H3>
<P>Logical AND is performed by specifying more than one criterion. For
example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
~t mutt ~f elkins
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>would select messages which contain the word ``mutt'' in the list of
recipients <B>and</B> that have the word ``elkins'' in the ``From'' header
field.</P>
<P>Mutt also recognizes the following operators to create more complex search
patterns:</P>
<P>
<UL>
<LI>! -- logical NOT operator</LI>
<LI>| -- logical OR operator</LI>
<LI>() -- logical grouping operator</LI>
</UL>
</P>
<P>Here is an example illustrating a complex search pattern. This pattern will
select all messages which do not contain ``mutt'' in the ``To'' or ``Cc''
field and which are from ``elkins''.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
!(~t mutt|~c mutt) ~f elkins
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Here is an example using white space in the regular expression (note
the ' and " delimiters). For this to match, the mail's subject must
match the ``^Junk +From +Me$'' and it must be from either ``Jim +Somebody''
or ``Ed +SomeoneElse'':</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
'~s "^Junk +From +Me$" ~f ("Jim +Somebody"|"Ed +SomeoneElse")'
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Note that if a regular expression contains parenthesis, or a veritical bar
("|"), you <B>must</B> enclose the expression in double or single quotes since
those characters are also used to separate different parts of Mutt's
pattern language. For example,</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
~f "me@(mutt\.org|cs\.hmc\.edu)"
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Without the quotes, the parenthesis wouldn't end.
This would be seperated to two OR'd patterns: <EM>~f me@(mutt\.org</EM>
and <EM>cs\.hmc\.edu)</EM>. They are never what you want.</P>
<H3>Searching by Date</H3>
<P>Mutt supports two types of dates, <EM>absolute</EM> and <EM>relative</EM>.</P>
<P><B>Absolute</B>. Dates <B>must</B> be in DD/MM/YY format (month and year are
optional, defaulting to the current month and year). An example of a valid
range of dates is:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
Limit to messages matching: ~d 20/1/95-31/10
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>If you omit the minimum (first) date, and just specify ``-DD/MM/YY'', all
messages <EM>before</EM> the given date will be selected. If you omit the maximum
(second) date, and specify ``DD/MM/YY-'', all messages <EM>after</EM> the given
date will be selected. If you specify a single date with no dash (``-''),
only messages sent on the given date will be selected. </P>
<P><B>Error Margins</B>. You can add error margins to absolute dates.
An error margin is a sign (+ or -), followed by a digit, followed by
one of the following units:
<PRE>
y years
m months
w weeks
d days
</PRE>
As a special case, you can replace the sign by a ``*'' character,
which is equivalent to giving identical plus and minus error margins.</P>
<P>Example: To select any messages two weeks around January 15, 2001,
you'd use the following pattern:
<BLOCKQUOTE><CODE>
<PRE>
Limit to messages matching: ~d 15/1/2001*2w
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P><B>Relative</B>. This type of date is relative to the current date, and may
be specified as:
<UL>
<LI>><EM>offset</EM> (messages older than <EM>offset</EM> units)</LI>
<LI><<EM>offset</EM> (messages newer than <EM>offset</EM> units)</LI>
<LI>=<EM>offset</EM> (messages exactly <EM>offset</EM> units old)</LI>
</UL>
</P>
<P><EM>offset</EM> is specified as a positive number with one of the following
units:
<PRE>
y years
m months
w weeks
d days
</PRE>
</P>
<P>Example: to select messages less than 1 month old, you would use
<BLOCKQUOTE><CODE>
<PRE>
Limit to messages matching: ~d <1m
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P><B>Note:</B> all dates used when searching are relative to the
<B>local</B> time zone, so unless you change the setting of your
<A HREF="manual-6.html#index_format">$index_format</A> to include a
<CODE>%[...]</CODE> format, these are <B>not</B> the dates shown
in the main index.</P>
<H2><A NAME="ss4.3">4.3</A> <A HREF="manual.html#toc4.3">Using Tags</A>
</H2>
<P>Sometimes it is desirable to perform an operation on a group of
messages all at once rather than one at a time. An example might be
to save messages to a mailing list to a separate folder, or to
delete all messages with a given subject. To tag all messages
matching a pattern, use the tag-pattern function, which is bound to
``shift-T'' by default. Or you can select individual messages by
hand using the ``tag-message'' function, which is bound to ``t'' by
default. See
<A HREF="#patterns">patterns</A> for Mutt's pattern
matching syntax.</P>
<P>Once you have tagged the desired messages, you can use the
``tag-prefix'' operator, which is the ``;'' (semicolon) key by default.
When the ``tag-prefix'' operator is used, the <B>next</B> operation will
be applied to all tagged messages if that operation can be used in that
manner. If the
<A HREF="manual-6.html#auto_tag">$auto_tag</A>
variable is set, the next operation applies to the tagged messages
automatically, without requiring the ``tag-prefix''.</P>
<P>In
<A HREF="manual-3.html#macro">macros</A> or
<A HREF="manual-3.html#push">push</A> commands,
you can use the ``tag-prefix-cond'' operator. If there are no tagged
messages, mutt will "eat" the rest of the macro to abort it's execution.
Mutt will stop "eating" the macro when it encounters the ``end-cond''
operator; after this operator the rest of the macro will be executed as
normal.</P>
<H2><A NAME="hooks"></A> <A NAME="ss4.4">4.4</A> <A HREF="manual.html#toc4.4">Using Hooks</A>
</H2>
<P>A <EM>hook</EM> is a concept borrowed from the EMACS editor which allows you to
execute arbitrary commands before performing some operation. For example,
you may wish to tailor your configuration based upon which mailbox you are
reading, or to whom you are sending mail. In the Mutt world, a <EM>hook</EM>
consists of a
<A HREF="#regexp">regular expression</A> or
<A HREF="#patterns">pattern</A> along with a
configuration option/command. See
<UL>
<LI>
<A HREF="manual-3.html#folder-hook">folder-hook</A></LI>
<LI>
<A HREF="manual-3.html#send-hook">send-hook</A></LI>
<LI>
<A HREF="manual-3.html#message-hook">message-hook</A></LI>
<LI>
<A HREF="manual-3.html#save-hook">save-hook</A></LI>
<LI>
<A HREF="manual-3.html#mbox-hook">mbox-hook</A></LI>
<LI>
<A HREF="manual-3.html#fcc-hook">fcc-hook</A></LI>
<LI>
<A HREF="manual-3.html#fcc-save-hook">fcc-save-hook</A></LI>
</UL>
for specific details on each type of <EM>hook</EM> available.</P>
<P><B>Note:</B> if a hook changes configuration settings, these changes remain
effective until the end of the current mutt session. As this is generally
not desired, a default hook needs to be added before all other hooks to
restore configuration defaults. Here is an example with send-hook and the
my_hdr directive:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
send-hook . 'unmy_hdr From:'
send-hook ~C'^b@b\.b$' my_hdr from: c@c.c
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H3><A NAME="pattern_hook"></A> Message Matching in Hooks</H3>
<P>Hooks that act upon messages (<CODE>send-hook, save-hook, fcc-hook,
message-hook</CODE>) are evaluated in a slightly different manner. For the other
types of hooks, a
<A HREF="#regexp">regular expression</A> is
sufficient. But in dealing with messages a finer grain of control is
needed for matching since for different purposes you want to match
different criteria.</P>
<P>Mutt allows the use of the
<A HREF="#patterns">search pattern</A>
language for matching messages in hook commands. This works in
exactly the same way as it would when <EM>limiting</EM> or
<EM>searching</EM> the mailbox, except that you are restricted to those
operators which match information mutt extracts from the header of
the message (i.e. from, to, cc, date, subject, etc.).</P>
<P>For example, if you wanted to set your return address based upon sending
mail to a specific address, you could do something like:
<BLOCKQUOTE><CODE>
<PRE>
send-hook '~t ^me@cs\.hmc\.edu$' 'my_hdr From: Mutt User <user@host>'
</PRE>
</CODE></BLOCKQUOTE>
which would execute the given command when sending mail to
<EM>me@cs.hmc.edu</EM>.</P>
<P>However, it is not required that you write the pattern to match using the
full searching language. You can still specify a simple <EM>regular
expression</EM> like the other hooks, in which case Mutt will translate your
pattern into the full language, using the translation specified by the
<A HREF="manual-6.html#default_hook">$default_hook</A> variable. The
pattern is translated at the time the hook is declared, so the value of
<A HREF="manual-6.html#default_hook">$default_hook</A> that is in effect
at that time will be used.</P>
<H2><A NAME="query"></A> <A NAME="ss4.5">4.5</A> <A HREF="manual.html#toc4.5">External Address Queries</A>
</H2>
<P>Mutt supports connecting to external directory databases such as LDAP,
ph/qi, bbdb, or NIS through a wrapper script which connects to mutt
using a simple interface. Using the
<A HREF="manual-6.html#query_command">$query_command</A> variable, you specify the wrapper
command to use. For example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
set query_command = "mutt_ldap_query.pl '%s'"
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The wrapper script should accept the query on the command-line. It
should return a one line message, then each matching response on a
single line, each line containing a tab separated address then name then
some other optional information. On error, or if there are no matching
addresses, return a non-zero exit code and a one line error message.</P>
<P>An example multiple response output:
<BLOCKQUOTE><CODE>
<PRE>
Searching database ... 20 entries ... 3 matching:
me@cs.hmc.edu Michael Elkins mutt dude
blong@fiction.net Brandon Long mutt and more
roessler@guug.de Thomas Roessler mutt pgp
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>There are two mechanisms for accessing the query function of mutt. One
is to do a query from the index menu using the query function (default: Q).
This will prompt for a query, then bring up the query menu which will
list the matching responses. From the query menu, you can select
addresses to create aliases, or to mail. You can tag multiple addresses
to mail, start a new query, or have a new query appended to the current
responses.</P>
<P>The other mechanism for accessing the query function is for address
completion, similar to the alias completion. In any prompt for address
entry, you can use the complete-query function (default: ^T) to run a
query based on the current address you have typed. Like aliases, mutt
will look for what you have typed back to the last space or comma. If
there is a single response for that query, mutt will expand the address
in place. If there are multiple responses, mutt will activate the query
menu. At the query menu, you can select one or more addresses to be
added to the prompt.</P>
<H2><A NAME="ss4.6">4.6</A> <A HREF="manual.html#toc4.6">Mailbox Formats</A>
</H2>
<P>Mutt supports reading and writing of four different mailbox formats:
mbox, MMDF, MH and Maildir. The mailbox type is autodetected, so there
is no need to use a flag for different mailbox types. When creating new
mailboxes, Mutt uses the default specified with the
<A HREF="manual-6.html#mbox_type">$mbox_type</A> variable.</P>
<P><B>mbox</B>. This is the most widely used mailbox format for UNIX. All
messages are stored in a single file. Each message has a line of the form:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
From me@cs.hmc.edu Fri, 11 Apr 1997 11:44:56 PST
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>to denote the start of a new message (this is often referred to as the
``From_'' line).</P>
<P><B>MMDF</B>. This is a variant of the <EM>mbox</EM> format. Each message is
surrounded by lines containing ``^A^A^A^A'' (four control-A's).</P>
<P><B>MH</B>. A radical departure from <EM>mbox</EM> and <EM>MMDF</EM>, a mailbox
consists of a directory and each message is stored in a separate file.
The filename indicates the message number (however, this is may not
correspond to the message number Mutt displays). Deleted messages are
renamed with a comma (,) prepended to the filename. <B>Note:</B> Mutt
detects this type of mailbox by looking for either <CODE>.mh_sequences</CODE>
or <CODE>.xmhcache</CODE> (needed to distinguish normal directories from MH
mailboxes).</P>
<P><B>Maildir</B>. The newest of the mailbox formats, used by the Qmail MTA (a
replacement for sendmail). Similar to <EM>MH</EM>, except that it adds three
subdirectories of the mailbox: <EM>tmp</EM>, <EM>new</EM> and <EM>cur</EM>. Filenames
for the messages are chosen in such a way they are unique, even when two
programs are writing the mailbox over NFS, which means that no file locking
is needed.</P>
<H2><A NAME="shortcuts"></A> <A NAME="ss4.7">4.7</A> <A HREF="manual.html#toc4.7">Mailbox Shortcuts</A>
</H2>
<P>There are a number of built in shortcuts which refer to specific mailboxes.
These shortcuts can be used anywhere you are prompted for a file or mailbox
path.</P>
<P>
<UL>
<LI>! -- refers to your
<A HREF="manual-6.html#spoolfile">$spoolfile</A> (incoming) mailbox</LI>
<LI>> -- refers to your
<A HREF="manual-6.html#mbox">$mbox</A> file</LI>
<LI>< -- refers to your
<A HREF="manual-6.html#record">$record</A> file</LI>
<LI>- or !! -- refers to the file you've last visited</LI>
<LI>~ -- refers to your home directory</LI>
<LI>= or + -- refers to your
<A HREF="manual-6.html#folder">$folder</A> directory</LI>
<LI>@<EM>alias</EM> -- refers to the
<A HREF="manual-3.html#save-hook">default save folder</A> as determined by the address of the alias</LI>
</UL>
</P>
<H2><A NAME="using_lists"></A> <A NAME="ss4.8">4.8</A> <A HREF="manual.html#toc4.8">Handling Mailing Lists</A>
</H2>
<P>Mutt has a few configuration options that make dealing with large
amounts of mail easier. The first thing you must do is to let Mutt
know what addresses you consider to be mailing lists (technically
this does not have to be a mailing list, but that is what it is most
often used for), and what lists you are subscribed to. This is
accomplished through the use of the
<A HREF="manual-3.html#lists">lists and subscribe</A> commands in your muttrc.</P>
<P>Now that Mutt knows what your mailing lists are, it can do several
things, the first of which is the ability to show the name of a list
through which you received a message (i.e., of a subscribed list) in
the <EM>index</EM> menu display. This is useful to distinguish between
personal and list mail in the same mailbox. In the
<A HREF="manual-6.html#index_format">$index_format</A> variable, the escape ``%L''
will return the string ``To <list>'' when ``list'' appears in the
``To'' field, and ``Cc <list>'' when it appears in the ``Cc''
field (otherwise it returns the name of the author).</P>
<P>Often times the ``To'' and ``Cc'' fields in mailing list messages
tend to get quite large. Most people do not bother to remove the
author of the message they are reply to from the list, resulting in
two or more copies being sent to that person. The ``list-reply''
function, which by default is bound to ``L'' in the <EM>index</EM> menu
and <EM>pager</EM>, helps reduce the clutter by only replying to the
known mailing list addresses instead of all recipients (except as
specified by <CODE>Mail-Followup-To</CODE>, see below).</P>
<P>Mutt also supports the <CODE>Mail-Followup-To</CODE> header. When you send
a message to a list of recipients which includes one or several
subscribed mailing lists, and if the
<A HREF="manual-6.html#followup_to">$followup_to</A> option is set, mutt will generate
a Mail-Followup-To header which contains all the recipients to whom
you send this message, but not your address. This indicates that
group-replies or list-replies (also known as ``followups'') to this
message should only be sent to the original recipients of the
message, and not separately to you - you'll receive your copy through
one of the mailing lists you are subscribed to.</P>
<P>Conversely, when group-replying or list-replying to a message which
has a <CODE>Mail-Followup-To</CODE> header, mutt will respect this header if
the
<A HREF="manual-6.html#honor_followup_to">$honor_followup_to</A> configuration
variable is set. Using list-reply will in this case also make sure
that the reply goes to the mailing list, even if it's not specified
in the list of recipients in the <CODE>Mail-Followup-To</CODE>.</P>
<P>Note that, when header editing is enabled, you can create a
<CODE>Mail-Followup-To</CODE> header manually. Mutt will only auto-generate
this header if it doesn't exist when you send the message.</P>
<P>The other method some mailing list admins use is to generate a
``Reply-To'' field which points back to the mailing list address rather
than the author of the message. This can create problems when trying
to reply directly to the author in private, since most mail clients
will automatically reply to the address given in the ``Reply-To''
field. Mutt uses the
<A HREF="manual-6.html#reply_to">$reply_to</A>
variable to help decide which address to use. If set to <EM>ask-yes</EM> or
<EM>ask-no</EM>, you will be
prompted as to whether or not you would like to use the address given in
the ``Reply-To'' field, or reply directly to the address given in the
``From'' field. When set to <EM>yes</EM>, the ``Reply-To'' field will be used when
present.</P>
<P>The ``X-Label:'' header field can be used to further identify mailing
lists or list subject matter (or just to annotate messages
individually). The
<A HREF="manual-6.html#index_format">$index_format</A> variable's ``%y'' and
``%Y'' escapes can be used to expand ``X-Label:'' fields in the
index, and Mutt's pattern-matcher can match regular expressions to
``X-Label:'' fields with the `` y'' selector. ``X-Label:'' is not a
standard message header field, but it can easily be inserted by procmail
and other mail filtering agents.</P>
<P>Lastly, Mutt has the ability to
<A HREF="manual-6.html#sort">sort</A> the mailbox into
<A HREF="manual-2.html#threads">threads</A>. A thread is a group of messages which all relate to the same
subject. This is usually organized into a tree-like structure where a
message and all of its replies are represented graphically. If you've ever
used a threaded news client, this is the same concept. It makes dealing
with large volume mailing lists easier because you can easily delete
uninteresting threads and quickly find topics of value.</P>
<H2><A NAME="ss4.9">4.9</A> <A HREF="manual.html#toc4.9">Editing threads</A>
</H2>
<P>Mutt has the ability to dynamically restructure threads that are broken
either by misconfigured software or bad behaviour from some
correspondents. This allows to clean your mailboxes formats) from these
annoyances which make it hard to follow a discussion.</P>
<P>If you want to use these functions with IMAP, you need to compile Mutt
with the <EM>--enable-imap-edit-threads</EM> configure flag.</P>
<H3>Linking threads</H3>
<P>Some mailers tend to "forget" to correctly set the "In-Reply-To:" and
"References:" headers when replying to a message. This results in broken
discussions because Mutt has not enough information to guess the correct
threading.
You can fix this by tagging the reply, then moving to the parent message
and using the ``link-threads'' function (bound to & by default). The
reply will then be connected to this "parent" message.</P>
<P>You can also connect multiple childs at once, tagging them and using the
tag-prefix command (';') or the auto_tag option.</P>
<H3>Breaking threads</H3>
<P>On mailing lists, some people are in the bad habit of starting a new
discussion by hitting "reply" to any message from the list and changing
the subject to a totally unrelated one.
You can fix such threads by using the ``break-thread'' function (bound
by default to #), which will turn the subthread starting from the
current message into a whole different thread.</P>
<H2><A NAME="ss4.10">4.10</A> <A HREF="manual.html#toc4.10">Delivery Status Notification (DSN) Support</A>
</H2>
<P>RFC1894 defines a set of MIME content types for relaying information
about the status of electronic mail messages. These can be thought of as
``return receipts.'' Berkeley sendmail 8.8.x currently has some command
line options in which the mail client can make requests as to what type
of status messages should be returned.</P>
<P>To support this, there are two variables.
<A HREF="manual-6.html#dsn_notify">$dsn_notify</A> is used to request receipts for
different results (such as failed message, message delivered, etc.).
<A HREF="manual-6.html#dsn_return">$dsn_return</A> requests how much
of your message should be returned with the receipt (headers or full
message). Refer to the man page on sendmail for more details on DSN.</P>
<H2><A NAME="ss4.11">4.11</A> <A HREF="manual.html#toc4.11">POP3 Support (OPTIONAL)</A>
</H2>
<P>If Mutt was compiled with POP3 support (by running the <EM>configure</EM>
script with the <EM>--enable-pop</EM> flag), it has the ability to work
with mailboxes located on a remote POP3 server and fetch mail for local
browsing.</P>
<P>You can access the remote POP3 mailbox by selecting the folder
<CODE>pop://popserver/</CODE>.</P>
<P>You can select an alternative port by specifying it with the server, ie:
<CODE>pop://popserver:port/</CODE>.</P>
<P>You can also specify different username for each folder, ie:
<CODE>pop://username@popserver[:port]/</CODE>.</P>
<P>Polling for new mail is more expensive over POP3 than locally. For this
reason the frequency at which Mutt will check for mail remotely can be
controlled by the
<A HREF="manual-6.html#pop_checkinterval">$pop_checkinterval</A>
variable, which defaults to every 60 seconds.</P>
<P>If Mutt was compiled with SSL support (by running the <EM>configure</EM>
script with the <EM>--with-ssl</EM> flag), connections to POP3 servers
can be encrypted. This naturally requires that the server supports
SSL encrypted connections. To access a folder with POP3/SSL, you should
use pops: prefix, ie:
<CODE>pops://[username@]popserver[:port]/</CODE>.</P>
<P>Another way to access your POP3 mail is the <EM>fetch-mail</EM> function
(default: G). It allows to connect to
<A HREF="manual-6.html#pop_host">pop_host</A>, fetch all your new mail and place it in the
local
<A HREF="manual-6.html#spoolfile">spoolfile</A>. After this
point, Mutt runs exactly as if the mail had always been local.</P>
<P><B>Note:</B> If you only need to fetch all messages to local mailbox
you should consider using a specialized program, such as
<A HREF="http://www.ccil.org/~esr/fetchmail">fetchmail</A></P>
<H2><A NAME="ss4.12">4.12</A> <A HREF="manual.html#toc4.12">IMAP Support (OPTIONAL)</A>
</H2>
<P>If Mutt was compiled with IMAP support (by running the <EM>configure</EM>
script with the <EM>--enable-imap</EM> flag), it has the ability to work
with folders located on a remote IMAP server.</P>
<P>You can access the remote inbox by selecting the folder
<CODE>imap://imapserver/INBOX</CODE>, where <CODE>imapserver</CODE> is the name of the
IMAP server and <CODE>INBOX</CODE> is the special name for your spool mailbox on
the IMAP server. If you want to access another mail folder at the IMAP
server, you should use <CODE>imap://imapserver/path/to/folder</CODE> where
<CODE>path/to/folder</CODE> is the path of the folder you want to access.</P>
<P>You can select an alternative port by specifying it with the server, ie:
<CODE>imap://imapserver:port/INBOX</CODE>.</P>
<P>You can also specify different username for each folder, ie:
<CODE>imap://username@imapserver[:port]/INBOX</CODE>.</P>
<P>If Mutt was compiled with SSL support (by running the <EM>configure</EM>
script with the <EM>--with-ssl</EM> flag), connections to IMAP servers
can be encrypted. This naturally requires that the server supports
SSL encrypted connections. To access a folder with IMAP/SSL, you should
use <CODE>imaps://[username@]imapserver[:port]/path/to/folder</CODE> as your
folder path.</P>
<P>Pine-compatible notation is also supported, ie
<CODE>{[username@]imapserver[:port][/ssl]}path/to/folder</CODE></P>
<P>Note that not all servers use / as the hierarchy separator. Mutt should
correctly notice which separator is being used by the server and convert
paths accordingly.</P>
<P>When browsing folders on an IMAP server, you can toggle whether to look
at only the folders you are subscribed to, or all folders with the
<EM>toggle-subscribed</EM> command. See also the
<A HREF="manual-6.html#imap_list_subscribed">$imap_list_subscribed</A> variable.</P>
<P>Polling for new mail on an IMAP server can cause noticeable delays. So, you'll
want to carefully tune the
<A HREF="manual-6.html#mail_check">$mail_check</A>
and
<A HREF="manual-6.html#timeout">$timeout</A>
variables. Personally I use
<BLOCKQUOTE><CODE>
<PRE>
set mail_check=90
set timeout=15
</PRE>
</CODE></BLOCKQUOTE>
with relatively good results over my slow modem line.</P>
<P>Note that if you are using mbox as the mail store on UW servers prior to
v12.250, the server has been reported to disconnect a client if another client
selects the same folder.</P>
<H3>The Folder Browser</H3>
<P>As of version 1.2, mutt supports browsing mailboxes on an IMAP
server. This is mostly the same as the local file browser, with the
following differences:
<UL>
<LI>In lieu of file permissions, mutt displays the string "IMAP",
possibly followed by the symbol "+", indicating
that the entry contains both messages and subfolders. On
Cyrus-like servers folders will often contain both messages and
subfolders. </LI>
<LI>For the case where an entry can contain both messages and
subfolders, the selection key (bound to <CODE>enter</CODE> by default)
will choose to descend into the subfolder view. If you wish to view
the messages in that folder, you must use <CODE>view-file</CODE> instead
(bound to <CODE>space</CODE> by default).</LI>
<LI>You can create, delete and rename mailboxes with the
<CODE>create-mailbox</CODE>, <CODE>delete-mailbox</CODE>, and
<CODE>rename-mailbox</CODE> commands (default bindings: <CODE>C</CODE>,
<CODE>d</CODE> and <CODE>r</CODE>, respectively). You may also
<CODE>subscribe</CODE> and <CODE>unsubscribe</CODE> to mailboxes (normally
these are bound to <CODE>s</CODE> and <CODE>u</CODE>, respectively).</LI>
</UL>
</P>
<H3>Authentication</H3>
<P>Mutt supports four authentication methods with IMAP servers: SASL,
GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add
NTLM authentication for you poor exchange users out there, but it has
yet to be integrated into the main tree). There is also support for
the pseudo-protocol ANONYMOUS, which allows you to log in to a public
IMAP server without having an account. To use ANONYMOUS, simply make
your username blank or "anonymous".</P>
<P>SASL is a special super-authenticator, which selects among several protocols
(including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the most secure
method available on your host and the server. Using some of these methods
(including DIGEST-MD5 and possibly GSSAPI), your entire session will be
encrypted and invisible to those teeming network snoops. It is the best
option if you have it. To use it, you must have the Cyrus SASL library
installed on your system and compile mutt with the <EM>--with-sasl</EM> flag.</P>
<P>Mutt will try whichever methods are compiled in and available on the server,
in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5, LOGIN.</P>
<P>There are a few variables which control authentication:
<UL>
<LI>
<A HREF="manual-6.html#imap_user">$imap_user</A> - controls
the username under which you request authentication on the IMAP server,
for all authenticators. This is overridden by an explicit username in
the mailbox path (ie by using a mailbox name of the form
<CODE>{user@host}</CODE>).</LI>
<LI>
<A HREF="manual-6.html#imap_pass">$imap_pass</A> - a
password which you may preset, used by all authentication methods where
a password is needed.</LI>
<LI>
<A HREF="manual-6.html#imap_authenticators">$imap_authenticators</A> - a colon-delimited list of IMAP
authentication methods to try, in the order you wish to try them. If
specified, this overrides mutt's default (attempt everything, in the order
listed above).</LI>
</UL>
</P>
<H2><A NAME="account-hook"></A> <A NAME="ss4.13">4.13</A> <A HREF="manual.html#toc4.13">Managing multiple IMAP/POP accounts (OPTIONAL)</A>
</H2>
<P>If you happen to have accounts on multiple IMAP and/or POP servers,
you may find managing all the authentication settings inconvenient and
error-prone. The account-hook command may help. This hook works like
folder-hook but is invoked whenever you access a remote mailbox
(including inside the folder browser), not just when you open the
mailbox.</P>
<P>Some examples:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
account-hook . 'unset imap_user; unset imap_pass; unset tunnel'
account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo'
account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"'
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="urlview"></A> <A NAME="ss4.14">4.14</A> <A HREF="manual.html#toc4.14">Start a WWW Browser on URLs (EXTERNAL)</A>
</H2>
<P>If a message contains URLs (<EM>unified resource locator</EM> = address in the
WWW space like <EM>http://www.mutt.org/</EM>), it is efficient to get
a menu with all the URLs and start a WWW browser on one of them. This
functionality is provided by the external urlview program which can be
retrieved at
<A HREF="ftp://ftp.mutt.org/mutt/contrib/">ftp://ftp.mutt.org/mutt/contrib/</A> and the configuration commands:
<BLOCKQUOTE><CODE>
<PRE>
macro index \cb |urlview\n
macro pager \cb |urlview\n
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss4.15">4.15</A> <A HREF="manual.html#toc4.15">Compressed folders Support (OPTIONAL)</A>
</H2>
<P>If Mutt was compiled with compressed folders support (by running the
<EM>configure</EM> script with the <EM>--enable-compressed</EM> flag), Mutt
can open folders stored in an arbitrary format, provided that the user
has a script to convert from/to this format to one of the accepted.</P>
<P>The most common use is to open compressed archived folders e.g. with
gzip.</P>
<P>In addition, the user can provide a script that gets a folder in an
accepted format and appends its context to the folder in the
user-defined format, which may be faster than converting the entire
folder to the accepted format, appending to it and converting back to
the user-defined format.</P>
<P>There are three hooks defined (
<A HREF="#open-hook">open-hook</A>,
<A HREF="#close-hook">close-hook</A> and
<A HREF="#append-hook">append-hook</A>) which define commands to uncompress and compress
a folder and to append messages to an existing compressed folder
respectively.</P>
<P>For example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
open-hook \\.gz$ "gzip -cd %f > %t"
close-hook \\.gz$ "gzip -c %t > %f"
append-hook \\.gz$ "gzip -c %t >> %f"
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>You do not have to specify all of the commands. If you omit
<A HREF="#append-hook">append-hook</A>, the folder will be open and
closed again each time you will add to it. If you omit
<A HREF="#close-hook">close-hook</A> (or give empty command) , the
folder will be open in the mode. If you specify
<A HREF="#append-hook">append-hook</A> though you'll be able to append
to the folder.</P>
<P>Note that Mutt will only try to use hooks if the file is not in one of
the accepted formats. In particular, if the file is empty, mutt
supposes it is not compressed. This is important because it allows the
use of programs that do not have well defined extensions. Just use
"." as a regexp. But this may be surprising if your
compressing script produces empty files. In this situation, unset
<A HREF="manual-6.html#save_empty">$save_empty</A>, so that the compressed file
will be removed if you delete all of the messages.</P>
<H3><A NAME="open-hook"></A> Open a compressed mailbox for reading</H3>
<P>Usage: <CODE>open-hook</CODE> <EM>regexp</EM> "<EM>command</EM>"</P>
<P>The <EM>command</EM> is the command that can be used for opening the
folders whose names match <EM>regexp</EM>.</P>
<P>The <EM>command</EM> string is the printf-like format string, and it
should accept two parameters: %f, which is replaced with the
(compressed) folder name, and %t which is replaced with the
name of the temporary folder to which to write.</P>
<P>%f and %t can be repeated any number of times in the
command string, and all of the entries are replaced with the
appropriate folder name. In addition, %% is replaced by
%, as in printf, and any other %anything is left as is.</P>
<P>The <EM>command</EM> should <B>not</B> remove the original compressed file.
The <EM>command</EM> should return non-zero exit status if it fails, so
mutt knows something's wrong.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
open-hook \\.gz$ "gzip -cd %f > %t"
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>If the <EM>command</EM> is empty, this operation is disabled for this file
type.</P>
<H3><A NAME="close-hook"></A> Write a compressed mailbox</H3>
<P>Usage: <CODE>close-hook</CODE> <EM>regexp</EM> "<EM>command</EM>"</P>
<P>This is used to close the folder that was open with the
<A HREF="#open-hook">open-hook</A> command after some changes were made to it.</P>
<P>The <EM>command</EM> string is the command that can be used for closing the
folders whose names match <EM>regexp</EM>. It has the same format as in
the
<A HREF="#open-hook">open-hook</A> command. Temporary folder
in this case is the folder previously produced by the
<A HREF="#open-hook">open-hook</A> command.</P>
<P>The <EM>command</EM> should <B>not</B> remove the decompressed file. The
<EM>command</EM> should return non-zero exit status if it fails, so mutt
knows something's wrong.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
close-hook \\.gz$ "gzip -c %t > %f"
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>If the <EM>command</EM> is empty, this operation is disabled for this file
type, and the file can only be open in the read-only mode.</P>
<P>
<A HREF="#close-hook">close-hook</A> is not called when you exit
from the folder if the folder was not changed.</P>
<H3><A NAME="append-hook"></A> Append a message to a compressed mailbox</H3>
<P>Usage: <CODE>append-hook</CODE> <EM>regexp</EM> "<EM>command</EM>"</P>
<P>This command is used for saving to an existing compressed folder.
The <EM>command</EM> is the command that can be used for appending to the
folders whose names match <EM>regexp</EM>. It has the same format as in
the
<A HREF="#open-hook">open-hook</A> command.
The temporary folder in this case contains the messages that are being
appended. </P>
<P>The <EM>command</EM> should <B>not</B> remove the decompressed file. The
<EM>command</EM> should return non-zero exit status if it fails, so mutt
knows something's wrong.</P>
<P>Example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
append-hook \\.gz$ "gzip -c %t >> %f"
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>When
<A HREF="#append-hook">append-hook</A> is used, the folder is
not opened, which saves time, but this means that we can not find out
what the folder type is. Thus the default (
<A HREF="manual-6.html#mbox_type">$mbox_type</A>) type is always supposed (i.e.
this is the format used for the temporary folder).</P>
<P>If the file does not exist when you save to it,
<A HREF="#close-hook">close-hook</A> is called, and not
<A HREF="#append-hook">append-hook</A>.
<A HREF="#append-hook">append-hook</A> is only
for appending to existing folders.</P>
<P>If the <EM>command</EM> is empty, this operation is disabled for this file
type. In this case, the folder will be open and closed again (using
<A HREF="#open-hook">open-hook</A> and
<A HREF="#close-hook">close-hook</A>respectively) each time you will add to it.</P>
<H3>Encrypted folders</H3>
<P>The compressed folders support can also be used to handle encrypted
folders. If you want to encrypt a folder with PGP, you may want to use
the following hooks:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
open-hook \\.pgp$ "pgp -f < %f > %t"
close-hook \\.pgp$ "pgp -fe YourPgpUserIdOrKeyId < %t > %f"
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Please note, that PGP does not support appending to an encrypted
folder, so there is no append-hook defined.</P>
<P>If you are using GnuPG instead of PGP, you may use the following hooks
instead:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
open-hook \\.gpg$ "gpg --decrypt < %f > %t"
close-hook \\.gpg$ "gpg --encrypt --recipient YourGpgUserIdOrKeyId < %t > %f"
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P><B>Note:</B> the folder is temporary stored decrypted in the /tmp
directory, where it can be read by your system administrator. So think
about the security aspects of this.</P>
<HR>
<A HREF="manual-5.html">Next</A>
<A HREF="manual-3.html">Previous</A>
<A HREF="manual.html#toc4">Contents</A>
</BODY>
</HTML>
