Gentoo Logo
Gentoo Logo Side

QuickStart Guide to Mutt E-Mail


1. Introduction to E-Mail

If you're not a fan of e-mail clients with fancy graphical user interfaces, or if you would just like to experiment with other mail clients before deciding which is best for you, here is the easy way to begin using these powerful command line tools:


These programs are not only powerful and highly customizable but also small and efficient. Once you are up and running with this e-mail system you will be amazed at what you can do with it.

Because this is a quick start guide, we will eliminate the Mail Transfer Agent (MTA) such as sendmail, postfix or exim. This means no complex MTA configuration. It also eliminates using port 25 for mail service.

We can do this because fetchmail can force the mail it retrieves directly to a Mail Delivery Agent (MDA) rather than forwarding to port 25. And we don't need to use a complex MTA for plain old outgoing mail delivery.

These are the programs you will need to get your e-mail running.

Code Listing 1.1

# emerge fetchmail procmail mutt nbsmtp

Then just four quick steps to configure files and you will be up and running a brand new e-mail system.

Important: After each step you can run a test to make sure the setup is correct. This means you will have a complete working e-mail system when you are done.

2. Fetchmail

Fetchmail fetches mail from remote servers and forwards it to your local machines delivery system. To use it you need to set up a .fetchmailrc file in your home directory like this example:

Code Listing 2.1: Sample .fetchmailrc

poll  protocol pop3 user "myname" password "mypasswd" 

Once you have created a .fetchmailrc file, you have to change the permissions on the file using the chmod command. The file must be readable only by the file owner. Set the permissions with the following command:

Code Listing 2.2

# chmod 600 .fetchmailrc

To see it in action use the verbose mode (-v). To fetch all messages use -a. And you must use the option -m to tell fetchmail to send the mail to procmail.

Warning: While testing, it's a good idea to tell fetchmail to keep (-k) the mail on the remote server in case something goes wrong and you need to fetch it again.

Run it now to see fetchmail in action!

Code Listing 2.3: Fetchmail test #1

# fetchmail -akv -m "/usr/bin/procmail -d %T" 

Once you have a working mail system you can set this as a cron job or put it in a monitor like gkrellm. Fetchmail can also run in a daemon mode for which you specify a polling interval in seconds.

3. Procmail

Procmail is the processor that filters the mail that is forwarded to it by fetchmail. It also acts as the MDA to deliver mail to your mailboxes where mutt (your e-mail client) can read it.

To use procmail you need to create a .procmailrc file in your home directory. For our quickstart purposes we will use a very simple .procmailrc that will filter mail from three gentoo mailing lists into these mailboxes:gentoo-dev, gentoo-user and gentoo-announce

Note: The procmail filter rules are called recipies and i have also included recipies to filter out some spam.

Code Listing 3.1: Sample .procmailrc

MAILDIR=$HOME/MuttMail                ##you better make sure it exists
LOGABSTRACT=no only used for debugging
##recipe lines begin with :0
##dont put comments on recipe lines
##disable a recipe with the false condition !
##condition lines begin with * and regex is your friend
##conditions are anded and everything after * is fed straight into egrep
##one action line follows the conditions, in this case it is a mailbox name

#catch duplicates using formail
:0 Whc: .msgid.lock
| $FORMAIL -D 16384 .msgid.cache

:0 a

