Mutt Mail Agent Icon

Gary Johnson's Mutt Page

Latest Updates

Updated my e-mail address.


My Mutt Files

This is a synopsis of the scripts and configuration files I have written originally for use with mutt 1.2i and on an HP-UX 10.20 system, and which I now use with mutt 1.5.17 on a SunOS 5.8 system. More detail about their application is given in later sections of this page.

Handling MIME Attachments

Mutt uses the mailcap file and the auto_view configuration command to determine how to display MIME attachments. This is discussed more fully in section 5, Mutt's MIME Support, of the mutt manual.

I have configured my mailcap file to use a number of commercial and free software programs along with some scripts of my own to allow me to easily view all of the attachment types I normally receive.

I generally include three entries for each MIME Content-Type:

<Content-Type>; <X viewer>; test=RunningX
<Content-Type>; <text viewer>
<Content-Type>; <text converter>; copiousoutput

The first entry specifies the viewer to be invoked from mutt's attachment menu when X is running. RunningX is a program by Brandon Long that detects whether X is running by trying to open the DISPLAY. If for any reason you don't want to use RunningX, the following is a less-reliable alternative that works in most cases.

<Content-Type>; <X viewer>; test=sh -c 'test $DISPLAY'

The second mailcap entry specifies the text-based viewer to be invoked from mutt's attachment menu.

The third entry specifies the program to be used to convert the attachment contents to plain text for automatic viewing while in mutt's pager. The Content-Type must also be included in an auto_view command in your muttrc file.

Mutt uses the copiousoutput field to indicate that the viewer is non-interactive and can be used to automatically view attachments within the pager as well as from the attachment menu. Conversely, mutt uses the absence of the copiousoutput field to indicate that the viewer is interactive and can be used only from the attachment menu. Therefore, any lines with the copiousoutput field should be last among those of a given content-type. This usage is an extension of that specified in RFC 1524.

Viewing HTML Attachments

This part of my mailcap file handles HTML attachments.

# From the attachment menu, if X is running, HTML attachments are sent
# to netscape for viewing; otherwise, they are sent to w3m.  For
# in-line viewing, the HTML is converted to text. 
text/html;                      mutt_netscape %s; test=RunningX
text/html;                      w3m %s; nametemplate=%s.html
text/html;                      w3m -dump %s; nametemplate=%s.html; \
mutt_netscape is a script that displays the attachment using Netscape. If Netscape is already running, it opens a new window; otherwise, it launches a new Netscape.

w3m is a terrific text-based web and file browser. It does a very good job of rendering tables.

This line from my muttrc tells mutt to automatically display text/html content when opening messages from the index menu.

auto_view text/html

Viewing PDF Attachments

I originally used these lines in my mailcap file to handle PDF attachments.

application/pdf;                mutt_bgrun acroread %s; test=RunningX
application/pdf;                pdftotext %s -; copiousoutput
mutt_bgrun is a script that launches the specified viewer in the background.

Acroread is Adobe's Adobe Reader, a graphical viewer for PDF files. You can download it for free. An alternative would be xpdf. I just prefer acroread.

Pdftotext, a PDF to text conversion utility, is part of the Xpdf package.

Some problems with my invocation of acroread were reported a while back in comp.mail.mutt (2 May 2002, "viewing pdf attachments with acroread"). While I had never observed any problems with this, it was reported that if mutt_bgrun was run when acroread was already running, the second invocation of acroread would simply notify the first acroread that there was a new file to be opened, then would return immediately. Mutt_bgrun would proceed to delete its temporary file before acroread had a chance to open it.

The solution proposed was to invoke acroread with the +useFrontEndProgram option. (Refer to acroread -helpall.) Consequently, I modified mutt_bgrun to allow options to be passed to the viewer and changed my mailcap entry for acroread to:

application/pdf; mutt_bgrun acroread +useFrontEndProgram %s; test=RunningX

More recent versions of acroread such as 7.0 no longer support the +useFrontEndProgram option. For these versions, I have changed my mailcap entry to this:

