Back to main page

The Quick-N-Dirty Guide to Getmail

(As of 20 October 2004, this particular guide is listed in
FreeBSD's /usr/ports/UPDATING as a reference.)

The aim of this QND guide is to get you up and running quickly with getmail. There will be far more how than why here.

Getmail is aimed to be a replacement for fetchmail. Many people consider it faster and more secure than fetchmail. My personal experience has been that it seems to at least be a little faster.

Getmail will require that python is installed. Most distributions have python so it is rare that this will be problem.

Note that this page is about getmail version 4.x. Debian and some others, as of October 2004 are still using version 3.x For information about 3.x please see my getmail 3.x page.

1.) Do you have getmail?

As fetchmail is still far better known, the chances are that you don't have getmail installed. However, it never hurts to check. At a command line type
which getmail

If you get a response like /usr/bin/getmail or /usr/local/bin/getmail, you can skip to step 3. Otherwise, continue with step 2.

2.) Installing getmail

First follow the instructions in the QND software guide for information on getting and installing getmail. If it's not included with your distribution (RedHat based systems don't have it) then go to the getmail homepage. They have a tar.gz file. They sometimes have rpms, but they're usually dated. However, my more detailed page on getmail gives instructions and links on installing a current rpm. (One was just accepted into Fedora stable)

FreeBSD's ports or Gentoo's portage will install getmail for you. If you've downloaded the tarball then untar it somewhere and cd to the directory that is created. Using version 4.2.2 as an example

tar xzf getmail-4.2.2.tar.gz
cd getmail-4.2.2
python build
python install

4.) Configuring getmail

FreeBSD and Gentoo both include a getmailrc-example file. In FreeBSD it's in /usr/local/share/examples/getmail/getmailrc-examples. In Gentoo, the last time I looked, it was in /usr/share/examples/getmail/getmailrc-examples. By default, getmail looks for a .getmail/getmailrc file in the user's home directory. So, as the user who will be using getmail (for this example, we'll assume that the getmailrc-example is in /usr/local/share/getmail
mkdir .getmail
cp /usr/local/share/examples/getmail/getmailrc-examples .getmail/getmailrc

Now we will edit our new getmailrc file. This example is for FreeBSD which has maildrop in /usr/local/bin. Some Linux distributions will have maildrop in /usr/bin. If that's the case then change the /usr/local/bin/maildrop to /usr/bin/maildrop.

(I use maildrop as my example because it's what I use--many others use procmail.)

For user john, with an email address of, email user name john, a password of 1234, and an ISP whose pop server name is, we would like our getmailrc to look like this.

verbose = 0
delete = True

type = SimplePOP3Retriever
server =
username = john
password = 1234

type = MDA_external
path = /usr/local/bin/maildrop
unixfrom = True

Note the line for maildrop. The above is for a FreeBSD machine, where maildrop is in /usr/local/bin. If you are using Linux, then it may be in /usr/bin. To find out simply type at a command prompt

which maildrop

and adjust your getmailrc accordingly. (The same holds for procmail, or any other external MDA)

As gmail becomes more and more popular, folks are often making use of its pop download feature, enabling you to receive gmail email on your normal client.

As gmail uses SSL the above configuration would work save for the SimplePop3Retriever line. For a gmail account, you want, assuming your gmail account is with a password of 1234

verbose = 0
delete = True

type = SimplePOP3SSLRetriever
server =
username = john
password = 1234

type = MDA_external
path = /usr/local/bin/maildrop
unixfrom = True

If one examines the docs, (/usr/local/share/doc/getmail/configuration.txt or configuration.html in FreeBSD) one finds that the default for the unixfrom line is false. However, some MDA's expect it. Both maildrop and procmail need it.

5.) Testing Getmail

To test getmail simply type at a command prompt
getmail -v

If all is set up successfully, you should see it polling your pop server and retrieving your mail. Unlike fetchmail, getmail doesn't have a daemon option, so if you want it to poll your server at regular intervals, you will have to add a crontab entry. The man 5 crontab page explains things rather clearly, but a quick example.

On most systems, a user can edit his own crontab. So as user john you would do

crontab -e

This will open up your default text editor. Type in

*/5 * * * * /usr/local/bin/getmail

That will set getmail to run every 5 minutes. If you wish to change the interval you want to change the 5 to however many minutes you wish.

If for some reason, you aren't able to edit your own crontab then as root or with root privilege

crontab -eu john
*/5 * * * * /usr/local/bin/getmail

One quick note of warning. If you wanted the job to run every two hours and made a crontab like this

* */2 * * * 

it would be running every minute. The correct way to specify the job to run every two hours would be

0 */2 * * *

With FreeBSD 5.1 and 5.2, I ran into an issue where getmail would either not run at all, or I would get a permission denied from crontab. This is mentioned on getmail's home page. The problem is that crontab has a shorter $PATH. The file (in FreeBSD) /usr/local/bin/getmail is simply a shell script. The top line read

#!/usr/bin/env python2.3 

I had to change that to reflect the complete path to python

#!/usr/bin/env /usr/local/bin/python2.3 

This solved that problem.

(As of late October, in FreeBSD that has been fixed. The first line gives the path to python and needs no modification.)

As of December, 2004, in FreeBSD 5.3 at least, if you have the most recent versions of both getmail and python, a DeprecationWarning regarding use of the "strict" keyword gets printed. If you have sendmail or another MTA sending you system messages, this will send you a message each time getmail retrieves mail.

To avoid this warning you can edit your crontab to read

*/5 * * * * /usr/local/bin/getmail > /dev/null 2>&1

With getmail 4.x each account will need a separate getmailrc file. If, for instance, one gets their home and work mail, create a getmailrc-home and getmailrc-work rc file. Put both of them in your .getmail directory and then, call getmail with

getmail -rgetmailrc-home -rgetmailrc-work

Note that getmail is going to look in ~/.getmail for the rcfiles, so as long as both files are in that directory, you don't need to specify their full path. They don't have to be called getmailrc-home, etc, you can simply call them home and work. If you don't specify the rcfile name, getmail looks for a ~/.getmail/getmailrc file. Therefore, whether you call it getmailrc-home or just home, you'll get an error unless you specify the rcfile as shown above.

If there is a non-fatal error, it will retrieve the mail but not delete it from the server. This is probably a Good Thing.(TM) For example, in ArchLinux, where I don't have spamassassin, I used my .mailfilter file from my BSD box, where I do have it. Getmail noted that there was no spamassissin and it went to STDERR. The message was retrieved, but remained on the server.

Another time, back when I used procmail, the issue was a simple mistype in my rc.lists, having put a capital letter o instead of the numeral zero in one of my rules. Procmail noted this, wrote to STDERR and getmail would retrieve the messages, but not delete them from the server, retrieving them each time it polled for mail.

In each case, once I fixed the error in my MDA's configuration file getmail deleted messages from the server as I wished.


Getmail home page
A more detailed page of mine
My getmail-3.x page
man crontab
man 5 crontab

Back to main page