2.5 Invoking SpamAssassin in a Perl Script

Because the heart of the SpamAssassin system is a set of Perl modules, it's fairly straightforward to call SpamAssassin from a Perl script to perform spam-checking of an email message. The Mail::SpamAssassin module (and its submodules) provide an object-oriented interface to the spam-checking and message-tagging logic. Many MTA-based filtering systems are written in Perl, and use the SpamAssassin modules to perform spam-checking on messages without invoking a separate program.

Examples Example 2-8 and Example 2-9 show Perl scripts that work like simple versions of the spamassassin script, accepting a message on standard input, checking it, and producing the (possibly rewritten) message on standard output. Example 2-8 illustrates the process for SpamAssassin 2.63.

Example 2-8. Using Mail::SpamAssassin 2.63 in Perl

 #!/usr/bin/perl use Mail::SpamAssassin; my @lines = <STDIN>; my $mail = Mail::SpamAssassin::NoMailAudit->new(data => \@lines); my $spamtest = Mail::SpamAssassin->new( ); my $status = $spamtest->check($mail); $status->rewrite_mail( ) if $status->is_spam( ); print $status->get_full_message_as_text( ); 

Before any SpamAssassin objects can be created, the script must use the Mail::SpamAssassin module. The message is read from standard input and saved to the array @lines . Then, the new( ) method of Mail::SpamAssassin::NoMailAudit is called, with a reference to the array provided as the value of the data parameter. ^[1] This method returns a Mail::SpamAssassin::Message object encapsulating the email message, which I call $mail in the example.

^[1] On systems with the Mail::Audit module, Mail::SpamAssassin 2.x can be used as a plug-in for Mail::Audit . See the documentation for both modules for details. SpamAssassin 3.0 no longer supports Mail::Audit , however; so this approach should be avoided for new installations.

A new Mail::SpamAssassin object called $spamtest is then created, and its check( ) method is called, passing in the message as an argument. check( ) returns a Mail::SpamAssassin::PerMsgStatus object, called $status in the script, that contains a copy of the message as well as the results of the spam check. In particular, the is_spam( ) method of $status returns 1 if the message was judged to be spam, and 0 otherwise .

If the message was spam, the rewrite_mail( ) method of the $status object is called and performs the complete SpamAssassin tagging process on the message, including adding relevant headers and MIME-encapsulating a spam report and the original message. Finally, the script prints the message to standard output by calling the get_full_message_as_text( ) method of $status and printing the result.

Example 2-9 illustrates the process for SpamAssassin 3.0.

Example 2-9. Using Mail::SpamAssassin 3.0 in Perl

 #!/usr/bin/perl use Mail::SpamAssassin; my @lines = <STDIN>; my $spamtest = Mail::SpamAssassin->new( ); my $mail = $spamtest->parse(\@lines); my $status = $spamtest->check($mail); print $status->rewrite_mail( ); 

Before any SpamAssassin objects can be created, the script must use the Mail::SpamAssassin module. The message is read from standard input and saved to the array @lines . Then, the new( ) method of Mail::SpamAssassin is called to create a new Mail::SpamAssassin object named $spamtest .

The parse( ) method on $spamtest is invoked and passed a reference to the array of message lines. This method returns a Mail::SpamAssassin::Message object encapsulating the email message, which I call $mail in the example.

Next, $spamtest 's check( ) method is called, passing in the message as an argument. check( ) returns a Mail::SpamAssassin::PerMsgStatus object, called $status in the script that contains a copy of the message as well as the results of the spam check.

Finally, the rewrite_mail( ) method of the $status object is called, which performs the complete SpamAssassin tagging process on the message, including adding relevant headers and, if the message is spam, MIME-encapsulating a spam report and the original message. The return value of rewrite_mail( ) is the rewritten message, so the script prints it to standard output.

As these scripts illustrate , simple spam-checking is easily added to Perl scripts that process email messages. The options to the spamassassin script are all available through Perl either as arguments that can be passed to the Mail::SpamAssassin constructor (e.g., to specify the location of the sitewide configuration file) or as methods of the Mail::SpamAssassin::PerMsgStatus object (e.g., to get the spam score or the specific tests that were triggered). The manual (or perldoc ) pages for Mail::SpamAssassin , and Mail::SpamAssassin::PerMsgStatus provide complete details. Other SpamAssassin modules support SpamAssassin's advanced features, such as learning, and are also documented with perldoc .