application/pdf; mutt_bgrun acroread -tempFile -openInNewWindow %s; test=RunningX

I don't use an auto_view command for PDF attachments because it usually takes a long time to convert them to text. If I want to view them, I use the attachment menu instead.

Viewing MS Office Attachments

Note: This section discusses using QuickView Plus for Unix to display certain attachment types. QuickView Plus is not available for the OS I'm using currently, so I run OpenOffice remotely on a Linux system instead. I have not yet updated the text of this section accordingly, but the concepts discussed here still apply, and I still use word2text and related scripts to convert MS Office attachments to plain text for in-line display.

I receive a lot of memos formatted as Word documents at work, along with an occasional Excel spreadsheet or PowerPoint presentation. The company I work for has a license for QuickView Plus for Unix which does a fair job of rendering MS Office and other odd attachment types on an X display.

For in-line viewing of such attachments within mutt, which I find much more convenient than using QuickView Plus, and the only way to view them when accessing my work mailbox from home, I wrote a couple of scripts that convert these attachments to text. They use programs that convert Word, Excel and PowerPoint attachments to HTML, then use w3m to convert the HTML to plain text, along with a little shell and Perl glue.

This part of my mailcap file handles MS Office attachments.

# The following Microsoft application MIME attachments are viewed from
# the attachment menu using QuickView Plus for UNIX. 
application/msword;             mutt_bgrun qvpview %s; test=RunningX
application/msword;             word2text %s; copiousoutput
application/vnd.msword;         mutt_bgrun qvpview %s; test=RunningX
application/vnd.msword;         word2text %s; copiousoutput
application/excel;              mutt_bgrun qvpview %s; test=RunningX
application/excel;              excel2text %s; copiousoutput
application/msexcel;            mutt_bgrun qvpview %s; test=RunningX
application/msexcel;            excel2text %s; copiousoutput
application/;       mutt_bgrun qvpview %s; test=RunningX
application/;       excel2text %s; copiousoutput
application/x-excel;            mutt_bgrun qvpview %s; test=RunningX
application/x-excel;            excel2text %s; copiousoutput
application/x-msexcel;          mutt_bgrun qvpview %s; test=RunningX
application/x-msexcel;          excel2text %s; copiousoutput
application/ms-Excel;           mutt_bgrun qvpview %s; test=RunningX
application/ms-Excel;           excel2text %s; copiousoutput
application/;  mutt_bgrun qvpview %s; test=RunningX
application/;  ppt2text %s; copiousoutput
application/x-mspowerpoint;     mutt_bgrun qvpview %s; test=RunningX
application/x-mspowerpoint;     ppt2text %s; copiousoutput
application/ppt;                mutt_bgrun qvpview %s; test=RunningX
application/ppt;                ppt2text %s; copiousoutput
qvpview is QuickView Plus for UNIX. An alternative for GNU/Linux users would be StarOffice, e.g.,
application/msword;             mutt_bgrun StarOffice %s; test=RunningX

word2text is a script that uses wvHtml to convert from Word to HTML and w3m to convert from HTML to plain text. wvHtml is part of the wvWare application, formerly known as mswordview, and distributed with the wv library.

excel2text is a script that uses xlhtml to convert Excel spreadsheets to HTML and w3m to convert from HTML to plain text.

ppt2text is a script that uses ppthtml, distributed with xlhtml, to convert PowerPoint presentations to HTML and w3m to convert from HTML to plain text. While it is not very useful for viewing PowerPoint slides with a lot of graphical content, it is very useful when people send simple textual messages such as meeting announcements as PowerPoint slides.

These lines from my muttrc tell mutt to automatically display these content types when opening messages from the index menu.

auto_view application/msword application/vnd.msword
auto_view application/excel application/ms-Excel application/msexcel
auto_view application/ application/x-excel
auto_view application/x-msexcel
auto_view application/ application/x-mspowerpoint application/ppt