#people we always allow mail from
* ^From:.*(craig\@hotmail|renee\

#now flush some spam out 
* ^Subject:.*(credit|cash|money|debt|sex|sale|loan)

#no more html messages
* ^Content-Type:.*html

#now put my mail lists into mailboxes
* ^List-Id:.*gentoo-user

* ^List-Id:.*gentoo-dev

* ^List-Id:.*gentoo-announce

#catch any other gentoo mail
* ^From:.*

* ^From:.*@freshmeat\.net

# Last rule: mail that gets    #
# this far goes in default box #  
* .*

# End of file

Note: It is only required to make the MAILDIR $HOME/MuttMail as Procmail will create all the mailbox files as needed in this directory using the names on the action lines. For some useful links visit

You can now test .procmailrc by re-running the fetchmail command we tested in the first step. Remember the -k option to keep all mail on the remote server so we have it if we need to rerun it.

Code Listing 3.2: Procmail test #1

# fetchmail -akv -m "/usr/bin/procmail -d %T" 

Now that fetchmail and procmail have run, go to $HOME/MuttMail and read your messages with less or your file manager.

4. Mutt e-mail client

Mutt is used to read and compose e-mail. It is powerful and highly customizable but also small and efficient.

Mutt supports reading and writing of four different mailbox formats: mbox, MMDF, MH and Maildir. The mailbox type is autodetected. In our case we are using the mbox format, where all messages of a mailbox are stored in a single file.

Mutt also has the ability to work with folders located on a remote IMAP server. See IMAP Support in section 4.11 of the Mutt manual and the Mutt web site

When you emerged mutt in the first step it installed a configurationfile in /etc/mutt/Muttrc. You also need to create a .muttrc file in your home directory.

Code Listing 4.1: Sample .muttrc

// Be sure to read the fine Mutt manual in /usr/share/doc/mutt*
// Any settings here override the system settings in /etc/mutt/Muttrc

# cp /etc/mutt/Muttrc ~/.muttrc
# nano -w .muttrc
set pager_context=1                        
set pager_index_lines=6                 #show a mini-index in pager
set menu_scroll  
set pgp_verify_sig=no                   #dont show pgp in pager
set status_on_top                       #put status line at top
set sort=threads                        #sort by message threads in index

set status_format=" %r %b %f %n      Del %d      Msgs %m %l %> (%P)"
set pager_format="%-10.10i %[!%a %b %d %R]"
set date_format="!%H:%M %a %d %b     "
set index_format="%4C %Z %[%b%d] %-15.15F %s"
set folder_format="%2C %t %8s %d %N %f"

#set sendmail="/usr/bin/nbsmtp -d -h -f"

#set from="default-mailaddress"         #set to your from address
#set realname="myname"

set record="$HOME/MuttMail/sent"        #sent mail is saved here
set delete=yes                          #delete without prompting
set include=yes				#quote msg in reply	
set fast_reply=yes			#no prompting on reply
set beep=no				#no noise
set markers=no				#no + on wrapped lines
set confirmappend=no			#no prompt for save to =keep           
set to_chars=" +TCF"                    #no L for mail_list

set folder = $HOME/MuttMail
mailboxes =gentoo-user
mailboxes =gentoo-dev
mailboxes =gentoo-announce
mailboxes =gentoo   
mailboxes =freshmeat
mailboxes =duplicates
mailboxes =default  
mailboxes =sent     
mailboxes =friends  
mailboxes =junk
mailboxes =spam
mailboxes =keep

save-hook .* =keep                      #default mbox to (s)ave mail is =keep
subscribe gentoo-user gentoo-dev        #subscribed to these lists

bind pager h display-toggle-weed	#toggle headers with h key

# simulate the old url menu
macro index \cb |urlview\n 'call urlview to extract URLs out of a message'
macro pager \cb |urlview\n 'call urlview to extract URLs out of a message'

#run fetchmail by hitting key of G
macro index G "!fetchmail -a -m 'procmail -d %T'\r"
macro pager G "!fetchmail -a -m 'procmail -d %T'\r"  

#use to edit .muttrc and then source restart necessary
macro generic ,sm ":source $HOME/.muttrc\r"
macro generic \cj "!rxvt -bg wheat -e joe $HOME/.muttrc\r"

# default list of header fields to weed out when displaying mail
#ignore them all and then unignore what you want to see
ignore *
unignore  Date To From: Subject X-Mailer Organization User-Agent
hdr_order Date From To Subject X-Mailer User-Agent Organization 

##your Mutt has to have some colors
##these are for four levels of quoted text
##they override the system settings in /etc/mutt/Muttrc

#color quoted green  default
color quoted1 magenta blue 
#color quoted2 yellow default
#color quoted3 red default   
#color signature cyan cyan   

#this color setup is copied from /etc/mutt/Muttrc.color
#comment it out if you want the default colors in /etc/mutt/Muttrc
# Je vois la vie en rose :-) 
color	hdrdefault	brightcyan	blue
color	header		brightwhite	blue "^from:"
color   header          brightwhite    	blue   "^subject:"

color   quoted          brightgreen     blue
color   signature       brightwhite	blue

color   indicator       blue	        green

color   error           red             black
mono    error           bold
color   status          black cyan
mono	status		bold
color   tree            yellow   	blue

color   tilde           brightmagenta   blue
color	body	brightwhite		blue	"[-a-z_0-9.]+@[-a-z_0-9.]+"
mono    body    bold                    "[-a-z_0-9.]+@[-a-z_0-9.]+"
color   body            brightyellow    black   "^Good signature"
mono    body            bold                    "^Good signature"
color   body            brightwhite     red     "^Bad signature from.*"
mono    body            bold                    "^Bad signature from.*"
color   normal          white		blue
color	message		green	black
color	attachment	brightgreen	blue

# End of file...but it can go on and on and on....:)

For the record, this is just a sample .muttrc. There are many more options that you can configure, gpg settings for instance. Have a look at for more examples and help.

You are now ready to test your .muttrc

Code Listing 4.2: Testing .muttrc

# mutt -y

This should open Mutt with a menu showing the Mutt mailboxes that you created in Test 2 when you ran the fetchmail command.

Type the ? for help in navigating the Mutt Mailboxes.


The final step is setting up nbsmtp the 'No-Brainer SMTP' used to send mail to your SMTP server. This setup is the easiest of all, as it only requires adding an entry in your .muttrc file.

domain: The domain you want nbsmtp to say it belongs to. This will almost invariably be the same as the domain in your e-mail address.

from@addr: This is the address you want nbsmtp to say the message is from. Note that this can be different than the "From:" line in your MUA.

host: This is the smtp server you are sending to.

Code Listing 5.1: Adding smtp support

# nano -w .muttrc
set sendmail="/usr/bin/nbsmtp -d -h -f"

You are now ready to send a message. So in the Mutt pager or index hit the m key to compose a test message to send to your e-mail address. Mutt will use the value of the EDITOR or VISUAL for the composition editor unless you set editor= in the .muttrc. When you are done composing hit y to send your message. If there are no errors you will see 'sending mail' followed by 'New mail in =sent'

Remember in .muttrc we have set where to save sent mail with set record="$HOME/MuttMail/sent"

Now to complete the test, run fetchmail again to get all your mail and verify you have received the message you sent to your e-mail address. When you find your test message, hit the h key to toggle a view of all the headers and see the complete mail transfer path.

Note: There is one more program you probably want to add called urlview. This extracts the urls in message texts and sends them to your browser.

Code Listing 5.2

# emerge urlview 

Then create ~/.urlview by copying the configuration file from /usr/share/doc/urlview*/ and setting your browser command.

You now have a powerful and highly customizable mail system. So read all the manuals and docs and find the many user configuration files available on the web with 'google' procmailrc and muttrc.

6. Alternative SMTP: msmtp

For those who are required to submit their username and password to their SMTP server before sending mail, msmtp is a simple alternative.

Code Listing 6.1: Installing msmtp

# emerge msmtp

Configure msmtp by creating a ~/.msmtprc file, filling in your SMTP server's information. Remember to set the permissions to a secure value!

Code Listing 6.2: Configuring msmtp

# nano -w .msmtprc
account default
#see man page for more auth options
auth login 
user your_username
password your_password
#If your SMTP Server supports TLS encryption, uncomment the next line

Now set the permissions of the file to a secure value:

Code Listing 6.3: Setting the permissions for the configuration file

# chmod 600 .msmtprc

Finally, edit or add the following line to .muttrc

Code Listing 6.4: Using msmtp with Mutt

# nano -w .muttrc
set sendmail="/usr/bin/msmtp"

Fire up mutt and send yourself a test email to see if it worked! See the msmtp man page for more options and another example.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.
Updated October 16, 2004
Mike Polniak

Ken Nowack

John Hitchings

Summary:  This guide shows you how to begin using the powerful command line tools for e-mail: fetchmail, procmail, mutt, nbsmtp, msmtp.
The Gentoo Linux Store
Copyright 2001-2004 Gentoo Foundation, Inc. Questions, Comments, Corrections? Email