Mail::SpamAssassin::PerMsgStatus - per-message status (spam or not-spam)
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);
my $rewritten_mail;
if ($status->is_spam()) {
$rewritten_mail = $status->rewrite_mail ();
}
...
The Mail::SpamAssassin check() method returns an object of this
class. This object encapsulates all the per-message state.
learn()get_autolearn_points()- rules with tflags set to 'learn' (the Bayesian rules)
- rules with tflags set to 'userconf' (user white/black-listing rules, etc)
- rules with tflags set to 'noautolearn'
Also note that auto-learning occurs using scores from either scoreset 0 or 1, depending on what scoreset is used during message check. It is likely that the message check and auto-learn scores will be different.
get_head_only_points()get_learned_points()get_body_only_points()The report is returned as a multi-line string, with the lines separated by
\n characters.
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.
get_message()The actual modifications depend on the configuration (see
Mail::SpamAssassin::Conf for more information).
The possible modifications are as follows:
X-Spam- will be added to mail depending on whether
it is spam or ham.
If report_safe is set to false (0), then the message will only have the above headers added/modified.
add_header, report templates, etc. This API
is intended for use by plugins. Tag names will be converted to an
all-uppercase representation internally.
$value can be a subroutine reference, which will be evaluated each time
the template is expanded. Note that perl supports closures, which means
that variables set in the caller's scope can be accessed inside this sub.
For example:
my $text = "hello world!";
$status->set_tag("FOO", sub {
return $text;
});
See Mail::SpamAssassin::Conf's TEMPLATE TAGS section for more details on
how template tags are used.
undef will be returned if a tag by that name has not been defined.
get_tag($tagname)add_header, report
templates, etc. This API is intended for use by plugins. Tag names will be
converted to an all-uppercase representation internally. See
Mail::SpamAssassin::Conf's TEMPLATE TAGS section for more details on
tags.
undef will be returned if a tag by that name has not been defined.
set_spamd_result_item($subref)$subref should be a code
reference for a subroutine which will return a string in 'name=VALUE'
format, similar to the other entries in the spamd result line:
Jul 17 14:10:47 radish spamd[16670]: spamd: result: Y 22 - ALL_NATURAL, DATE_IN_FUTURE_03_06,DIET_1,DRUGS_ERECTILE,DRUGS_PAIN, TEST_FORGED_YAHOO_RCVD,TEST_INVALID_DATE,TEST_NOREALNAME, TEST_NORMAL_HTTP_TO_IP,UNDISC_RECIPS scantime=0.4,size=3138,user=jm, uid=1000,required_score=5.0,rhost=localhost,raddr=127.0.0.1, rport=33153,mid=<9PS291LhupY>,autolearn=spam
name and VALUE must not contain = or , characters, as it
is important that these log lines are easy to parse.
The code reference will be called by spamd after the message has been scanned,
and the PerMsgStatus::check() method has returned.
$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.
get_current_eval_rule_name()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.
It is returned as an array of strings, with each string representing one newline-separated line of the body.
It will always render text/html, and will use a heuristic to determine if other text/* parts should be considered text/html.
It is returned as an array of strings, with each string representing one 'paragraph'. Paragraphs, in plain-text mails, are double-newline-separated blocks of multi-line text.
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'':
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''
There are several special pseudo-headers that can be specified:
ALL can be used to mean the text of all the message's headers.ALL-TRUSTED can be used to mean the text of all the message's headers
that could only have been added by trusted relays.ALL-INTERNAL can be used to mean the text of all the message's headers
that could only have been added by internal relays.ALL-UNTRUSTED can be used to mean the text of all the message's
headers that may have been added by untrusted relays. To make this
pseudo-header more useful for header rules the 'Received' header that was added
by the last trusted relay is included, even though it can be trusted.ALL-EXTERNAL can be used to mean the text of all the message's headers
that may have been added by external relays. Like ALL-UNTRUSTED the
'Received' header added by the last internal relay is included.ToCc can be used to mean the contents of both the 'To' and 'Cc'
headers.EnvelopeFrom is the address used in the 'MAIL FROM:' phase of the SMTP
transaction that delivered this message, if this data has been made available
by the SMTP server.MESSAGEID is a symbol meaning all Message-Id's found in the message;
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.X-Spam-Relays-Untrusted is the generated metadata of untrusted relays
the message has passed throughX-Spam-Relays-Trusted is the generated metadata of trusted relays
the message has passed throughThe 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/' )
The hash format looks something like this:
raw_uri => {
types => { a => 1, img => 1, parsed => 1 },
cleaned => [ canonified_uri ],
anchor_text => [ "click here", "no click here" ],
domains => { domain1 => 1, domain2 => 1 },
}
raw_uri is whatever the URI was in the message itself
(http://spamassassin.apache%2Eorg/).
types is a hash of the HTML tags (lowercase) which referenced
the raw_uri. parsed is a faked type which specifies that the
raw_uri was seen in the rendered text.
cleaned is an array of the raw and canonified version of the raw_uri
(http://spamassassin.apache%2Eorg/, http://spamassassin.apache.org/).
anchor_text is an array of the anchor text (text between <a> and
</a>), if any, which linked to the URI.
domains is a hash of the domains found in the canonified URIs.
clear_test_state()$status->test_log().
There are two mandatory arguments. These are $rulename, the name of the rule
that fired, and $desc_prepend, which is a short string that will be
prepended to the rules describe string in output reports.
In addition, callers can supplement that with the following optional data:
Mail::SpamAssassin::Conf object's {scores}
hash will be used.
1.
tflags multiple rules use values of greater than 1 to indicate
multiple hits. This value is accessible to meta rules.
hit_rule plugin call, called by this method. If unset, 'unknown' is
used.
Backwards compatibility: the two mandatory arguments have been part of this API since SpamAssassin 2.x. The optional name=<gtvalue> pairs, however, are a new addition in SpamAssassin 3.2.0.
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.
create_fulltext_tmpfile() call. Deletes the
temporary file and uncaches the filename.
Mail::SpamAssassin
spamassassin