Another alternative for viewing Word documents is Antiword. It converts Word documents to text and to PostScript. I haven't used it a lot, but it seems to do a nice job and is fast.

For the sake of completeness, I should also mention catdoc, which convert Word documents to plain text. The last version I tried was 0.90 and its formatting was not as good as Antiword. However, it is now (2003-12-31) at version 0.93.3 and seems to have some additional features such as handling RTF files, so it might be worth checking out.

The author of catdoc has also written a program, xls2csv, to extract the data from Excel files and output it in CSV (comma-separated values) format. I haven't tried it yet. It should be fairly simple to format CSV data as an HTML table for display by a browser, if someone was so inclined.

Viewing Octet-Stream Attachments

Note: This section applies only to mutt versions 1.4.x and earlier. The mime_lookup feature was added to the 1.5.x branch on 2002-01-24 and included in the 1.5.1 development release, making the workarounds discussed here unnecessary for the 1.5.x versions.

When a mail user agent (MUA) doesn't know the proper content-type to use for an attachment, it is expected by RFC 2045 to create an attachment of type application/octet-stream. Some MUAs (notably Microsoft Outlook) rely on filename extensions to identify the content-type of attachments, so they are not always properly configured to assign the correct Content-Type and instead assign Content-Type application/octet-stream to all attachments.

Since mutt was designed to work with properly designed and configured MUAs, it does not use filename extensions to further identify the content of application/octet-stream attachments. A couple of solutions have been developed to work around this "limitation" of mutt.

  1. External programs to be used as viewers for octet-stream attachments. These programs use the filename extension of the attachment to look up the appropriate viewer in their internal tables and then invoke that viewer on the attachment.

    This solution has the advantage that no modification to mutt itself is needed, but the disadvantages that:

    1. The user has two databases of viewers to maintain;
    2. Mailcap fields such as copiousoutput must be selected before the external program is invoked and before the "actual" content-type is determined and therefore are not always selected as the user would like.

  2. A patch to mutt that allows mutt to use the mime.types file to look up the content-type associated with the filename extension of an octet-stream attachment. Mutt then uses this derived content-type along with the mailcap file to find the appropriate viewer.
I originally used the external program approach, but have since applied the patch, which I think is a much better solution.

External Programs for Viewing Octet-Stream Attachments

I first used Dave Pearson's popular mutt.octet.filter for this purpose. However, it was designed to produce text output for in-line viewing of attachments and I wanted something that would handle graphical viewers as well, so I hacked mutt.octet.filter to create mutt_octet_view. mutt_octet_view doesn't handle as many file types as mutt.octet.filter, but it does a better job for me of handling all the types that I receive.

This is how my mailcap file handled octet-stream attachments when using mutt_octet_view.

application/octet-stream;       mutt_octet_view -x %s; test=RunningX
application/octet-stream;       mutt_octet_view -v %s
application/octet-stream;       mutt_octet_view %s; copiousoutput

This line from my muttrc told mutt to automatically display octet-stream content when opening messages from the index menu.

auto_view application/octet-stream

A Patch for Viewing Octet-Stream Attachments

Ulf Erikson wrote the original lookup octet-stream patch for mutt-1.2.5 and posted it to the mutt-dev list in May, 2001. Brian Foley has made some improvements to the patch since then including extending it to handle any Content-Type, not just application/octet-stream. It has also been renamed mime_lookup and updated for mutt-1.4i. The latest version of the patch is available from this mirror of Ulf Erikson's Geocities Patches page. You can also get a local copy of the patch here.

Once you've applied the patch, simply add this line to your muttrc:

mime_lookup application/octet-stream

Unpacking TNEF (winmail.dat) Attachments

TNEF is Transport Neutral Encapsulation Format, a Microsoft format for encapsulating attachments. Such attachments have Content-Type: application/ms-tnef and usually the name "winmail.dat". A single TNEF attachment may contain several files, but oftentimes it contains only RTF (Rich Text Format) formatting and highlighting enhancements to the text portion of the message. The ytnef links page has links to further information about TNEF.

