 |
Index for
Section 3 |
|
 |
Alphabetical
listing for M |
|
 |
Bottom of
page |
|
Mail::SpamAssassin::PeUrsMesrgSCtoantursi(b3u)ted
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/user_prefs'
});
my $mail = $spamtest->parse();
my $status = $spamtest->check ($mail);
if ($status->is_spam()) {
$status->rewrite_mail ();
}
...
DESCRIPTION
The Mail::SpamAssassin "check()" method returns an object of this class.
This object encapsulates all the per-message state.
METHODS
$status->check ()
Runs the SpamAssassin rules against the message pointed to by the
object.
$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_score ()
After a mail message has been checked, this method can be called. It
will return the message's score.
$num = $status->get_required_score ()
After a mail message has been checked, this method can be called. It
will return the score required for a mail to be considered spam.
$num = $status->get_autolearn_status ()
After a mail message has been checked, this method can be called. It
will return one of the following strings depending on whether the mail
was auto-learned or not: "ham", "no", "spam", "disabled", "failed",
"unavailable".
$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.
$msg = $status->get_message()
Return the object representing the message being scanned.
$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 function will return a scalar of the rewritten
message.
The actual modifications depend on the configuration (see
"Mail::SpamAssassin::Conf" for more information).
The possible modifications are as follows:
To:, From: and Subject: modification on spam mails
Depending on the configuration, the To: and From: lines can have a
user-defined RFC 2822 comment appended for spam mail. The subject
line may have a user-defined string prepended to it for spam mail.
X-Spam-* headers for all mails
Depending on the configuration, zero or more headers with names
beginning with "X-Spam-" will be added to mail depending on whether
it is spam or ham.
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.
$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.
$name = $status->get_current_eval_rule_name()
Return the name of the currently-running eval rule. "undef" is
returned if no eval rule is currently being run. Useful for plugins to
determine the current rule name while inside an eval test function
call.
$status->get (header_name [, default_value])
Returns a message header, pseudo-header, real name or address.
"header_name" is the name of a mail header, such as 'Subject', 'To',
etc. If "default_value" is given, it will be used if the requested
"header_name" does not exist.
Appending ":raw" to the header name will inhibit decoding of quoted-
printable or base-64 encoded strings.
Appending ":addr" to the header name will cause everything except the
first email address to be removed from the header. For example, all of
the following will result in "example@foo":
example@foo
example@foo (Foo Blah)
example@foo, example@bar
display: example@foo (Foo Blah), example@bar ;
Foo Blah <example@foo>
"Foo Blah" <example@foo>
"'Foo Blah'" <example@foo>
Appending ":name" to the header name will cause everything except the
first real name to be removed from the header. For example, all of the
following will result in "Foo Blah"
example@foo (Foo Blah)
example@foo (Foo Blah), example@bar
display: example@foo (Foo Blah), example@bar ;
Foo Blah <example@foo>
"Foo Blah" <example@foo>
"'Foo Blah'" <example@foo>
There are several special pseudo-headers that can be specified:
"ALL" can be used to mean the text of all the message's headers.
headers.
"ToCc" can be used to mean the contents of both the 'To' and 'Cc'
transaction that delivered this message, if this data has been made
available by the SMTP server.
"EnvelopeFrom" is the address used in the 'MAIL FROM:' phase of the SMTP
some mailing list software moves the real 'Message-Id' to
'Resent-Message-Id' or 'X-Message-Id', then uses its own one in the
'Message-Id' header. The value returned for this symbol is the text from
all 3 headers, separated by newlines.
"MESSAGEID" is a symbol meaning all Message-Id's found in the message;
the message has passed through
"X-Spam-Relays-Untrusted" is the generated metadata of untrusted relays
message has passed through
"X-Spam-Relays-Trusted" is the generated metadata of trusted relays the
$status->get_uri_list ()
Returns an array of all unique URIs found in the message. It takes a
combination of the URIs found in the rendered (decoded and HTML
stripped) body and the URIs found when parsing the HTML in the message.
Will also set $status->{uri_domain_count} (count of unique domains) and
$status->{uri_list} (the array as returned by this function).
The returned array will include the "raw" URI as well as "slightly
cooked" versions. For example, the single URI
'http://%77w%77.example.com/' will get turned into: (
'http://%77w%77.example.com/', 'http://www.example.com/' )
$status->clear_test_state()
Clear test state, including test log messages from
"$status->test_log()".
$status->create_fulltext_tmpfile (fulltext_ref)
This function creates a temporary file containing the passed scalar
reference data (typically the full/pristine text of the message). This
is typically used by external programs like pyzor and dccproc, to avoid
hangs due to buffering issues. Methods that need this, should call
$self->create_fulltext_tmpfile($fulltext) to retrieve the temporary
filename; it will be created if it has not already been.
Note: This can only be called once until
$status->delete_fulltext_tmpfile() is called.
$status->delete_fulltext_tmpfile ()
Will cleanup after a $status->create_fulltext_tmpfile() call. Deletes
the temporary file and uncaches the filename.
SEE ALSO
"Mail::SpamAssassin" "spamassassin"
|
Index for
Section 3 |
|
|
Alphabetical
listing for M |
|
 |
Top of
page |
|