Procmail

From Apis Networks Wiki

This article is obsolete. We now use maildrop for message filtering. You still use procmail by adding the following to .mailfilter within your home directory:

to "|/usr/bin/procmail"

Brief Introduction

procmail is a filtering agent designed to modify and sort incoming e-mails based upon pre-defined sets of criteria called "recipes". These recipes are stored inside a user's home directory called .procmailrc. Every e-mail received for a user's account checks for the presence of .procmailrc and attempts to use the recipes stored within to filter to possibly modify the headers sent or to deliver in a different IMAP folder.

Recipes

As was stated before, procmail's logic operates on recipes inside the .procmailrc file. Here's a fundamental example to help you get started.

:0
* ^X-Spam-Flag: YES
/dev/null

:0 declares the start of a recipe and everything following it leading up to the next :0 will be part of that recipe. Think of it as an if (expr) { /* do stuff */ } construct you normally see in programming languages. :0 marks the if declaration and the lines prefixed with * mark conditions. Everything following the * lines are actions to perform if the condition is met. You could nest other conditions, just like a nested if (expr) { if (expr a) { /* do something */ } else { /* do something */ } } construct in C. In procmail, it would look like

:0
* ^X-Spam-Flag: YES
{
        :0
        * ^FROMsally@spamsite.com
        /dev/null
        :0E
        $HOME/Possible_Spam
}

Here, we look for an X-Spam-Flag marked in the header (see SpamAssassin). If that is matched, then we'll check if the e-mail is from sally@spamsite.com. Note the capitalization of FROM. This is a special token that unrolls and looks for any fields related to the From field in an e-mail and is your best case in deciphering an e-mail's sender. If the e-mail is sent by sally@spamsite.com, then we will delete the e-mail silently. /dev/null is a special location that points to a system device on the server. If you use that as an IMAP folder, then any e-mail sent there will be sent to the void — or deleted in other words. If the condition of the sender sally@spamsite.com is not met, then the else block is invoked, denoted by the special E flag in the recipe declaration. $HOME is a special variable that evaluates to your home directory, which is the base location for all of your files on the server.

Every condition denoted by the * matches a specific line in the header of an e-mail. Two special imaginary headers exist, TO and FROM, which unroll the addresses of the respective party to simplify matching. This comes in use later when filtering mailing lists or setting up GMail-style aliases.

Logging

So you're confused that procmail isn't placing your e-mail into the right IMAP mailbox? Or it has completely bypassing a rule? You can log procmail's actions by including

LOG=$HOME/procmail.log

at the top of your .procmailrc file. This will log some mildly-verbose details about e-mails and the rules they triggered, but if you want to see how procmail analzyed the file fully, including all conditions met or not met, then you will need to enable verbose logging, include

VERBOSE=YES

at the top of your .procmailrc to turn verbose logging. This comes in particular use when you're running a dry-run on your new procmail recipe and would like to verify that your script is correct. Turning on verbose logging not only gives you details of potential errors in your recipe, but it also includes a list of all conditions analyzed and met/unmet.

Testing A Recipe

To test a recipe out on your inbox, run

formail -s procmail procmailscriptfile < someimapinbox

The -s flag supplied to formail splits the IMAP inbox into individual messages and pipes it over to the program procmail in this case. procmail takes an argument that is the recipe file and applies it to the messages. From there, you can check the terminal output, if VERBOSE is set to YES or read the logfile supplied in the LOGFILE variable of the procmail recipe.

Advanced Filtering Topics

See the supplemental entry for more advanced filtering topics.

External Links

• Procmail Documentation Project - a comprehensive set of documentation for using procmail effectively.
• Procmail Tips - a general question and answers set to aid in commonly used techniques in procmail.