.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::PerMsgStatus 3pm"
.TH Mail::SpamAssassin::PerMsgStatus 3pm "2022-09-10" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::SpamAssassin::PerMsgStatus \- per\-message status (spam or not\-spam)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  my $spamtest = Mail::SpamAssassin\->new({
\&    \*(Aqrules_filename\*(Aq      => \*(Aq/etc/spamassassin.rules\*(Aq,
\&    \*(Aquserprefs_filename\*(Aq  => $ENV{HOME}.\*(Aq/.spamassassin/user_prefs\*(Aq
\&  });
\&  my $mail = $spamtest\->parse();
\&
\&  my $status = $spamtest\->check ($mail);
\&
\&  my $rewritten_mail;
\&  if ($status\->is_spam()) {
\&    $rewritten_mail = $status\->rewrite_mail ();
\&  }
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Mail::SpamAssassin \f(CW\*(C`check()\*(C'\fR method returns an object of this
class.  This object encapsulates all the per-message state.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$status\->check ()" 4
.el .IP "\f(CW$status\fR\->check ()" 4
.IX Item "$status->check ()"
Runs the SpamAssassin rules against the message pointed to by the object.
.ie n .IP "$status\->\fBlearn()\fR" 4
.el .IP "\f(CW$status\fR\->\fBlearn()\fR" 4
.IX Item "$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.
.ie n .IP "$score = $status\->\fBget_autolearn_points()\fR" 4
.el .IP "\f(CW$score\fR = \f(CW$status\fR\->\fBget_autolearn_points()\fR" 4
.IX Item "$score = $status->get_autolearn_points()"
Return the message's score as computed for auto-learning.  Certain tests are
ignored:
.Sp
.Vb 1
\&  \- rules with tflags set to \*(Aqlearn\*(Aq (the Bayesian rules)
\&
\&  \- rules with tflags set to \*(Aquserconf\*(Aq (user welcome/block\-listing rules, etc)
\&
\&  \- rules with tflags set to \*(Aqnoautolearn\*(Aq
.Ve
.Sp
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.
.ie n .IP "$score = $status\->\fBget_head_only_points()\fR" 4
.el .IP "\f(CW$score\fR = \f(CW$status\fR\->\fBget_head_only_points()\fR" 4
.IX Item "$score = $status->get_head_only_points()"
Return the message's score as computed for auto-learning, ignoring
all rules except for header-based ones.
.ie n .IP "$score = $status\->\fBget_learned_points()\fR" 4
.el .IP "\f(CW$score\fR = \f(CW$status\fR\->\fBget_learned_points()\fR" 4
.IX Item "$score = $status->get_learned_points()"
Return the message's score as computed for auto-learning, ignoring
all rules except for learning-based ones.
.ie n .IP "$score = $status\->\fBget_body_only_points()\fR" 4
.el .IP "\f(CW$score\fR = \f(CW$status\fR\->\fBget_body_only_points()\fR" 4
.IX Item "$score = $status->get_body_only_points()"
Return the message's score as computed for auto-learning, ignoring
all rules except for body-based ones.
.ie n .IP "$score = $status\->\fBget_autolearn_force_status()\fR" 4
.el .IP "\f(CW$score\fR = \f(CW$status\fR\->\fBget_autolearn_force_status()\fR" 4
.IX Item "$score = $status->get_autolearn_force_status()"
Return whether a message's score included any rules that are flagged as
autolearn_force.
.ie n .IP "$rule_names = $status\->\fBget_autolearn_force_names()\fR" 4
.el .IP "\f(CW$rule_names\fR = \f(CW$status\fR\->\fBget_autolearn_force_names()\fR" 4
.IX Item "$rule_names = $status->get_autolearn_force_names()"
Return a list of comma separated list of rule names if a message's
score included any rules that are flagged as autolearn_force.
.ie n .IP "$isspam = $status\->is_spam ()" 4
.el .IP "\f(CW$isspam\fR = \f(CW$status\fR\->is_spam ()" 4
.IX Item "$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.
.ie n .IP "$list = $status\->get_names_of_tests_hit ()" 4
.el .IP "\f(CW$list\fR = \f(CW$status\fR\->get_names_of_tests_hit ()" 4
.IX Item "$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 triggered by the mail.
.ie n .IP "$list = $status\->get_names_of_tests_hit_with_scores_hash ()" 4
.el .IP "\f(CW$list\fR = \f(CW$status\fR\->get_names_of_tests_hit_with_scores_hash ()" 4
.IX Item "$list = $status->get_names_of_tests_hit_with_scores_hash ()"
After a mail message has been checked, this method can be called. It will
return a pointer to a hash for rule & score pairs for all the symbolic
test names and individual scores of the tests which were triggered by the mail.
.ie n .IP "$list = $status\->get_names_of_tests_hit_with_scores ()" 4
.el .IP "\f(CW$list\fR = \f(CW$status\fR\->get_names_of_tests_hit_with_scores ()" 4
.IX Item "$list = $status->get_names_of_tests_hit_with_scores ()"
After a mail message has been checked, this method can be called. It will
return a comma-separated string of rule=score pairs for all the symbolic
test names and individual scores of the tests which were triggered by the mail.
.ie n .IP "$list = $status\->get_names_of_subtests_hit ()" 4
.el .IP "\f(CW$list\fR = \f(CW$status\fR\->get_names_of_subtests_hit ()" 4
.IX Item "$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 triggered by the mail.  Sub-tests are the
normally-hidden rules, which score 0 and have names beginning with two
underscores, used in meta rules.
.Sp
If a parameter of collapsed or dbg is passed, the output will be a condensed 
array of sub-tests with multiple hits reduced to one entry.
.Sp
If the parameter of dbg is passed, the output will be a condensed string of
sub-tests with multiple hits reduced to one entry with the number of hits 
in parentheses. Some information is also added at the end regarding the 
multiple hits.
.ie n .IP "$num = $status\->get_score ()" 4
.el .IP "\f(CW$num\fR = \f(CW$status\fR\->get_score ()" 4
.IX Item "$num = $status->get_score ()"
After a mail message has been checked, this method can be called.  It will
return the message's score.
.ie n .IP "$num = $status\->get_required_score ()" 4
.el .IP "\f(CW$num\fR = \f(CW$status\fR\->get_required_score ()" 4
.IX Item "$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.
.ie n .IP "$num = $status\->get_autolearn_status ()" 4
.el .IP "\f(CW$num\fR = \f(CW$status\fR\->get_autolearn_status ()" 4
.IX Item "$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: \*(L"ham\*(R", \*(L"no\*(R", \*(L"spam\*(R", \*(L"disabled\*(R", \*(L"failed\*(R", \*(L"unavailable\*(R".
.Sp
It also returns is flagged with auto_learn_force, it will also include the status
and the rules hit.  For example: \*(L"autolearn_force=yes (\s-1AUTOLEARNTEST_BODY\s0)\*(R"
.ie n .IP "$report = $status\->get_report ()" 4
.el .IP "\f(CW$report\fR = \f(CW$status\fR\->get_report ()" 4
.IX Item "$report = $status->get_report ()"
Deliver a \*(L"spam report\*(R" on the checked mail message.  This contains details of
how many spam detection rules it triggered.
.Sp
The report is returned as a multi-line string, with the lines separated by
\&\f(CW\*(C`\en\*(C'\fR characters.
.ie n .IP "$preview = $status\->get_content_preview ()" 4
.el .IP "\f(CW$preview\fR = \f(CW$status\fR\->get_content_preview ()" 4
.IX Item "$preview = $status->get_content_preview ()"
Give a \*(L"preview\*(R" of the content.
.Sp
This is returned as a multi-line string, with the lines separated by \f(CW\*(C`\en\*(C'\fR
characters, containing a fully-decoded, safe, plain-text sample of the first
few lines of the message body.
.ie n .IP "$msg = $status\->\fBget_message()\fR" 4
.el .IP "\f(CW$msg\fR = \f(CW$status\fR\->\fBget_message()\fR" 4
.IX Item "$msg = $status->get_message()"
Return the object representing the message being scanned.
.ie n .IP "$status\->rewrite_mail ()" 4
.el .IP "\f(CW$status\fR\->rewrite_mail ()" 4
.IX Item "$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.
.Sp
The actual modifications depend on the configuration (see
\&\f(CW\*(C`Mail::SpamAssassin::Conf\*(C'\fR for more information).
.Sp
The possible modifications are as follows:
.RS 4
.IP "To:, From: and Subject: modification on spam mails" 4
.IX Item "To:, From: and Subject: modification on spam mails"
Depending on the configuration, the To: and From: lines can have a
user-defined \s-1RFC 2822\s0 comment appended for spam mail. The subject line
may have a user-defined string prepended to it for spam mail.
.IP "X\-Spam\-* headers for all mails" 4
.IX Item "X-Spam-* headers for all mails"
Depending on the configuration, zero or more headers with names
beginning with \f(CW\*(C`X\-Spam\-\*(C'\fR will be added to mail depending on whether
it is spam or ham.
.IP "spam message with report_safe" 4
.IX Item "spam message with report_safe"
If report_safe is set to true (1), then spam messages are encapsulated
into their own message/rfc822 \s-1MIME\s0 attachment without any modifications
being made.
.Sp
If report_safe is set to false (0), then the message will only have the
above headers added/modified.
.RE
.RS 4
.RE
.ie n .IP "$status\->action_depends_on_tags($tags, $code, @args)" 4
.el .IP "\f(CW$status\fR\->action_depends_on_tags($tags, \f(CW$code\fR, \f(CW@args\fR)" 4
.IX Item "$status->action_depends_on_tags($tags, $code, @args)"
Enqueue the supplied subroutine reference \f(CW$code\fR, to become runnable when
all the specified tags become available. The \f(CW$tags\fR may be a simple
scalar \- a tag name, or a listref of tag names. The subroutine \f(CW&$code\fR
when called will be passed a \f(CW\*(C`permessagestatus\*(C'\fR object as its first argument,
followed by the supplied (optional) list \f(CW@args\fR .
.ie n .IP "$status\->set_tag($tagname, $value)" 4
.el .IP "\f(CW$status\fR\->set_tag($tagname, \f(CW$value\fR)" 4
.IX Item "$status->set_tag($tagname, $value)"
Set a template tag, as used in \f(CW\*(C`add_header\*(C'\fR, report templates, etc.  This
\&\s-1API\s0 is intended for use by plugins.  Tag names will be converted to an
all-uppercase representation internally.  Tag names must consist only of
[A\-Z0\-9_] characters and must not contain consecutive underscores.  Also the
name must not start or end in an underscore, as that is the template tagging
format.
.Sp
\&\f(CW$value\fR can be a simple scalar (string or number), or a reference to an
array, in which case the public method get_tag will join array elements
using a space as a separator, returning a single string for backward
compatibility.
.Sp
\&\f(CW$value\fR can also be a subroutine reference, which will be evaluated
each time the template is expanded. The first argument passed by get_tag
to a called subroutine will be a PerMsgStatus object (this module's object),
followed by optional arguments provided by a caller to get_tag.
.Sp
Note that perl supports closures, which means that variables set in the
caller's scope can be accessed inside this \f(CW\*(C`sub\*(C'\fR. For example:
.Sp
.Vb 5
\&    my $text = "hello world!";
\&    $status\->set_tag("FOO", sub {
\&              my $pms = shift;
\&              return $text;
\&            });
.Ve
.Sp
See \f(CW\*(C`Mail::SpamAssassin::Conf\*(C'\fR's \f(CW\*(C`TEMPLATE TAGS\*(C'\fR and \f(CW\*(C`CAPTURING TAGS
USING REGEX NAMED CAPTURE GROUPS\*(C'\fR sections for more details on how template
tags are used.
.ie n .IP "$string = $status\->get_tag($tagname)" 4
.el .IP "\f(CW$string\fR = \f(CW$status\fR\->get_tag($tagname)" 4
.IX Item "$string = $status->get_tag($tagname)"
Get the current value of a template tag, as used in \f(CW\*(C`add_header\*(C'\fR, report
templates, etc. This \s-1API\s0 is intended for use by plugins.  Tag names will be
converted to an all-uppercase representation internally.
.Sp
See \f(CW\*(C`Mail::SpamAssassin::Conf\*(C'\fR's \f(CW\*(C`TEMPLATE TAGS\*(C'\fR and \f(CW\*(C`CAPTURING TAGS
USING REGEX NAMED CAPTURE GROUPS\*(C'\fR sections for more details on how template
tags are used.
.Sp
\&\f(CW\*(C`undef\*(C'\fR will be returned if a tag by that name has not been defined.
.ie n .IP "$string = $status\->get_tag_raw($tagname, @args)" 4
.el .IP "\f(CW$string\fR = \f(CW$status\fR\->get_tag_raw($tagname, \f(CW@args\fR)" 4
.IX Item "$string = $status->get_tag_raw($tagname, @args)"
Similar to \f(CW\*(C`get_tag\*(C'\fR, but keeps a tag name unchanged (does not uppercase it),
and does not convert arrayref tag values into a single string.
.ie n .IP "$status\->set_spamd_result_item($subref)" 4
.el .IP "\f(CW$status\fR\->set_spamd_result_item($subref)" 4
.IX Item "$status->set_spamd_result_item($subref)"
Set an entry for the spamd result log line.  \f(CW$subref\fR should be a code
reference for a subroutine which will return a string in \f(CW\*(Aqname=VALUE\*(Aq\fR
format, similar to the other entries in the spamd result line:
.Sp
.Vb 6
\&  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
.Ve
.Sp
\&\f(CW\*(C`name\*(C'\fR and \f(CW\*(C`VALUE\*(C'\fR must not contain \f(CW\*(C`=\*(C'\fR or \f(CW\*(C`,\*(C'\fR characters, as it
is important that these log lines are easy to parse.
.Sp
The code reference will be called by spamd after the message has been scanned,
and the \f(CW\*(C`PerMsgStatus::check()\*(C'\fR method has returned.
.ie n .IP "$status\->finish ()" 4
.el .IP "\f(CW$status\fR\->finish ()" 4
.IX Item "$status->finish ()"
Indicate that this \f(CW$status\fR object is finished with, and can be destroyed.
.Sp
If you are using SpamAssassin in a persistent environment, or checking many
mail messages from one \f(CW\*(C`Mail::SpamAssassin\*(C'\fR factory, this method should be
called to ensure Perl's garbage collection will clean up old status objects.
.ie n .IP "$name = $status\->\fBget_current_eval_rule_name()\fR" 4
.el .IP "\f(CW$name\fR = \f(CW$status\fR\->\fBget_current_eval_rule_name()\fR" 4
.IX Item "$name = $status->get_current_eval_rule_name()"
Return the name of the currently-running eval rule.  \f(CW\*(C`undef\*(C'\fR 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.
.ie n .IP "$status\->get_decoded_body_text_array ()" 4
.el .IP "\f(CW$status\fR\->get_decoded_body_text_array ()" 4
.IX Item "$status->get_decoded_body_text_array ()"
Returns the message body, with \fBbase64\fR or \fBquoted-printable\fR encodings
decoded, and non-text parts or non-inline attachments stripped.
.Sp
This is the same result text as used in 'rawbody' rules.
.Sp
It is returned as an array of strings, with each string being a 2\-4kB chunk
of the body, split from boundaries if possible.
.ie n .IP "$status\->get_decoded_stripped_body_text_array ()" 4
.el .IP "\f(CW$status\fR\->get_decoded_stripped_body_text_array ()" 4
.IX Item "$status->get_decoded_stripped_body_text_array ()"
Returns the message body, decoded (as described in
\&\fBget_decoded_body_text_array()\fR), with \s-1HTML\s0 rendered, and with whitespace
normalized.
.Sp
This is the same result text as used in 'body' rules.
.Sp
It will always render text/html.
.Sp
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.
.ie n .IP "$status\->get (header_name [, default_value])" 4
.el .IP "\f(CW$status\fR\->get (header_name [, default_value])" 4
.IX Item "$status->get (header_name [, default_value])"
Returns a message header, pseudo-header or a real name, email-address or
some other parsed value set by modifiers.  \f(CW\*(C`header_name\*(C'\fR is the name of a
mail header, such as 'Subject', 'To', etc.
.Sp
Should be called in list context since 4.0.  Will return list of headers
content, or other values when modifiers used.
.Sp
If \f(CW\*(C`default_value\*(C'\fR is given, it will be used if the requested
\&\f(CW\*(C`header_name\*(C'\fR does not exist.  This is mainly useful when called in scalar
context to set 'undef' instead of legacy '' return value when header does
not exist.
.Sp
Appending \f(CW\*(C`:raw\*(C'\fR modifier to the header name will inhibit decoding of
quoted-printable or base\-64 encoded strings.
.Sp
Appending \f(CW\*(C`:addr\*(C'\fR modifier to the header name will return all
email-addresses found in the header.  It is mainly applicable to header
fields 'From', 'Sender', 'To', 'Cc' along with their 'Resent\-*'
counterparts, and the 'Return\-Path'.  For example, all of the following will
result in \*(L"example@foo\*(R" (and \*(L"example@bar\*(R"):
.RS 4
.IP "example@foo" 4
.IX Item "example@foo"
.PD 0
.IP "example@foo (Foo Blah), <example@bar>" 4
.IX Item "example@foo (Foo Blah), <example@bar>"
.IP "example@foo, example@bar" 4
.IX Item "example@foo, example@bar"
.IP "display: example@foo (Foo Blah), example@bar ;" 4
.IX Item "display: example@foo (Foo Blah), example@bar ;"
.IP "Foo Blah <example@foo>" 4
.IX Item "Foo Blah <example@foo>"
.ie n .IP """Foo Blah"" <example@foo>" 4
.el .IP "``Foo Blah'' <example@foo>" 4
.IX Item "Foo Blah <example@foo>"
.ie n .IP """'Foo Blah'"" <example@foo>" 4
.el .IP "``'Foo Blah''' <example@foo>" 4
.IX Item "'Foo Blah' <example@foo>"
.RE
.RS 4
.PD
.Sp
Appending \f(CW\*(C`:name\*(C'\fR modifier to the header name will return all \*(L"display
names\*(R" from the header field.  As with \f(CW\*(C`:addr\*(C'\fR, it is mainly applicable to
header fields 'From', 'Sender', 'To', 'Cc' along with their 'Resent\-*'
counterparts, and the 'Return\-Path'.  For example, all of the following will
result in \*(L"Foo Blah\*(R" (and \*(L"Bar Baz\*(R").  One level of single quotes is
stripped too, as it is often seen.
.IP "example@foo (Foo Blah)" 4
.IX Item "example@foo (Foo Blah)"
.PD 0
.ie n .IP "example@foo (Foo Blah), ""Bar Baz"" <example@bar>" 4
.el .IP "example@foo (Foo Blah), ``Bar Baz'' <example@bar>" 4
.IX Item "example@foo (Foo Blah), Bar Baz <example@bar>"
.IP "display: example@foo (Foo Blah), example@bar ;" 4
.IX Item "display: example@foo (Foo Blah), example@bar ;"
.IP "Foo Blah <example@foo>" 4
.IX Item "Foo Blah <example@foo>"
.ie n .IP """Foo Blah"" <example@foo>" 4
.el .IP "``Foo Blah'' <example@foo>" 4
.IX Item "Foo Blah <example@foo>"
.ie n .IP """'Foo Blah'"" <example@foo>" 4
.el .IP "``'Foo Blah''' <example@foo>" 4
.IX Item "'Foo Blah' <example@foo>"
.RE
.RS 4
.PD
.Sp
Appending \f(CW\*(C`:host\*(C'\fR to the header name will return the first hostname-looking
string that ends with a valid \s-1TLD.\s0  First it tries to find a match after @
character (possible email), then from any part of the header.  Normal use of
this would be for example 'From:addr:host' to return the hostname portion of
a From-address.
.Sp
Appending \f(CW\*(C`:domain\*(C'\fR to the header name implies \f(CW\*(C`:host\*(C'\fR, but will return
only domain part of the hostname, as returned by
\&\fBRegistryBoundaries::trim_domain()\fR.
.Sp
Appending \f(CW\*(C`:ip\*(C'\fR to the header name, will return the first IPv4 or IPv6
address string found.  Could be used for example as 'X\-Originating\-IP:ip'.
.Sp
Appending \f(CW\*(C`:revip\*(C'\fR to the header name implies \f(CW\*(C`:ip\*(C'\fR, but will return the
found \s-1IP\s0 in reverse (usually for \s-1DNSBL\s0 usage).
.Sp
Appending \f(CW\*(C`:first\*(C'\fR modifier to the header name will return only the first
(topmost) header, in case there are multiple ones.  Similarly \f(CW\*(C`:last\*(C'\fR will
select the last one.  These affect only the physical header line selection. 
If selected header is parsed further with \f(CW\*(C`:addr\*(C'\fR or similar, it may return
multiple results, if the selected header contains multiple addresses.
.Sp
There are several special pseudo-headers that can be specified:
.ie n .IP """ALL"" can be used to mean the text of all the message's headers. Each header is decoded and unfolded to single line, unless called with :raw." 4
.el .IP "\f(CWALL\fR can be used to mean the text of all the message's headers. Each header is decoded and unfolded to single line, unless called with :raw." 4
.IX Item "ALL can be used to mean the text of all the message's headers. Each header is decoded and unfolded to single line, unless called with :raw."
.PD 0
.ie n .IP """ALL\-TRUSTED"" can be used to mean the text of all the message's headers that could only have been added by trusted relays." 4
.el .IP "\f(CWALL\-TRUSTED\fR can be used to mean the text of all the message's headers that could only have been added by trusted relays." 4
.IX Item "ALL-TRUSTED can be used to mean the text of all the message's headers that could only have been added by trusted relays."
.ie n .IP """ALL\-INTERNAL"" can be used to mean the text of all the message's headers that could only have been added by internal relays." 4
.el .IP "\f(CWALL\-INTERNAL\fR can be used to mean the text of all the message's headers that could only have been added by internal relays." 4
.IX Item "ALL-INTERNAL can be used to mean the text of all the message's headers that could only have been added by internal relays."
.ie n .IP """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." 4
.el .IP "\f(CWALL\-UNTRUSTED\fR 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." 4
.IX Item "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."
.ie n .IP """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." 4
.el .IP "\f(CWALL\-EXTERNAL\fR can be used to mean the text of all the message's headers that may have been added by external relays.  Like \f(CWALL\-UNTRUSTED\fR the 'Received' header added by the last internal relay is included." 4
.IX Item "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."
.ie n .IP """ToCc"" can be used to mean the contents of both the 'To' and 'Cc' headers." 4
.el .IP "\f(CWToCc\fR can be used to mean the contents of both the 'To' and 'Cc' headers." 4
.IX Item "ToCc can be used to mean the contents of both the 'To' and 'Cc' headers."
.ie n .IP """EnvelopeFrom"" is the address used in the '\s-1MAIL FROM:\s0' phase of the \s-1SMTP\s0 transaction that delivered this message, if this data has been made available by the \s-1SMTP\s0 server." 4
.el .IP "\f(CWEnvelopeFrom\fR is the address used in the '\s-1MAIL FROM:\s0' phase of the \s-1SMTP\s0 transaction that delivered this message, if this data has been made available by the \s-1SMTP\s0 server." 4
.IX Item "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."
.ie n .IP """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." 4
.el .IP "\f(CWMESSAGEID\fR 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." 4
.IX Item "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."
.ie n .IP """X\-Spam\-Relays\-Untrusted"" is the generated metadata of untrusted relays the message has passed through" 4
.el .IP "\f(CWX\-Spam\-Relays\-Untrusted\fR is the generated metadata of untrusted relays the message has passed through" 4
.IX Item "X-Spam-Relays-Untrusted is the generated metadata of untrusted relays the message has passed through"
.ie n .IP """X\-Spam\-Relays\-Trusted"" is the generated metadata of trusted relays the message has passed through" 4
.el .IP "\f(CWX\-Spam\-Relays\-Trusted\fR is the generated metadata of trusted relays the message has passed through" 4
.IX Item "X-Spam-Relays-Trusted is the generated metadata of trusted relays the message has passed through"
.ie n .IP """X\-Spam\-Relays\-External"" is the generated metadata of external relays the message has passed through" 4
.el .IP "\f(CWX\-Spam\-Relays\-External\fR is the generated metadata of external relays the message has passed through" 4
.IX Item "X-Spam-Relays-External is the generated metadata of external relays the message has passed through"
.ie n .IP """X\-Spam\-Relays\-Internal"" is the generated metadata of internal relays the message has passed through" 4
.el .IP "\f(CWX\-Spam\-Relays\-Internal\fR is the generated metadata of internal relays the message has passed through" 4
.IX Item "X-Spam-Relays-Internal is the generated metadata of internal relays the message has passed through"
.RE
.RS 4
.RE
.ie n .IP "$status\->get_uri_list ()" 4
.el .IP "\f(CW$status\fR\->get_uri_list ()" 4
.IX Item "$status->get_uri_list ()"
.PD
Returns an array of all unique URIs found in the message.  It takes
a combination of the URIs found in the rendered (decoded and \s-1HTML\s0
stripped) body and the URIs found when parsing the \s-1HTML\s0 in the message.
Will also set \f(CW$status\fR\->{uri_list} (the array as returned by this function).
.Sp
The returned array will include the \*(L"raw\*(R" \s-1URI\s0 as well as
\&\*(L"slightly cooked\*(R" versions.  For example, the single \s-1URI\s0
\&'http://%77&#00119;%77.example.com/' will get turned into:
( 'http://%77&#00119;%77.example.com/', 'http://www.example.com/' )
.ie n .IP "$status\->get_uri_detail_list ()" 4
.el .IP "\f(CW$status\fR\->get_uri_detail_list ()" 4
.IX Item "$status->get_uri_detail_list ()"
Returns a hash reference of all unique URIs found in the message and
various data about where the URIs were found in the message.  It takes a
combination of the URIs found in the rendered (decoded and \s-1HTML\s0 stripped)
body and the URIs found when parsing the \s-1HTML\s0 in the message.  Will also
set \f(CW$status\fR\->{uri_detail_list} (the hash reference as returned by this
function).
.Sp
The hash format looks something like this:
.Sp
.Vb 8
\&  raw_uri => {
\&    types => { a => 1, img => 1, parsed => 1, domainkeys => 1,
\&               unlinked => 1, schemeless => 1 },
\&    cleaned => [ canonicalized_uri ],
\&    anchor_text => [ "click here", "no click here" ],
\&    domains => { domain1 => 1, domain2 => 1 },
\&    hosts => { host1 => domain1, host2 => domain2 },
\&  }
.Ve
.Sp
\&\f(CW\*(C`raw_uri\*(C'\fR is whatever the \s-1URI\s0 was in the message itself
(http://spamassassin.apache%2Eorg/).  Uris parsed from text will be prefixed
with scheme if missing (http://, mailto: etc).  \s-1HTML\s0 uris are as found.
.Sp
\&\f(CW\*(C`types\*(C'\fR is a hash of the \s-1HTML\s0 tags (lowercase) which referenced the
raw_uri.  \fIparsed\fR is a faked type which specifies that the raw_uri was
seen in the rendered text.  \fIdomainkeys\fR is defined when raw_uri was found
from \s-1DK/DKIM\s0 d= field.  \fIunlinked\fR is defined when it's assumed that \s-1MUA\s0
will not linkify uri (found in body without scheme or www. prefix). 
\&\fIschemeless\fR is always added for uris without scheme, regardless of
linkifying (i.e. email address found in body without mailto:).
.Sp
\&\f(CW\*(C`cleaned\*(C'\fR is an array of the raw and canonicalized version of the raw_uri
(http://spamassassin.apache%2Eorg/, https://spamassassin.apache.org/).
.Sp
\&\f(CW\*(C`anchor_text\*(C'\fR is an array of the anchor text (text between <a> and
</a>), if any, which linked to the \s-1URI.\s0
.Sp
\&\f(CW\*(C`domains\*(C'\fR is a hash of the domains found in the canonicalized URIs.
.Sp
\&\f(CW\*(C`hosts\*(C'\fR is a hash of unstripped hostnames found in the canonicalized URIs
as hash keys, with their domain part stored as a value of each hash entry.
.ie n .IP "$status\->add_uri_detail_list ($raw_uri, $types, $source, $valid_domain)" 4
.el .IP "\f(CW$status\fR\->add_uri_detail_list ($raw_uri, \f(CW$types\fR, \f(CW$source\fR, \f(CW$valid_domain\fR)" 4
.IX Item "$status->add_uri_detail_list ($raw_uri, $types, $source, $valid_domain)"
Adds values to internal uri_detail_list.  When used from Plugins, recommended
to call from parsed_metadata (along with register_method_priority, \-10) so
other Plugins calling \fBget_uri_detail_list()\fR will see it.
.Sp
\&\f(CW\*(C`raw_uri\*(C'\fR is the \s-1URI\s0 to be added. The only required parameter.
.Sp
\&\f(CW\*(C`types\*(C'\fR is an optional hash reference, contents are added to
uri_detail_list\->{types} (see get_uri_detail_list for known keys). 
\&\fIparsed\fR is default is no hash given.  \fInocanon\fR does not run
uri_list_canonicalize (no redirector, uri fixing).  \fInoclean\fR skips adding
uri_detail_list\->{cleaned}, so it would not be used in \*(L"uri\*(R" rule checks,
but domain/hosts would still be used for \s-1URIBL/RBL\s0 purposes.
.Sp
\&\f(CW\*(C`source\*(C'\fR is an optional simple string, only used for debug logging purposes
to identify where uri originates from (default: \*(L"parsed\*(R").
.Sp
\&\f(CW\*(C`valid_domain\*(C'\fR is an optional boolean (0/1).  If true, uri will not be
added unless hostname/domain is in valid format and contains a valid \s-1TLD.\s0 
(default: 0)
.ie n .IP "$status\->\fBclear_test_state()\fR" 4
.el .IP "\f(CW$status\fR\->\fBclear_test_state()\fR" 4
.IX Item "$status->clear_test_state()"
\&\s-1DEPRECATED, UNNEEDED SINCE 4.0\s0
.ie n .IP "$status\->got_hit ($rulename, $desc_prepend [, name => value, ...])" 4
.el .IP "\f(CW$status\fR\->got_hit ($rulename, \f(CW$desc_prepend\fR [, name => value, ...])" 4
.IX Item "$status->got_hit ($rulename, $desc_prepend [, name => value, ...])"
Register a hit against a rule in the ruleset.
.Sp
There are two mandatory arguments. These are \f(CW$rulename\fR, the name of the rule
that fired, and \f(CW$desc_prepend\fR, which is a short string that will be
prepended to the rules \f(CW\*(C`describe\*(C'\fR string in output reports.
.Sp
In addition, callers can supplement that with the following optional
data:
.RS 4
.ie n .IP "score => $num" 4
.el .IP "score => \f(CW$num\fR" 4
.IX Item "score => $num"
Optional: the score to use for the rule hit.  If unspecified,
the value from the \f(CW\*(C`Mail::SpamAssassin::Conf\*(C'\fR object's \f(CW\*(C`{scores}\*(C'\fR
hash will be used (a configured score), and in its absence the
\&\f(CW\*(C`defscore\*(C'\fR option value.
.ie n .IP "defscore => $num" 4
.el .IP "defscore => \f(CW$num\fR" 4
.IX Item "defscore => $num"
Optional: the score to use for the rule hit if neither the
option \f(CW\*(C`score\*(C'\fR is provided, nor a configured score value is provided.
.ie n .IP "value => $num" 4
.el .IP "value => \f(CW$num\fR" 4
.IX Item "value => $num"
Optional: the value to assign to the rule; the default value is \f(CW1\fR.
\&\fItflags multiple\fR rules use values of greater than 1 to indicate
multiple hits.  This value is accessible to meta rules.
.ie n .IP "ruletype => $type" 4
.el .IP "ruletype => \f(CW$type\fR" 4
.IX Item "ruletype => $type"
Optional, but recommended: the rule type string.  This is used in the
\&\f(CW\*(C`hit_rule\*(C'\fR plugin call, called by this method.  If unset, \fI'unknown'\fR is
used.
.ie n .IP "tflags => $string" 4
.el .IP "tflags => \f(CW$string\fR" 4
.IX Item "tflags => $string"
Optional: a string, i.e. a space-separated list of additional tflags
to be appended to an existing list of flags in \f(CW$self\fR\->{conf}\->{tflags},
such as: \*(L"nice noautolearn multiple\*(R". No syntax checks are performed.
.ie n .IP "description => $string" 4
.el .IP "description => \f(CW$string\fR" 4
.IX Item "description => $string"
Optional: a custom rule description string.  This is used in the
\&\f(CW\*(C`hit_rule\*(C'\fR plugin call, called by this method. If unset, the static
description is used.
.RE
.RS 4
.Sp
Backward compatibility: the two mandatory arguments have been part of this \s-1API\s0
since SpamAssassin 2.x.  The optional \fIname=<gt\fRvalue> pairs, however, are a
new addition in SpamAssassin 3.2.0.
.RE
.ie n .IP "$status\->rule_ready ($rulename [, $no_async])" 4
.el .IP "\f(CW$status\fR\->rule_ready ($rulename [, \f(CW$no_async\fR])" 4
.IX Item "$status->rule_ready ($rulename [, $no_async])"
Mark an asynchronous rule ready, so it can be considered for meta rule
evaluation.  Asynchronous rule is a rule whose eval-function returns undef,
marking that it's not ready yet, expecting results later. 
\&\f(CW$status\fR\->\fBrule_ready()\fR must be called later to mark it ready, alternatively
\&\f(CW$status\fR\->\fBgot_hit()\fR also does this.  If neither is called, then any meta rule
that depends on this rule might not evaluate.
.Sp
Optional boolean \f(CW$no_async\fR skips checking if there are pending async \s-1DNS\s0
lookups for the rule.
.ie n .IP "$status\->test_log ($text [, $rulename])" 4
.el .IP "\f(CW$status\fR\->test_log ($text [, \f(CW$rulename\fR])" 4
.IX Item "$status->test_log ($text [, $rulename])"
Add \f(CW$text\fR log entry for a hit rule in final message \s-1REPORT/SUMMARY.\s0
.Sp
Usually called just before \fBgot_hit()\fR, to describe for example what \s-1URI\s0 the
rule matched on.  Optional <$rulename> argument is recommended to make sure
log is written to correct rule.  If rulename is not provided,
\&\fBget_current_eval_rule_name()\fR is used as fallback.
.Sp
Can be called multiple times per rule for additional entries.
.ie n .IP "$status\->create_fulltext_tmpfile (fulltext_ref)" 4
.el .IP "\f(CW$status\fR\->create_fulltext_tmpfile (fulltext_ref)" 4
.IX Item "$status->create_fulltext_tmpfile (fulltext_ref)"
This function creates a temporary file containing the passed scalar
reference data.  If no scalar is passed, full/pristine message text is
assumed.  This is typically used by external programs like pyzor and
dccproc, to avoid hangs due to buffering issues.
.Sp
All tempfiles are automatically cleaned up by PerMsgStatus destructor.
.ie n .IP "$status\->delete_fulltext_tmpfile (tmpfile)" 4
.el .IP "\f(CW$status\fR\->delete_fulltext_tmpfile (tmpfile)" 4
.IX Item "$status->delete_fulltext_tmpfile (tmpfile)"
Will cleanup after a \f(CW$status\fR\->\fBcreate_fulltext_tmpfile()\fR call.  Deletes the
temporary file and uncaches the filename.  Generally there no need to call
this, PerMsgStatus destructor cleans up all tmpfiles.
.IP "all_from_addrs_domains" 4
.IX Item "all_from_addrs_domains"
This function returns all the various from addresses in a message using \fBall_from_addrs()\fR
and then returns only the domain names.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBMail::SpamAssassin\fR\|(3)
\&\fBspamassassin\fR\|(1)