NAME

Mail::SpamAssassin::PerMsgStatus - per-message status (spam or not-spam)

SYNOPSIS

my $spamtest = new Mail::SpamAssassin ({
  'rules_filename'      => '/etc/spamassassin.rules',
  'userprefs_filename'  => $ENV{HOME}.'/.spamassassin.cf'
});
my $mail = Mail::SpamAssassin::MyMailAudit->new();

my $status = $spamtest->check ($mail);
if ($status->is_spam()) {
  $status->rewrite_mail ();
  $mail->accept("caught_spam");
}
...

DESCRIPTION

The Mail::SpamAssassin check() method returns an object of this class. This object encapsulates all the per-message state.

METHODS

$isspam = $status->is_spam ()

After a mail message has been checked, this method can be called. It will return 1 for mail determined likely to be spam, 0 if it does not seem spam-like.

$list = $status->get_names_of_tests_hit ()

After a mail message has been checked, this method can be called. It will return a comma-separated string, listing all the symbolic test names of the tests which were trigged by the mail.

$num = $status->get_hits ()

After a mail message has been checked, this method can be called. It will return the number of hits this message incurred.

$num = $status->get_required_hits ()

After a mail message has been checked, this method can be called. It will return the number of hits required for a mail to be considered spam.

$report = $status->get_report ()

Deliver a "spam report" on the checked mail message. This contains details of how many spam detection rules it triggered.

The report is returned as a multi-line string, with the lines separated by \n characters.

$status->rewrite_mail ()

Rewrite the mail message. This will add headers, and possibly body text, to reflect its spam or not-spam status.

The modifications made are as follows:

Subject: header for spam mails

The string *****SPAM***** (changeable with subject_tag config option) is prepended to the subject, unless the rewrite_subject 0 configuration option is given.

X-Spam-Status: header for spam mails

A string, Yes, hits=nn required=nn tests=... is set in this header to reflect the filter status. The keys in this string are as follows:

X-Spam-Report: header for spam mails

The SpamAssassin report is added to the mail header if the report_header = 1 configuration option is given.

hits=nn The number of hits the message triggered.

required=nn The threshold at which a mail is marked as spam.

tests=... The symbolic names of tests which were triggered.

X-Spam-Flag: header for spam mails

Set to YES.

Content-Type: header for spam mails

Set to text/plain, in order to defang HTML mail or other active content that could "call back" to the spammer.

X-Spam-Checker-Version: header for spam mails

Set to the version number of the SpamAssassin checker which tested the mail.

spam mail body text

The SpamAssassin report is added to top of the mail message body, unless the report_header 1 configuration option is given.

X-Spam-Status: header for non-spam mails

A string, No, hits=nn required=nn tests=... is set in this header to reflect the filter status. The keys in this string are the same as for spam mails (see above).

$messagestring = $status->get_full_message_as_text ()

Returns the mail message as a string, including headers and raw body text.

If the message has been rewritten using rewrite_mail(), these changes will be reflected in the string.

Note: this is simply a helper method which calls methods on the mail message object. It is provided because Mail::Audit uses an unusual (ie. not quite intuitive) interface to do this, and it has been a common stumbling block for authors of scripts which use SpamAssassin.

$status->handle_auto_report ()

If this mail message has a high enough hit score, report it to spam-tracking services straight away, without waiting for user confirmation. See the documentation for spamassassin's -r switch for details on what spam-tracking services are used.

$status->finish ()

Indicate that this $status object is finished with, and can be destroyed.

If you are using SpamAssassin in a persistent environment, or checking many mail messages from one Mail::SpamAssassin factory, this method should be called to ensure Perl's garbage collection will clean up old status objects.

SEE ALSO

Mail::SpamAssassin spamassassin