There are a number of programs available for unpacking TNEF attachments. The two most prominent ones seem to be tnef and ytnef. Others may be found by searching (formerly There is also a Perl module available from CPAN (Comprehensive Perl Archive Network) that looks intriguing, but I haven't checked it out.

Unfortunately, there seem to be no tools currently available to let mutt display files encapsulated within TNEF attachments as easily as it can those within MIME attachments. The tnef program, however, allows you to see the names of any files in a TNEF attachment and to selectively unpack them, so this is what I use. The man page even tells you how to use tnef with mutt.

Here is what I have in my mailcap file:

application/ms-tnef; tnef -w %s
When you open a TNEF attachment from mutt's attachments menu, if the attachment contains only RTF enhancements to the text message, nothing will happen. If the TNEF attachment contains one or more files, then tnef will issue a prompt like this
extract filename?
for each file it finds. Answering y will cause the file to be extracted to the current directory.

Running Attachment Viewers in the Background

Mutt runs as a single process, in a single thread. One consequence of this is that if a viewer is run from the attachment menu with a mailcap entry like this,

image/*; xv %s
mutt will wait for the viewer (e.g., xv) to exit before continuing execution and in the mean time mutt's user interface will be "frozen".

A solution to this would seem to be to simply specify in the mailcap line that the viewer run in the background:

image/*; xv %s &

The trouble with this is that as soon as mutt resumes executing, it first overwrites the temporary file it passed to the viewer with NULs, then unlinks (deletes) the file. Even if the viewer continues to hold the file open so that the operating system doesn't actually delete the file until the viewer exits, mutt has overwritten the file's contents. This may still work if the operating system has given the viewer enough time to run and load the file before resuming mutt, but it isn't a very reliable solution and won't work at all with viewers that are slow to start.

A better solution is this:

image/*; xv %s & sleep 5
This gives the viewer five seconds to load the file before mutt resumes and deletes it. The trouble with this is that some viewers can be really slow to start--around 20 seconds. Using the worst-case sleep time means waiting that long after launching the viewer before you can get back to using mutt.

To avoid that, I wrote the mutt_bgrun script, which runs viewers in the background. It copies mutt's temporary file to its own temporary file, runs the viewer in the background and exits "immediately". It also removes its temporary file when the viewer exits. Use mutt_bgrun in your mailcap file like this:

image/*; mutt_bgrun xv %s

It has been pointed out to me that with some operating systems and some shells, any viewers still running in the background when mutt exits will be sent the SIGHUP signal and will terminate. I haven't been able to reproduce this myself, so I haven't tested this solution, but I think modifying mutt_bgrun with the addition of a trap command as shown below should fix this problem. I would like to hear from anyone who has experienced this problem and can verify that my solution works.

    trap '' SIGHUP
    "$viewer" $options "$tmpfile"
    rm -f "$tmpfile"
    rmdir "$tmpdir"
) &

Using W3m with Mutt

Besides being very good for viewing or converting to text HTML-encoded message content, w3m is a good alternative to urlview for viewing URLs embedded in plain text messages. Simply pipe the message to w3m like this,
or redefine in your muttrc the macro that by default invokes urlview:
macro index \cB |w3m\n "call w3m to extract URLs out of a message"
macro pager \cB |w3m\n "call w3m to extract URLs out of a message"
When in w3m, type a colon (:) to have w3m convert strings that look like URLs to links.

I find this especially useful for viewing messages such as the Slashdot Headlines that contain links to other articles, so I use w3m as the pager for these messages by using message-hooks in my muttrc like this:

message-hook ~A                                 'set pager="builtin"'
message-hook '~f ""'           'set pager="w3m"'
message-hook '~s "slashdot headlines"'          'set pager="w3m"'
message-hook '~s "the register update"'         'set pager="w3m"'
message-hook '~s "YOUR LINUX TODAY NEWSLETTER"' 'set pager="w3m"'

Hiding Long To: and Cc: Lists

Do you ever receive messages with really long distribution lists so that you have to scroll down a few pages before you can read the message? mail-to-filter is a Perl script that compresses To: and Cc: lists that are longer than two lines, replacing the second and subsequent lines with the message,
[<lines> lines deleted]
The latest version also truncates lines in the To: and Cc: lists to the width of the terminal (using the environment variable $COLUMNS) because I started receiving horribly long lines in such lists from Outlook users.

The script compresses the To: and Cc: lists only when it determines that mutt is weeding headers. Otherwise, it passes the lists unaltered. One can then choose between seeing the full and compressed lists just as one chooses between seeing all headers and just the unignored headers, by using mutt's display-toggle-weed function.

The script decides that mutt is not weeding headers if it finds "From " at the start of the first line of the message, which may only work with mbox-formatted mailboxes. If this is a problem for anyone, it shouldn't be difficult to modify the script to use some other commonly ignored field, such as Received:, as the "weed" indicator.

It also deletes spaces at the ends of lines (except sigdashes, "-- ") because these can cause lines to wrap unnecessarily when displayed. This feature isn't related to compressing the distribution lists, but this script was a convenient place to implement it.

mail-to-filter is intended to be used as a filter ahead of the pager rather than in a procmail recipe since I don't like altering my incoming mail. To use mail-to-filter, add this line to your muttrc:

set display_filter=mail-to-filter

Managing Message Expiry Dates

I wanted to be able to tag certain messages with expiration dates so that after the messages were no longer of interest I could easily identify and delete them. Mutt already provides part of the solution to this. Mutt recognizes the Expires: header and has an ~E pattern which matches messages that have expired, that is, whose Expires: dates and times are earlier than the current date and time. What is missing from mutt is a means to easily add an Expires: header to a message or to modify an existing Expires: header.

A patch that adds this capability to mutt was written by Omen Wild and posted to the mutt-dev list on February 5, 2002. It appeared that most if not all the functionality of the patch (patch-1.5.0.ow.edit-expires.4) could be achieved with a shell script, macros and existing patterns, so I wrote a shell script which borrowed heavily from the script included with the patch and I wrote two macros to invoke it from the index and pager views.

macro index ,E ':set editor=mutt_expires_editor<Return><edit>:set editor=vim<Return>' "set Expires: header"
macro pager ,E ':set editor=mutt_expires_editor<Return><edit>:set editor=vim<Return><next-entry><clear-flag>N' "set Expires: header"
Each macro uses mutt's <edit> function to edit the current message using the shell script, mutt_expires_editor. In addition, the pager macro marks the new, edited message as read. (Thanks to Tom Eliaz for that suggestion.) The script prompts the user for the expiration date and/or time. Just hitting <Enter> will use a default date; the string "never" will remove the current Expires: header, if any.

The script uses 'formail' (part of the procmail package) to edit the message headers and GNU 'date' (part of the GNU coreutils package) to translate the date and/or time entered by the user to a date and time in the RFC 822 format required by the Expires: header. One nice feature of GNU 'date' is that it accepts relative dates such as "tomorrow" and "next week" and incomplete dates such as "Aug 23".

The 'mutt_expires_editor' script should work on any system that has 'formail' and GNU 'date', such as GNU/Linux. I use to use mutt on an HP-UX 10.20 system which didn't have either 'formail' or GNU 'date', but which did have 'gcc'. Both programs were easy to compile. Note that the script contains two versions of an "echo" command, one for HP-UX and SunOS and one, commented out, for GNU/Linux. If you use GNU/Linux, you'll have to change the comments around.

Finally, I put this line in my muttrc file to highlight expired messages that haven't been tagged for deletion:

color index magenta default '~E !~D'

References and Other Mutt-related Resources

Valid HTML 3.2! Best viewed with any browser
Gary Johnson, gjohnson AT spocom DOT com
URL: <>
Last modified: 2013-10-28 08:12:30