The Mutt E-Mail Client

http://www.mutt.org/

To subscribe to one of the following mailing lists, send a message with the word subscribe in the body to list-name-request@mutt.org.

Note: all messages posted to mutt-announce are automatically forwarded to mutt-users, so you do not need to be subscribed to both lists.

For a list of mirror sites, please refer to http://www.mutt.org/download.html.

Visit channel #mutt on irc.freenode.net to chat with other people interested in Mutt.

See the newsgroup comp.mail.mutt.

Mutt is Copyright (C) 1996-2005 Michael R. Elkins <me@cs.hmc.edu> and others

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 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.

Information is presented in menus, very similar to ELM, see Table 2.1, “Most common navigation keys” for common keys used to navigate menus in Mutt.

Similar to many other mail clients, there are two modes in which mail is read in Mutt. The first is the index of messages in the mailbox, which is called the ``index'' in Mutt. The second mode is the display of the message contents. This is called the ``pager.''

The next few sections describe the functions provided in each of these modes.

The bindings shown in Table 2.8, “Most common mail sending keys” are available in the index for sending messages.

Bouncing a message sends the message as is to the recipient you specify. Forwarding a message allows you to add comments or modify the message you are forwarding. These items are discussed in greater detail in the next chapter ``Forwarding and Bouncing Mail.''

Mutt will then enter the compose menu and prompt you for the recipients to place on the ``To:'' header field. Next, it will ask you for the ``Subject:'' field for the message, providing a default if you are replying to or forwarding a message. See also $askcc, $askbcc, $autoedit, $bounce, $fast_reply, and $include for changing how Mutt asks these questions.

Mutt will then automatically start your $editor on the message body. If the $edit_headers variable is set, the headers will be at the top of the message in your editor. Any messages you are replying to will be added in sort order to the message, with appropriate $attribution, $indent_string and $post_indent_string. When forwarding a message, if the $mime_forward variable is unset, a copy of the forwarded message will be included. If you have specified a $signature, it will be appended to the message.

Once you have finished editing the body of your mail message, you are returned to the compose menu providing the functions show in Table 2.9, “Most common compose menu keys”.

Note: The attach-message function will prompt you for a folder to attach messages from. You can now tag messages in that folder and they will be attached to the message you are sending. Note that certain operations like composing a new mail, replying, forwarding, etc. are not permitted when you are in that folder. The %r in $status_format will change to a 'A' to indicate that you are in attach-message mode.

Bouncing and forwarding let you send an existing message to recipients that you specify. Bouncing a message uses the $sendmail command to send a copy to alternative addresses as if they were the message's original recipients. Forwarding a message, on the other hand, allows you to modify the message before it is resent (for example, by adding your own comments). The default key bindings are shown in Table 2.11, “Message forwarding/bouncing keys”.

Forwarding can be done by including the original message in the new message's body (surrounded by indicating lines) or including it as a MIME attachment, depending on the value of the $mime_forward variable. Decoding of attachments, like in the pager, can be controlled by the $forward_decode and $mime_forward_decode variables, respectively. The desired forwarding format may depend on the content, therefore $mime_forward is a quadoption which, for example, can be set to ``ask-no''.

The inclusion of headers is controlled by the current setting of the $weed variable, unless $mime_forward is set.

Editing the message to forward follows the same procedure as sending or replying to a message does.

At times it is desirable to delay sending a message that you have already begun to compose. When the postpone-message function is used in the compose menu, the body of your message and attachments are stored in the mailbox specified by the $postponed variable. This means that you can recall the message even if you exit Mutt and then restart it at a later time.

Once a message is postponed, there are several ways to resume it. From the command line you can use the ``-p'' option, or if you compose a new message from the index or pager you will be prompted if postponed messages exist. If multiple messages are currently postponed, the postponed menu will pop up and you can select which message you would like to resume.

Note: If you postpone a reply to a message, the reply setting of the message is only updated when you actually finish the message and send it. Also, you must be in the same folder with the message you replied to for the status of the message to be updated.

See also the $postpone quad-option.

An initialization file consists of a series of commands. Each line of the file may contain one or more commands. When multiple commands are used, they must be separated by a semicolon (;).

set realname='Mutt user' ; ignore x-

