NAME

Mystery Girl - A Bounce Handler For Dada Mail

DESCRIPTION

Mystery Girl intelligently handles bounces from Dada Mail list messages. Each message is first parsed. The parsed email will then be examined and an action will be taken. The examination and action are set in a collection of rules. These rules can be tweaked, added, removed and generally mucked about with.

REQUIREMENTS

It's best to get all these requirements in order before you begin.

Configuration

There's a few things you need to configure in this script, they're all at the top.

As far as required changes, that's it. We'll get to interesting optional things further down the line.

Installation

Setting up the script.

The script itself is a command line tool. This is not a CGI script, do not even attempt to call it from a web browser. You'll receive an error, each time, I promise. This isn't an error in the script, it's an error in the operator.

As such, Do not put this script in your cgi-bin. I would just make a directory in your home directory and place the script that. If you've set up Dada Mail as outlined in the Magic Book, you may want to make another directory in the .dada_files directory, called .scripts, and install this script in there.

chmod 755 dada_bounce_handler.pl

That's it as far as installation of the script.

Running the script

Since this program is a command line tool, you execute it via a command line. Again, this is not a CGI script. bold Underlined. Running the program without any arguments will have it check the mailbox for bounces, parse the messages and handle the bounces. ie:

 prompt>./dada_bounce_handler.pl

I suggest before you do that, you test the dada_bounce_handler.pl.

Testing

You can pass the --test argument to dada_bounce_handler.pl to make sure everything is workings as it should. The --test argument needs to take one of a few paramaters:

Setting The Schedule

You could run dada_bounce_handler.pl every now and again from the command line, but you'd get very sick of it and I spent an entire weekend in May to write this script to be lazy.

To accomplish that, you want to set this script to execute via a con or scheduled, job. Here's what a theoretical cron tab for this script may look like:

 0  1   *   *  * /usr/bin/perl /home/myaccount/dada_scripts/dada_bounce_handler.pl >/dev/null 2>&1

This will run the script every day around 1am. You can run this script as often as you want, just be logical. I wouldn't run this script every five minutes, that's a bit overkill.

Different hosts may have a control panel to set up crontabs, my host gives me the pleasure of the contrab command. I type in:

 prompt> crontab -e

and am launched into my favorite text editor to type in the crontab.

Telling Dada Mail to use the Bounce Handler.

You're going to have to tell Dada Mail explicitly that you want bounces to go to the bounce handler. The first step is to set the Dada List Administrator to your bounce email address. You set this in the list control panel, under Change List Information

Once you do that, you need to tell Dada Mail that you want the correct headers in your list messages to say, ``use the admin address for bounces''

Usually, this means that the Return-path header needs to be set. There are a few ways to accomplish this, some more preferable than others.

Optional Fun Things

There's a slew of optional arguments you can give to this script:

Rules, Rule!

dada_bounce_handler.pl figures out what to do with the bounce messages receives by consulting a group of rules. These rules are highly configurable, so if you need to change the behavior of this script, you don't have to change the code.

These rules are stored in the $Rules hashref. An example rule:

 {
 user_unknown => {
         Examine => {
                Message_Fields => {
                        Status => [qw(5.1.1 550 5.x.y)]
                },
                Data => { 
                        Email => 'is_valid', 
                        List  => 'is_valid',
                }
        },
        Action => { 
                unsubscribe_bounced_email => 'from_list', 
        },
}

user_unknown is the title of the rule - just a label, nothing else.

Examine holds a set of parameters that the handler looks at when trying to figure out what to do with a bounced message. This example has a Message_Fields entry and inside that, a Status entry. The Status entry holds a list of status codes. The ones in shown there all correspond to hard bounces; the mailbox probably doesn't exist. Examine also holds a Data entry, which holds the Email or List entries, or both. Their values are either 'is_valid', or 'is_invalid'.

So, to sum this all up, this rule will match a message that has Status: Message Field contaning a user unknown error code, (5.1.1, etc). The message also has to be parsed to have found a valid email and list name.

Pretty Slick, eh?

If this all matches, the Action is... acted upon. In this case, the email will be unsubscribed from the list. We could tell the bounce handler to unsubscribe the message from all the lists that Dada Mail handles, since, hey, if the email address isn't valid anymore, why wait for your other lists to find out? Changing from_list, to from_all_lists will do the trick.

I could change the line:

 unsubscribe_bounced_email => 'from_list',

to:

 mail_list_owner => 'user_unknown_message'

This will, instead of deleting the email automatically, send a message to the list owner, stating that, ``Hey, the message bounced, what do you want to do?''

Another example:

 {
 over_quota => {
         Examine => {
                Message_Fields => {
                        Status => [qw(5.2.2)]
                },
                Data => { 
                        Email => 'is_valid', 
                        List  => 'is_valid',
                }
        },
        Action => { 
                mail_list_owner => 'over_quota_message', 
        },
 }

This time, I created a list for messages that get bounced because the mailbox is full. This is still considered a hard bounce, but I don't want the subscriber removed because they haven't check their inbox during the week. In this case, the Action has been set to:

 mail_list_owner => 'over_quota_message',

Which will do what it sounds like, it'll mail the list owner a message explaining the circumstances.

Here's a schematic of all the different things you can do:

 {
 rule_name => {
         Examine => {
                Message_Fields => {
                        Status               => qw([    ]), 
                        Last-Attempt-Date    => qw([    ]), 
                        Action               => qw([    ]), 
                        Status               => qw([    ]), 
                        Diagnostic-Code      => qw([    ]), 
                        Final-Recipient      => qw([    ]), 
                        Remote-MTA           => qw([    ]), 
                        # etc, etc, etc
                        
                },
                Data => { 
                        Email => 'is_valid' | 'is_invalid' 
                        List  => 'is_valid' | 'is_invalid' 
                }
        },
        Action => { 
                           mail_list_owner           => 'user_unknown_message', 
                           mail_list_owner           => 'email_not_found_message', 
                           mail_list_owner           => 'over_quota_message', 
                           unsubscribe_bounced_email => 'from_list' | 'from_all_lists',
        },
 },

Mystery Girl also supports the use of regular expressions for matching any of the Message_Fields. To tell the parser that you're using a regular exspression, make the Message_Field key end in '_regex':

 'Final-Recipient_regex' => [(qr/RFC822/)],

Setting rules is sort of the super advanced part of the configuration, but it may come in handy.

FAQs

History

To Do

Perhaps think about making filters specifically for Postfix. They seem to have their own way of doing things, like Qmail.

Add onto that custom a filter for AOL/Compuserve/Netscape

Thanks

Thanks to: Jake Ortman Henry Hughes for some prelim bounce examples.

Thanks to Eryq ( http://www.zeegee.com ) for the amazing MIME-tools collection. It's a gnarly group of modules.

COPYRIGHT

Copyright (c) 1999 - 2005 Justin Simoni me@justinsimoni.com http://justinsimoni.com All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Parts of this script were swiped from Mail::Bounce::Qmail module, fetched from here:

http://mikoto.sapporo.iij.ad.jp/cgi-bin/cvsweb.cgi/fmlsrc/fml/lib/Mail/Bounce/Qmail.pm

The copyright of that code stated:

Copyright (C) 2001,2002,2003 Ken'ichi Fukamachi All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Thanks Ken'ichi