A Procmail Primer

The purpose of this page is to get you started on procmail. I can’t provide ALL the details about this program, but I can provide enough to get you started and can point you to other sources of information. Please let me know if you find any errors in this information or outdated links. I strive to maintain this page and keep it up-to-date :)

About Procmail

Procmail, written by Stephen R. van den Berg and Philip A. Guenther, is a powerful e-mail filtering program that can be used to process your messages either as they arrive or after they have been placed in the appropriate mail directory. I personally use procmail to process the numerous mailing lists I’m on, filter out spam, forward messages, and have also used it to auto-respond to certain messages

What you need

To use procmail you must have the following:

A shell account on a UN*X server (Linux, Solaris, BSD, etc)
A secure shell client, such as OpenSSH

Desktop Email Clients

If you are a user of Microsoft Outlook, Mozilla Thunderbird, or other non-UN*X based program, then this tutorial will not be of much use to you unless you have access to a UNIX shell account. The good news is that these clients all include their own filtering mechanisms and I invite you to consult your user documentation or help menus. In theory, you can use procmail to tag specific e-mail and then let your own client’s filter process that mail based on the tag … a useful tool for handling SPAM.

Setting up Procmail

You will need to create a file called .procmailrc in your home directory. Open it up with your favorite editor and be sure to set up the following variables. When specifying file or directory locations, be sure to use the absolute path!

`SHELL`	Location of your shell. `/bin/sh` should suffice
`PMDIR`	Location of your procmail folder. If in doubt, create a directory, `$HOME/.procmail` and set `PMDIR` accordingly
`LOGFILE`	Log file for procmail. I use `$PMDIR/log`
`MAILDIR`	Directory where mail is stored. Consult your mail user agent documentation for where you should set this.

Invoking Procmail

If your mail server is set up to use procmail as a mail delivery agent, then you don’t have to do anything, it’s there for you to use. Otherwise, you will need to invoke procmail via a .forward file in your home directory.

Example .forward

"|IFS=' '&&p=/usr/bin/procmail&&test -f $p&&exec $p -Yf-||exit 75 #YOUR_USERNAME"

Creating Filter Recipes

All recipes should be placed in your .procmailrc file. For your convenience, I’ve set up an example procmailrc file that you are welcome to download and modify to your liking. If you are subscribed to multiple mailing lists, you can create a separate file with all your mailing list recipes in it and then include the following line in your .procmailrc file:

Including a recipe file

INCLUDERC = <path to your other rc file>

Example procmail recipe

An Example procmail recipe

# The afd mailing list
:0:
* ^Sender:.owner-afd@ict.org
in-afd

The first line is just a comment line. All comments are preceded with #'s, which should be familiar to anyone who’s done shell programming.

The second line marks the beginning of a recipe. The final : at the end of the line indicates that the destination file (i.e. in-afd) is locked.

The third line is a condition. These start with a leading +*: and use standard regular expressions to search the header of the message. here, it is looking for any mail with the sender line as "owner-afd@ict.org".

Other examples

# Filter anything from president@whitehouse.gov
* ^From:.president@whitehouse.gov

# Filter anything sent to ArthurDent
* ^To:.ArthurDent@Hitchhikers.Org

# Filter on subject line
* ^Subject:.*MAKE MONEY FAST*

You get the general idea. The last line is merely the file to be filtered to. Unless the destination file contains an absolute path, then the default location is location specified by $DEFAULT.

Scoring

Procmail also provides a scoring mechanism. This allows you to assign a weight to a particular pattern that procmail finds. When the score meets a certain threshold, procmail will then invoke the corresponding action.

An example recipe that uses scoring

:0 Bhb
* -400^0
*   20^1 ^*This.is.not.spam*
*   40^1 ^*to.be.removed*
*  100^2 ^*sent.in.compliance*
in-spam

The first line tells procmail to only search the body of the message, not the header. Since procmail won’t take any action until the score is positive, we set the initial score to -400. As procmail greps through the body of the message, the following rules are applied:

For every instance of "This is not spam", a point score of 20 is added.
For every instance of "to be removed", a point score of 40 is added.
For the first instance of "sent in compliance", a point score of 100 is added. For the second instance of "sent in compliance" encountered, a point score of 200 is added.

When the score reaches 0 (remember, we set it initially to "-400"), then procmail will filter the e-mail into the in-spam folder. As you can see, the procmail scoring facility is a powerful means of processing your mail based on content.

Other examples

Let’s say you want to filter any mail sent to momlist@mom.org. Try the following:

:0:
* (^To:.|Cc:.*)momlist@mom.org
in-momlist

You can use regular expressions to set up yur conditionals (in fact, procmail uses egrep to pattern match!). If you’re familiar with grep or perl, you should not have any problems writing recipes.

Some handy recipes

Tired of having to write a procmail recipe for 'every' mailing list you’re on? Here’s a sample recipe for catching all those Yahoo! Groups you’re subscribed to and filtering them into their own separate folders based on Group Name

# Yahoo! groups
:0w
* ^Delivered-To:.mailing.list.\/[^@]+@yahoogroups.com
{
        LISTNAME=${MATCH}
        :0w
        * LISTNAME??^\/[^@]+
        in-ygrp-${MATCH}
}

GNU Mailman is a popular mailing list management software package used by individuals, organizations, and corporations around the world. Subscribers to GNU Mailman managed mailing lists can use a modified form of the following recipe to properly filter list email (note use of the X-BeenThere header):

# Redhat mailing list traffic
:0w
* ^X-BeenThere:.\/[^@]+@redhat.com
{
        LISTNAME=${MATCH}
        :0w
        * LISTNAME??^\/[^@]+
        $MAIL/.in-redhat-${MATCH}/
}

ezmlm is another popular mailing list manager which takes advantage of the high-speed qmail mail transport agent. Subscribers can modify the following generic ezmlm recipe to taste:

# Generic ezmlm filter (modified from
# http://spacepants.org/conf/dot.procmailrc)

:0w
* ^Mailing-list: contact .*; run by ezmlm
* ^List-Post: [<]mailto:\/.*
{
        LISTID=$MATCH

        :0
        * LISTID ?? ^ *\/[^@]*
        {
                LIST=$MATCH

                :0
                * LISTID ?? ^.*@\/[^>\.]*
                $MAIL/.in-$MATCH-$LIST/
        }
}

Additional Resources

Official Procmail Home Page (link appears broken)
Procmail basics
The procmail(1) manual page