All text patterns for searching and matching in Mutt must be specified as 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.
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: ``\\''. For more information, see the section on searching below.
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.
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.
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.
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 not in the list. For example, the regular expression [0123456789] 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.
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:
Alphanumeric characters.
Alphabetic characters.
Space or tab characters.
Control characters.
Numeric characters.
Characters that are both printable and visible. (A space is printable, but not visible, while an ``a'' is both.)
Lower-case alphabetic characters.
Printable characters (characters that are not control characters.)
Punctuation characters (characters that are not letter, digits, control characters, or space characters).
Space characters (such as space, tab and formfeed, to name a few).
Upper-case alphabetic characters.
Characters that are hexadecimal digits.
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, [[:digit:]] is equivalent to [0-9].
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:
A collating symbols is a multi-character collating element enclosed in ``[.'' and ``.]''. For example, if ``ch'' is a collating element, then [[.ch.]] is a regexp that matches this collating element, while [ch] is a regexp that matches either ``c'' or ``h''.
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, [[=e=]] is a regexp that matches any of ``è'', ``é'' and ``e''.
A regular expression matching a single character may be followed by one of several repetition operators:
The preceding item is optional and matched at most once.
The preceding item will be matched zero or more times.
The preceding item will be matched one or more times.
The preceding item is matched exactly n times.
The preceding item is matched n or more times.
The preceding item is matched at most m times.
The preceding item is matched at least n times, but no more than m times.
Two regular expressions may be concatenated; the resulting regular expression matches any string formed by concatenating two substrings that respectively match the concatenated subexpressions.
Two regular expressions may be joined by the infix operator ``|''; the resulting regular expression matches any string matching either subexpression.
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.
Note: If you compile Mutt with the GNU rx package, the following operators may also be used in regular expressions:
Matches the empty string at either the beginning or the end of a word.
Matches the empty string within a word.
Matches the empty string at the beginning of a word.
Matches the empty string at the end of a word.
Matches any word-constituent character (letter, digit, or underscore).
Matches any character that is not word-constituent.
Matches the empty string at the beginning of a buffer (string).
Matches the empty string at the end of a buffer.
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.
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:
~A all messages
~b PATTERN messages which contain PATTERN in the message body
~B PATTERN messages which contain PATTERN in the whole message
~c USER messages carbon-copied to USER
~C PATTERN message is either to: or cc: PATTERN
~D deleted messages
~d [MIN]-[MAX] messages with ``date-sent'' in a Date range
~E expired messages
~e PATTERN message which contains PATTERN in the ``Sender'' field
~F flagged messages
~f USER messages originating from USER
~h PATTERN messages which contain PATTERN in the message header
~i ID message which match ID in the ``Message-ID'' field
~L PATTERN message is either originated or received by PATTERN
~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
~x PATTERN messages which contain PATTERN in the `References' field
~z [MIN]-[MAX] messages with a size in the range MIN to MAX
Where PATTERN, USER, ID, and SUBJECT are regular expressions.
Logical AND is performed by specifying more than one criterion. For example:
~t mutt ~f elkins
would select messages which contain the word ``mutt'' in the list of recipients and that have the word ``elkins'' in the ``From'' header field.
Mutt also recognizes the following operators to create more complex search patterns:
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''.
!(~t mutt|~c mutt) ~f elkins
Mutt supports two types of dates, absolute and relative.
Absolute. Dates must 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:
Limit to messages matching: ~d 20/1/95-31/10
If you omit the minimum (first) date, and just specify ``-DD/MM/YY'', all messages before the given date will be selected. If you omit the maximum (second) date, and specify ``DD/MM/YY-'', all messages after 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.
Relative. This type of date is relative to the current date, and may be specified as:
offset is specified as a positive number with one of the following units:
y years m months w weeks d days
Example: to select messages less than 1 month old, you would use
Limit to messages matching: ~d <1m
Note: all dates used when searching are relative to the
local time zone, so unless you change the setting of your
$index_format to include a
%[...] format, these are not the dates shown
in the main index.
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 ``control-T'' by default. Or you can select individual messages by hand using the ``tag-message'' function, which is bound to ``t'' by default. See searching for Mutt's searching syntax.
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 next operation will be applied to all tagged messages if that operation can be used in that manner. If the $auto_tag variable is set, the next operation applies to the tagged messages automatically, without requiring the ``tag-prefix''.
A hook 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 hook consists of a regular expression along with a configuration option/command. See
for specific details on each type of hook available.Hooks that act upon messages (send-hook, save-hook, fcc-hook) are
evaluated in a slightly different manner. For the other types of hooks, a
regular expression. But in dealing with messages a
finer grain of control is needed for matching since for different purposes
you want to match different criteria.
Mutt allows the use of the search pattern language for matching messages in hook commands. This works in exactly the same way as it would when limiting or searching the mailbox, except that you are restricted to those operators which match information from the envelope of the message (i.e. from, to, cc, date, subject, etc.).
For example, if you wanted to set your return address based upon sending mail to a specific address, you could do something like:
send-hook '~t ^me@cs\.hmc\.edu$' 'my_hdr From: Mutt User <user@host>'
However, it is not required that you write the pattern to match using the full searching language. You can still specify a simple regular expression like the other hooks, in which case Mutt will translate your pattern into the full language, using the translation specified by the $dfault_hook variable. The pattern is translated at the time the hook is declared, so the value of $dfault_hook that is in effect at that time will be used.
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 $query_command variable, you specify the wrapper command to use. For example:
set query_command = "mutt_ldap_query.pl '%s'"
The wrapper script should accept the query on the command-line. It should return a one line message, than 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.
An example multiple response output:
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
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 messages to mail, start a new query, or have a new query appended to the current responses.
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.
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 $mbox_type variable.
mbox. 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:
From me@cs.hmc.edu Fri, 11 Apr 1997 11:44:56 PST
to denote the start of a new message (this is often referred to as the ``From_'' line).
MMDF. This is a variant of the mbox format. Each message is surrounded by lines containing ``ˆAˆAˆAˆA'' (four control-A's).
MH. A radical departure from mbox and MMDF, 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. Note: Mutt
detects this type of mailbox by looking for either .mh_sequences
or .xmhcache (needed to distinguish normal directories from MH
mailboxes). Mutt does not update these files, yet.
Maildir. The newest of the mailbox formats, used by the Qmail MTA (a replacement for sendmail). Similar to MH, except that it adds three subdirectories of the mailbox: tmp, new and cur. 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.
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.
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). This is accomplished through the use of the lists command in your muttrc.
Now that Mutt knows what your mailing lists are, it can do several things, the first of which is the ability to show the list name in the index menu display. This is useful to distinguish between personal and list mail in the same mailbox. In the $index_format 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).
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 index menu and pager, helps reduce the clutter by only replying to the mailing list addresses instead of all recipients.
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 $reply_to variable to help decide which address to use. If set, 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 unset, the ``Reply-To'' field will be used when present.
Lastly, Mutt has the ability to sort the mailbox into threads. 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.
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.
To support this, there are two variables. $dsn_notify is used to request receipts for different results (such as failed message, message delivered, etc.). $dsn_return 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.
If Mutt was compiled with POP3 support (by running the configure script with the --enable-pop flag), it has the ability to fetch your mail from a remote server for local browsing. When you invoke the fetch-mail function (default: G), Mutt attempts to connect to pop_host and authenticate by logging in as pop_user. After the connection is established, you will be prompted for your password on the remote system.
Once you have been authenticated, Mutt will fetch all your new mail and place it in the local spoolfile. After this point, Mutt runs exactly as if the mail had always been local.
Note: The POP3 support is there only for convenience, and it's rather limited. If you need more functionality you should consider using a specialized program, such as fetchmail
If Mutt was compiled with IMAP support (by running the configure script with the --enable-imap flag), it has the ability to work with folders located on a remote imap server.
You can access the remote inbox by selecting the folder
{imapserver}inbox, where imapserver is the name of the IMAP
server and inbox 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 {imapserver}path/to/folder where
path/to/folder is the path of the folder you want to access
relative to your home directory.
Note: The IMAP support is in a very early state and quite unstable at the moment. If you need a more stable way to access your IMAP folder, consider using a specialized program, such as fetchmail.