Whole document tree

2. Getting Started

This section is intended as a brief overview of how to use Mutt. There are many other features which are described elsewhere in the manual. There is even more information available in the Mutt FAQ and various web pages. See the Mutt Page for more details.

The keybindings described in this section are the defaults as distributed. Your local system administrator may have altered the defaults for your site. You can always type ``?'' in any menu to display the current bindings.

The first thing you need to do is invoke mutt, simply by typing mutt at the command line. There are various command-line options, see either the mutt man page or the reference.

2.1 Moving Around in Menus

Information is presented in menus, very similar to ELM. Here is a table showing the common keys used to navigate menus in Mutt.

j or Down       next-entry      move to the next entry
k or Up         previous-entry  move to the previous entry
z or PageDn     page-down       go to the next page
Z or PageUp     page-up         go to the previous page
= or Home       first-entry     jump to the first entry
* or End        last-entry      jump to the last entry
q               quit            exit the current menu
?               help            list all keybindings for the current menu

2.2 Editing Input Fields

Mutt has a builtin line editor which is used as the primary way to input textual data such as email addresses or filenames. The keys used to move around while editing are very similar to those of Emacs.

^A or <Home>    bol             move to the start of the line
^B or <Left>    backward-char   move back one char
Esc B           backward-word   move back one word
^D or <Delete>  delete-char     delete the char under the cursor
^E or <End>     eol             move to the end of the line
^F or <Right>   forward-char    move forward one char
Esc F           forward-word    move forward one word
<Tab>           complete        complete filename or alias
^T              complete-query  complete address with query
^K              kill-eol        delete to the end of the line
ESC d           kill-eow        delete to the end ot the word
^W              kill-word       kill the word in front of the cursor
^U              kill-line       delete entire line
^V              quote-char      quote the next typed key
<Up>            history-up      recall previous string from history
<Down>          history-down    recall next string from history
<BackSpace>     backspace       kill the char in front of the cursor
Esc u           upcase-word     convert word to upper case
Esc l           downcase-word   convert word to lower case
Esc c           capitalize-word capitalize the word
^G              n/a             abort
<Return>        n/a             finish editing

You can remap the editor functions using the bind command. For example, to make the Delete key delete the character in front of the cursor rather than under, you could use

bind editor <delete> backspace

2.3 Reading Mail - The Index and Pager

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 Message Index

c               change to a different mailbox
ESC c           change to a folder in read-only mode
C               copy the current message to another mailbox
ESC C           decode a message and copy it to a folder
ESC s           decode a message and save it to a folder
D               delete messages matching a pattern
d               delete the current message
F               mark as important
l               show messages matching a pattern
N               mark message as new
o               change the current sort method
O               reverse sort the mailbox
q               save changes and exit
s               save-message
T               tag messages matching a pattern
t               toggle the tag on a message
ESC t           toggle tag on entire message thread
U               undelete messages matching a pattern
u               undelete-message
v               view-attachments
x               abort changes and exit
<Return>        display-message
<Tab>           jump to the next new message
@               show the author's full e-mail address
$               save changes to mailbox
/               search
ESC /           search-reverse
^L              clear and redraw the screen
^T              untag messages matching a pattern

Status Flags

In addition to who sent the message and the subject, a short summary of the disposition of each message is printed beside the message number. Zero or more of the following ``flags'' may appear, which mean:

D

message is deleted (is marked for deletion)

d

message have attachments marked for deletion

K

contains a PGP public key

N

message is new

O

message is old

P

message is PGP encrypted

r

message has been replied to

S

message is PGP signed, and the signature is succesfully verified

s

message is PGP signed

!

message is flagged

*

message is tagged

Some of the status flags can be turned on or off using

• set-flag (default: w)
• clear-flag (default: W)

Furthermore, the following flags reflect who the message is addressed to. They can be customized with the $to_chars variable.

+       message is to you and you only
T       message is to you, but also to or cc'ed to others
C       message is cc'ed to you
F       message is from you
L       message is sent to a subscribed mailing list

The Pager

By default, Mutt uses its builtin pager to display the body of messages. The pager is very similar to the Unix program less though not nearly as featureful.

<Return>        go down one line
<Space>         display the next page (or next message if at the end of a message)
-               go back to the previous page
n               search for next match
S               skip beyond quoted text
T               toggle display of quoted text
?               show keybindings
/               search for a regular expression (pattern)
ESC /           search backwards for a regular expression
\               toggle search pattern coloring
^               jump to the top of the message
$               jump to the bottom of the message

In addition, many of the functions from the index are available in the pager, such as delete-message or copy-message (this is one advantage over using an external pager to view messages).

Also, the internal pager supports a couple other advanced features. For one, it will accept and translate the ``standard'' nroff sequences for bold and underline. These sequences are a series of either the letter, backspace (^H), the letter again for bold or the letter, backspace, ``_'' for denoting underline. Mutt will attempt to display these in bold and underline respectively if your terminal supports them. If not, you can use the bold and underline color objects to specify a color or mono attribute for them.

Additionally, the internal pager supports the ANSI escape sequences for character attributes. Mutt translates them into the correct color and character settings. The sequences Mutt supports are:

