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 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->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 the Mail::SpamAssassin manpage
        factory, this method should be called to ensure Perl's garbage
        collection will clean up old status objects.

SEE ALSO
    `Mail::SpamAssassin' `spamassassin'