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::NoMailAudit->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 $status->learn() After a mail message has been checked, this method can be called. If the score is outside a certain range around the threshold, ie. if the message is judged more-or-less definitely spam or definitely non-spam, it will be fed into SpamAssassin's learning systems (currently the naive Bayesian classifier), so that future similar mails will be caught. $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. $list = $status->get_names_of_subtests_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 meta-rule sub-tests which were trigged by the mail. Sub-tests are the normally-hidden rules, which score 0 and have names beginning with two underscores, used in meta rules. $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. $preview = $status->get_content_preview () Give a "preview" of the content. This is returned as a multi-line string, with the lines separated by "\n" characters, containing a fully-decoded, safe, plain-text sample of the first few lines of the message body. $status->rewrite_mail () Rewrite the mail message. This will at minimum add headers, and at maximum MIME-encapsulate the message text, to reflect its spam or not-spam status. The possible modifications 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: 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. version=... The version of SpamAssassin which made the change 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). X-Spam-Flag: header for spam mails Set to "YES". X-Spam-Checker-Version: header for all mails Set to the version number of the SpamAssassin checker which tested the mail. spam message with report_safe If report_safe is set to true (1), then spam messages are encapsulated into their own message/rfc822 MIME attachment without any modifications being made. If report_safe is set to false (0), then the message will only have the above headers added/modified. $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->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"