ESC [ Ps;Ps;Ps;...;Ps m
where Ps =
0    All Attributes Off
1    Bold on
4    Underline on
5    Blink on
7    Reverse video on
3x   Foreground color is x
4x   Background color is x

Colors are
0    black
1    red
2    green
3    yellow
4    blue
5    magenta
6    cyan
7    white

Mutt uses these attributes for handling text/enriched messages, and they can also be used by an external autoview script for highlighting purposes. Note: If you change the colors for your display, for example by changing the color associated with color2 for your xterm, then that color will be used instead of green.

Threaded Mode

When the mailbox is sorted by threads, there are a few additional functions available in the index and pager modes.

^D      delete-thread           delete all messages in the current thread
^U      undelete-thread         undelete all messages in the current thread
^N      next-thread             jump to the start of the next thread
^P      previous-thread         jump to the start of the previous thread
^R      read-thread             mark the current thread as read
ESC d   delete-subthread        delete all messages in the current subthread
ESC u   undelete-subthread      undelete all messages in the current subthread
ESC n   next-subthread          jump to the start of the next subthread
ESC p   previous-subthread      jump to the start of the previous subthread
ESC r   read-subthread          mark the current subthread as read
ESC t   tag-thread              toggle the tag on the current thread
ESC v   collapse-thread         toggle collapse for the current thread
ESC V   collapse-all            toggle collapse for all threads
P       parent-message          jump to parent message in thread

Note: Collapsing a thread displays only the first message in the thread and hides the others. This is useful when threads contain so many messages that you can only see a handful of threads on the screen. See %M in $index_format. For example, you could use "%?M?(#%03M)&(%4l)?" in $index_format to optionally display the number of hidden messages if the thread is collapsed.

See also: $strict_threads.

Miscellaneous Functions

create-alias (default: a)

Creates a new alias based upon the current message (or prompts for a new one). Once editing is complete, an alias command is added to the file specified by the $alias_file variable for future use. Note: Specifying an $alias_file does not add the aliases specified there-in, you must also source the file.

check-traditional-pgp (default: ESC P)

This function will search the current message for content signed or encrypted with PGP the "traditional" way, that is, without proper MIME tagging. Technically, this function will temporarily change the MIME content types of the body parts containing PGP data; this is similar to the edit-type function's effect.

display-toggle-weed (default: h)

Toggles the weeding of message header fields specified by ignore commands.

edit (default: e)

This command (available in the ``index'' and ``pager'') allows you to edit the raw current message as it's present in the mail folder. After you have finished editing, the changed message will be appended to the current folder, and the original message will be marked for deletion.

edit-type
(default: ^E on the attachment menu, and in the pager and index menus; ^T on the compose menu)

This command is used to temporarily edit an attachment's content type to fix, for instance, bogus character set parameters. When invoked from the index or from the pager, you'll have the opportunity to edit the top-level attachment's content type. On the attachment menu, you can change any attachment's content type. These changes are not persistent, and get lost upon changing folders.

Note that this command is also available on the compose menu. There, it's used to fine-tune the properties of attachments you are going to send.

enter-command (default: ``:'')

This command is used to execute any command you would normally put in a configuration file. A common use is to check the settings of variables, or in conjunction with macros to change settings on the fly.

extract-keys (default: ^K)

This command extracts PGP public keys from the current or tagged message(s) and adds them to your PGP public key ring.

forget-passphrase (default: ^F)

This command wipes the PGP passphrase from memory. It is useful, if you misspelled the passphrase.

list-reply (default: L)

Reply to the current or tagged message(s) by extracting any addresses which match the addresses given by the lists or subscribe commands, but also honor any Mail-Followup-To header(s) if the $honor_followup_to configuration variable is set. Using this when replying to messages posted to mailing lists helps avoid duplicate copies being sent to the author of the message you are replying to.

pipe-message (default: |)

Asks for an external Unix command and pipes the current or tagged message(s) to it. The variables $pipe_decode, $pipe_split, $pipe_sep and $wait_key control the exact behaviour of this function.

resend-message (default: ESC e)

With resend-message, mutt takes the current message as a template for a new message. This function is best described as "recall from arbitrary folders". It can conveniently be used to forward MIME messages while preserving the original mail structure. Note that the amount of headers included here depends on the value of the $weed variable.

This function is also available from the attachment menu. You can use this to easily resend a message which was included with a bounce message as a message/rfc822 body part.

shell-escape (default: !)

Asks for an external Unix command and executes it. The $wait_key can be used to control whether Mutt will wait for a key to be pressed when the command returns (presumably to let the user read the output of the command), based on the return status of the named command.

toggle-quoted (default: T)

The pager uses the $quote_regexp variable to detect quoted text when displaying the body of the message. This function toggles the display of the quoted material in the message. It is particularly useful when are interested in just the response and there is a large amount of quoted text in the way.

skip-quoted (default: S)

This function will go to the next line of non-quoted text which come after a line of quoted text in the internal pager.

2.4 Sending Mail

The following bindings are available in the index for sending messages.

m       compose         compose a new message
r       reply           reply to sender
g       group-reply     reply to all recipients
L       list-reply      reply to mailing list address
f       forward         forward message
b       bounce          bounce (remail) message
ESC k   mail-key        mail a PGP public key to someone

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, and $fast_reply 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. The following options are available:

a       attach-file             attach a file
A       attach-message          attach message(s) to the message
ESC k   attach-key              attach a PGP public key
d       edit-description        edit description on attachment
D       detach-file             detach a file
t       edit-to                 edit the To field
ESC f   edit-from               edit the From field
r       edit-reply-to           edit the Reply-To field
c       edit-cc                 edit the Cc field
b       edit-bcc                edit the Bcc field
y       send-message            send the message
s       edit-subject            edit the Subject
f       edit-fcc                specify an ``Fcc'' mailbox
p       pgp-menu                select PGP options (``i'' version only)
P       postpone-message        postpone this message until later
q       quit                    quit (abort) sending the message
w       write-fcc               write the message to a folder
i       ispell                  check spelling (if available on your system)
^F      forget-passphrase       whipe PGP passphrase from memory

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.

Editing the message header

When editing the header of your outgoing message, there are a couple of special features available.

If you specify
Fcc: filename
Mutt will pick up filename just as if you had used the edit-fcc function in the compose menu.

You can also attach files to your message by specifying
Attach: filename [ description ]
where filename is the file to attach and description is an optional string to use as the description of the attached file.

When replying to messages, if you remove the In-Reply-To: field from the header field, Mutt will not generate a References: field, which allows you to create a new message thread.

Also see edit_headers.

Using Mutt with PGP

If you want to use PGP, you can specify

Pgp: [ E | S | S<id> ]

``E'' encrypts, ``S'' signs and ``S<id>'' signs with the given key, setting $pgp_sign_as permanently.

If you have told mutt to PGP encrypt a message, it will guide you through a key selection process when you try to send the message. Mutt will not ask you any questions about keys which have a certified user ID matching one of the message recipients' mail addresses. However, there may be situations in which there are several keys, weakly certified user ID fields, or where no matching keys can be found.

In these cases, you are dropped into a menu with a list of keys from which you can select one. When you quit this menu, or mutt can't find any matching keys, you are prompted for a user ID. You can, as usually, abort this prompt using ^G. When you do so, mutt will return to the compose screen.

Once you have successfully finished the key selection, the message will be encrypted using the selected public keys, and sent out.

Most fields of the entries in the key selection menu (see also $pgp_entry_format) have obvious meanings. But some explanations on the capabilities, flags, and validity fields are in order.

The flags sequence (%f) will expand to one of the following flags:

R            The key has been revoked and can't be used.
X            The key is expired and can't be used.
d            You have marked the key as disabled.
c            There are unknown critical self-signature 
             packets.

The capabilities field (%c) expands to a two-character sequence representing a key's capabilities. The first character gives the key's encryption capabilities: A minus sign (-) means that the key cannot be used for encryption. A dot (.) means that it's marked as a signature key in one of the user IDs, but may also be used for encryption. The letter e indicates that this key can be used for encryption.

The second character indicates the key's signing capabilities. Once again, a ``-'' implies ``not for signing'', ``.'' implies that the key is marked as an encryption key in one of the user-ids, and ``s'' denotes a key which can be used for signing.

Finally, the validity field (%t) indicates how well-certified a user-id is. A question mark (?) indicates undefined validity, a minus character (-) marks an untrusted association, a space character means a partially trusted association, and a plus character (+) indicates complete validity.

Sending anonymous messages via mixmaster.

You may also have configured mutt to co-operate with Mixmaster, an anonymous remailer. Mixmaster permits you to send your messages anonymously using a chain of remailers. Mixmaster support in mutt is for mixmaster version 2.04 (beta 45 appears to be the latest) and 2.03. It does not support earlier versions or the later so-called version 3 betas, of which the latest appears to be called 2.9b23.

To use it, you'll have to obey certain restrictions. Most important, you cannot use the Cc and Bcc headers. To tell Mutt to use mixmaster, you have to select a remailer chain, using the mix function on the compose menu.

The chain selection screen is divided into two parts. In the (larger) upper part, you get a list of remailers you may use. In the lower part, you see the currently selected chain of remailers.

You can navigate in the chain using the chain-prev and chain-next functions, which are by default bound to the left and right arrows and to the h and l keys (think vi keyboard bindings). To insert a remailer at the current chain position, use the insert function. To append a remailer behind the current chain position, use select-entry or append. You can also delete entries from the chain, using the corresponding function. Finally, to abandon your changes, leave the menu, or accept them pressing (by default) the Return key.

Note that different remailers do have different capabilities, indicated in the %c entry of the remailer menu lines (see $mix_entry_format). Most important is the ``middleman'' capability, indicated by a capital ``M'': This means that the remailer in question cannot be used as the final element of a chain, but will only forward messages to other mixmaster remailers. For details on the other capabilities, please have a look at the mixmaster documentation.

2.5 Forwarding and Bouncing Mail

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 following keys are bound by default:

f       forward         forward message
b       bounce          bounce (remail) message

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.

2.6 Postponing Mail

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.