NAME

Mail::Audit - Library for creating easy mail filters

SYNOPSIS

        use Mail::Audit;
        my $mail = Mail::Audit->new;
        $mail->pipe("listgate p5p") if ($mail->from =~ /perl5-porters/);
        $mail->accept("perl) if ($mail->from =~ /perl/);
        $mail->reject("We do not accept spam") if looks_like_spam($mail);
        $mail->ignore if $mail->subject =~ /boring/i;
        ...

DESCRIPTION

procmail is nasty. It has a tortuous and complicated recipe format, and I don't like it. I wanted something flexible whereby I could filter my mail using Perl tests.

Mail::Audit was inspired by Tom Christiansen's audit_mail and deliverlib programs. It allows a piece of email to be logged, examined, accepted into a mailbox, filtered, resent elsewhere, rejected, and so on. It's designed to allow you to easily create filter programs to stick in a .forward file or similar.

CONSTRUCTOR

new(%options)

The constructor reads a mail message from STDIN (or, if the data option is set, from an array reference) and creates a Mail::Audit object from it, to be manipulated by the following methods.

Other options include the accept, reject or pipe keys, which specify subroutine references to override the methods with those names.

You may also specify log => $logfile to write a debugging log; you can set the verbosity of the log with the loglevel key, on a scale of 1 to 4. If you specify a log level without a log file, logging will be written to /tmp/you-audit.log where you is replaced by your user name. If you specify noexit => 1>>, Mail::Audit will not exit after delivering the mail, but continue running your filter.

METHODS

accept($where)

You can choose to accept the mail into a mailbox by calling the accept method; with no argument, this accepts to /var/spool/mail/you. The mailbox is opened append-write, then locked LOCK_EX, the mail written and then the mailbox unlocked and closed. If Mail::Audit sees that you have a maildir style system, where /var/spool/mail/you is a directory, it'll deliver in maildir style.

If this isn't how you want local delivery to happen, you'll need to override this method.

reject($reason)

This rejects the email; it will be bounced back to the sender as undeliverable. If a reason is given, this will be included in the bounce.

ignore

This merely ignores the email, dropping it into the bit bucket for eternity.

rblcheck([$timeout])

Attempts to check the mail headers with the Relay Blackhole List. Returns false if the headers check out fine or the query times out, returns a reason if the mail is considered spam.

pipe($program)

This opens a pipe to an external program and feeds the mail to it.

tidy

Tidies up the email as per Mail::Internet

get($header)

Retrieves the named header from the mail message.

body

Returns an array of lines in the body of the email.

header

Returns the header as a single string.

resend($address)

Bounces the email in its entirety to another address.

ATTRIBUTES

The following attributes correspond to fields in the mail:

• from

• to

• subject

• cc

• bcc

BUGS

Probably loads.

AUTHOR

Simon Cozens <simon@cpan.org>

SEE ALSO

Mail::Internet, Mail::SMTP