The hash mark, or pound sign (``#''), is used as a ``comment'' character. You can use it to annotate your initialization file. All text after the comment character to the end of the line is ignored. For example,

my_hdr X-Disclaimer: Why are you listening to me? # This is a comment

Single quotes (') and double quotes (") can be used to quote strings which contain spaces or other special characters. The difference between the two types of quotes is similar to that of many popular shell programs, namely that a single quote is used to specify a literal string (one that is not interpreted for shell variables or quoting with a backslash [see next paragraph]), while double quotes indicate a string for which should be evaluated. For example, backtics are evaluated inside of double quotes, but not for single quotes.

\ quotes the next character, just as in shells such as bash and zsh. For example, if want to put quotes ``"'' inside of a string, you can use ``\'' to force the next character to be a literal instead of interpreted character.

set realname="Michael \"MuttDude\" Elkins"

``\\'' means to insert a literal ``\'' into the line. ``\n'' and ``\r'' have their usual C meanings of linefeed and carriage-return, respectively.

A \ at the end of a line can be used to split commands over multiple lines, provided that the split points don't appear in the middle of command names.

It is also possible to substitute the output of a Unix command in an initialization file. This is accomplished by enclosing the command in backquotes (``). For example,

my_hdr X-Operating-System: `uname -a`

The output of the Unix command ``uname -a'' will be substituted before the line is parsed. Note that since initialization files are line oriented, only the first line of output from the Unix command will be substituted.

Both environment variables and mutt variables can be accessed by prepending ``$'' to the name of the variable. For example,

set record=+sent_on_$HOSTNAME

will cause mutt to save outgoing messages to a folder named ``sent_on_kremvax'' if the environment variable HOSTNAME is set to ``kremvax.'' (See $record for details.)

Mutt expands the variable when it is assigned, not when it is used. If the value of a variable on the right-hand side of an assignment changes after the assignment, the variable on the left-hand side will not be affected.

The commands understood by mutt are explained in the next paragraphs. For a complete list, see the command reference.

Usage: group [ -group name [ ... ] ] [ -rx EXPR [ ... ] ] [ -addr EXPR [ ... ] ]

group is used to directly add either addresses or regular expressions to the specified group or groups. The different categories of arguments to the group command can be in any order. The flags -rx and -addr specify what the following strings (that cannot begin with a hyphen) should be interpreted as: either a regular expression or an email address, respectively.

These address groups can also be created implicitely by the alias, lists, subscribe and alternates commands by specifying the optional -group option.

Once defined, these address groups can be used in patterns to search for and limit the display to messages matching a group.

Usage: ungroup [ -group name [ ... ] ] [ * | [ [ -rx EXPR [ ... ] ] [ -addr EXPR [ ... ] ] ]

ungroup is used to remove addresses or regular expressions from the specified group or groups. The syntax is similar to the group command, however the special character * can be used to empty a group of all of its contents.

Usage: alias [ -group name [ ... ] ] key address [ , address, ... ]

It's usually very cumbersome to remember or type out the address of someone you are communicating with. Mutt allows you to create ``aliases'' which map a short string to a full address.

Note: if you want to create an alias for more than one address, you must separate the addresses with a comma (``,'').

The optional -group argument to alias causes the aliased address(es) to be added to the named group.

To remove an alias or aliases (``*'' means all aliases):

unalias [ * | key ... ]

alias muttdude me@cs.hmc.edu (Michael Elkins)
alias theguys manny, moe, jack

Unlike other mailers, Mutt doesn't require aliases to be defined in a special file. The alias command can appear anywhere in a configuration file, as long as this file is sourced. Consequently, you can have multiple alias files, or you can have all aliases defined in your muttrc.

On the other hand, the create-alias function can use only one file, the one pointed to by the $alias_file variable (which is ˜/.muttrc by default). This file is not special either, in the sense that Mutt will happily append aliases to any file, but in order for the new aliases to take effect you need to explicitly source this file too.

For example:

source /usr/local/share/Mutt.aliases
source ~/.mail_aliases
set alias_file=~/.mail_aliases

To use aliases, you merely use the alias at any place in mutt where mutt prompts for addresses, such as the To: or Cc: prompt. You can also enter aliases in your editor at the appropriate headers if you have the $edit_headers variable set.

In addition, at the various address prompts, you can use the tab character to expand a partial alias to the full alias. If there are multiple matches, mutt will bring up a menu with the matching aliases. In order to be presented with the full list of aliases, you must hit tab with out a partial alias, such as at the beginning of the prompt or after a comma denoting multiple addresses.

In the alias menu, you can select as many aliases as you want with the select-entry key (default: RET), and use the exit key (default: q) to return to the address prompt.

Usage: bind map key function

This command allows you to change the default key bindings (operation invoked when pressing a key).

map specifies in which menu the binding belongs. Multiple maps may be specified by separating them with commas (no additional whitespace is allowed). The currently defined maps are:

key is the key (or key sequence) you wish to bind. To specify a control character, use the sequence \Cx, where x is the letter of the control character (for example, to specify control-A use ``\Ca''). Note that the case of x as well as \C is ignored, so that \CA, \Ca, \cA and \ca are all equivalent. An alternative form is to specify the key as a three digit octal number prefixed with a ``\'' (for example \177 is equivalent to \c?). In addition, key may be a symbolic name as shown in Table 3.1, “Symbolic key names”.

key does not need to be enclosed in quotes unless it contains a space (`` '').

function specifies which action to take when key is pressed. For a complete list of functions, see the reference. The special function noop unbinds the specified key sequence.

The charset-hook command defines an alias for a character set. This is useful to properly display messages which are tagged with a character set name not known to mutt.

The iconv-hook command defines a system-specific name for a character set. This is helpful when your systems character conversion library insists on using strange, system-specific names for character sets.

Usage: folder-hook [!]regexp command

It is often desirable to change settings based on which mailbox you are reading. The folder-hook command provides a method by which you can execute any configuration command. regexp is a regular expression specifying in which mailboxes to execute command before loading. If a mailbox matches multiple folder-hook's, they are executed in the order given in the muttrc.

Note: if you use the ``!'' shortcut for $spoolfile at the beginning of the pattern, you must place it inside of double or single quotes in order to distinguish it from the logical not operator for the expression.

Note that the settings are not restored when you leave the mailbox. For example, a command action to perform is to change the sorting method based upon the mailbox being read:

folder-hook mutt set sort=threads

However, the sorting method is not restored to its previous value when reading a different mailbox. To specify a default command, use the pattern ``.'':

folder-hook . set sort=date-sent

Usage: macro menu key sequence [ description ]

Macros are useful when you would like a single key to perform a series of actions. When you press key in menu menu, Mutt will behave as if you had typed sequence. So if you have a common sequence of commands you type, you can create a macro to execute those commands with a single key.

menu is the map which the macro will be bound. Multiple maps may be specified by separating multiple menu arguments by commas. Whitespace may not be used in between the menu arguments and the commas separating them.

key and sequence are expanded by the same rules as the key bindings. There are some additions however. The first is that control characters in sequence can also be specified as ^x. In order to get a caret (`^'') you need to use ^^. Secondly, to specify a certain key such as up or to invoke a function directly, you can use the format <key name> and <function name>. For a listing of key names see the section on key bindings. Functions are listed in the reference.

The advantage with using function names directly is that the macros will work regardless of the current key bindings, so they are not dependent on the user having particular key definitions. This makes them more robust and portable, and also facilitates defining of macros in files used by more than one user (e.g., the system Muttrc).

Optionally you can specify a descriptive text after sequence, which is shown in the help screens.

Note: Macro definitions (if any) listed in the help screen(s), are silently truncated at the screen width, and are not wrapped.

If your terminal supports color, you can spice up Mutt by creating your own color scheme. To define the color of an object (type of information), you must specify both a foreground color and a background color (it is not possible to only specify one or the other).

object can be one of:

foreground and background can be one of the following:

foreground can optionally be prefixed with the keyword bright to make the foreground color boldfaced (e.g., brightred).

If your terminal supports it, the special keyword default can be used as a transparent color. The value brightdefault is also valid. If Mutt is linked against the S-Lang library, you also need to set the COLORFGBG environment variable to the default colors of your terminal for this to work; for example (for Bourne-like shells):

set COLORFGBG="green;black"
export COLORFGBG

Note: The S-Lang library requires you to use the lightgray and brown keywords instead of white and yellow when setting this variable.

Note: The uncolor command can be applied to the index object only. It removes entries from the list. You must specify the same pattern specified in the color command for it to be removed. The pattern ``*'' is a special token which means to clear the color index list of all entries.

Mutt also recognizes the keywords color0, color1, …, colorN-1 (N being the number of colors supported by your terminal). This is useful when you remap the colors for your display (for example by changing the color associated with color2 for your xterm), since color names may then lose their normal meaning.

If your terminal does not support color, it is still possible change the video attributes through the use of the ``mono'' command:

where attribute is one of the following:

Usage: [un]ignore pattern [ pattern ... ]

Messages often have many header fields added by automatic processing systems, or which may not seem useful to display on the screen. This command allows you to specify header fields which you don't normally want to see.

You do not need to specify the full header field name. For example, ``ignore content-'' will ignore all header fields that begin with the pattern ``content-''. ``ignore *'' will ignore all headers.

To remove a previously added token from the list, use the ``unignore'' command. The ``unignore'' command will make Mutt display headers with the given pattern. For example, if you do ``ignore x-'' it is possible to ``unignore x-mailer''.

``unignore *'' will remove all tokens from the ignore list.

For example:

# Sven's draconian header weeding
ignore *
unignore from date subject to cc
unignore organization organisation x-mailer: x-newsreader: x-mailing-list:
unignore posted-to:

Usage: [un]alternates [ -group name [ ... ] ] regexp [ regexp ... ]

With various functions, mutt will treat messages differently, depending on whether you sent them or whether you received them from someone else. For instance, when replying to a message that you sent to a different party, mutt will automatically suggest to send the response to the original message's recipients -- responding to yourself won't make much sense in many cases. (See $reply_to.)

Many users receive e-mail under a number of different addresses. To fully use mutt's features here, the program must be able to recognize what e-mail addresses you receive mail under. That's the purpose of the alternates command: It takes a list of regular expressions, each of which can identify an address under which you receive e-mail.

The -group flag causes all of the subsequent regular expressions to be added to the named group.

The unalternates command can be used to write exceptions to alternates patterns. If an address matches something in an alternates command, but you nonetheless do not think it is from you, you can list a more precise pattern under an unalternates command.

To remove a regular expression from the alternates list, use the unalternates command with exactly the same regexp. Likewise, if the regexp for an alternates command matches an entry on the unalternates list, that unalternates entry will be removed. If the regexp for unalternates is ``*'', all entries on alternates will be removed.