Mail::SpamAssassin::PerMsgStatus(3)			User Contributed Perl Documentation		       Mail::SpamAssassin::PerMsgStatus(3)

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

       $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 consid-
	   ered 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 "
" 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 Spa-
	   mAssassin.

       $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"

perl v5.8.0							    2002-09-26				       Mail::SpamAssassin::PerMsgStatus(3)