1Mail::SpamAssassin::PerUMssegrStCaotnutsr(i3b)uted PerlMDaoiclu:m:eSnptaamtAisosnassin::PerMsgStatus(3)
2
6 Mail::SpamAssassin::PerMsgStatus - per-message status (spam or
7 not-spam)
8
10 my $spamtest = Mail::SpamAssassin->new({
11 'rules_filename' => '/etc/spamassassin.rules',
12 'userprefs_filename' => $ENV{HOME}.'/.spamassassin/user_prefs'
13 });
14 my $mail = $spamtest->parse();
15 my $status = $spamtest->check ($mail);
17 my $rewritten_mail;
19 if ($status->is_spam()) {
20 $rewritten_mail = $status->rewrite_mail ();
21 }
22 ...
23
25 The Mail::SpamAssassin check() method returns an object of this class.
26 This object encapsulates all the per-message state.
27
29 $status->check ()
30 Runs the SpamAssassin rules against the message pointed to by the
31 object.
32 $status->learn()
34 After a mail message has been checked, this method can be called.
35 If the score is outside a certain range around the threshold, ie.
36 if the message is judged more-or-less definitely spam or definitely
37 non-spam, it will be fed into SpamAssassin's learning systems
38 (currently the naive Bayesian classifier), so that future similar
39 mails will be caught.
40 $score = $status->get_autolearn_points()
42 Return the message's score as computed for auto-learning. Certain
43 tests are ignored:
44 - rules with tflags set to 'learn' (the Bayesian rules)
46 - rules with tflags set to 'userconf' (user welcome/block-listing rules, etc)
48 - rules with tflags set to 'noautolearn'
50 Also note that auto-learning occurs using scores from either
52 scoreset 0 or 1, depending on what scoreset is used during message
53 check. It is likely that the message check and auto-learn scores
54 will be different.
55 $score = $status->get_head_only_points()
57 Return the message's score as computed for auto-learning, ignoring
58 all rules except for header-based ones.
59 $score = $status->get_learned_points()
61 Return the message's score as computed for auto-learning, ignoring
62 all rules except for learning-based ones.
63 $score = $status->get_body_only_points()
65 Return the message's score as computed for auto-learning, ignoring
66 all rules except for body-based ones.
67 $score = $status->get_autolearn_force_status()
69 Return whether a message's score included any rules that are
70 flagged as autolearn_force.
71 $rule_names = $status->get_autolearn_force_names()
73 Return a list of comma separated list of rule names if a message's
74 score included any rules that are flagged as autolearn_force.
75 $isspam = $status->is_spam ()
77 After a mail message has been checked, this method can be called.
78 It will return 1 for mail determined likely to be spam, 0 if it
79 does not seem spam-like.
80 $list = $status->get_names_of_tests_hit ()
82 After a mail message has been checked, this method can be called.
83 It will return a comma-separated string, listing all the symbolic
84 test names of the tests which were triggered by the mail.
85 $list = $status->get_names_of_tests_hit_with_scores_hash ()
87 After a mail message has been checked, this method can be called.
88 It will return a pointer to a hash for rule & score pairs for all
89 the symbolic test names and individual scores of the tests which
90 were triggered by the mail.
91 $list = $status->get_names_of_tests_hit_with_scores ()
93 After a mail message has been checked, this method can be called.
94 It will return a comma-separated string of rule=score pairs for all
95 the symbolic test names and individual scores of the tests which
96 were triggered by the mail.
97 $list = $status->get_names_of_subtests_hit ()
99 After a mail message has been checked, this method can be called.
100 It will return a comma-separated string, listing all the symbolic
101 test names of the meta-rule sub-tests which were triggered by the
102 mail. Sub-tests are the normally-hidden rules, which score 0 and
103 have names beginning with two underscores, used in meta rules.
104 If a parameter of collapsed or dbg is passed, the output will be a
106 condensed array of sub-tests with multiple hits reduced to one
107 entry.
108 If the parameter of dbg is passed, the output will be a condensed
110 string of sub-tests with multiple hits reduced to one entry with
111 the number of hits in parentheses. Some information is also added
112 at the end regarding the multiple hits.
113 $num = $status->get_score ()
115 After a mail message has been checked, this method can be called.
116 It will return the message's score.
117 $num = $status->get_required_score ()
119 After a mail message has been checked, this method can be called.
120 It will return the score required for a mail to be considered spam.
121 $num = $status->get_autolearn_status ()
123 After a mail message has been checked, this method can be called.
124 It will return one of the following strings depending on whether
125 the mail was auto-learned or not: "ham", "no", "spam", "disabled",
126 "failed", "unavailable".
127 It also returns is flagged with auto_learn_force, it will also
129 include the status and the rules hit. For example:
130 "autolearn_force=yes (AUTOLEARNTEST_BODY)"
131 $report = $status->get_report ()
133 Deliver a "spam report" on the checked mail message. This contains
134 details of how many spam detection rules it triggered.
135 The report is returned as a multi-line string, with the lines
137 separated by "\n" characters.
138 $preview = $status->get_content_preview ()
140 Give a "preview" of the content.
141 This is returned as a multi-line string, with the lines separated
143 by "\n" characters, containing a fully-decoded, safe, plain-text
144 sample of the first few lines of the message body.
145 $msg = $status->get_message()
147 Return the object representing the message being scanned.
148 $status->rewrite_mail ()
150 Rewrite the mail message. This will at minimum add headers, and at
151 maximum MIME-encapsulate the message text, to reflect its spam or
152 not-spam status. The function will return a scalar of the
153 rewritten message.
154 The actual modifications depend on the configuration (see
156 "Mail::SpamAssassin::Conf" for more information).
157 The possible modifications are as follows:
159 To:, From: and Subject: modification on spam mails
161 Depending on the configuration, the To: and From: lines can
162 have a user-defined RFC 2822 comment appended for spam mail.
163 The subject line may have a user-defined string prepended to it
164 for spam mail.
165 X-Spam-* headers for all mails
167 Depending on the configuration, zero or more headers with names
168 beginning with "X-Spam-" will be added to mail depending on
169 whether it is spam or ham.
170 spam message with report_safe
172 If report_safe is set to true (1), then spam messages are
173 encapsulated into their own message/rfc822 MIME attachment
174 without any modifications being made.
175 If report_safe is set to false (0), then the message will only
177 have the above headers added/modified.
178 $status->action_depends_on_tags($tags, $code, @args)
180 Enqueue the supplied subroutine reference $code, to become runnable
181 when all the specified tags become available. The $tags may be a
182 simple scalar - a tag name, or a listref of tag names. The
183 subroutine &$code when called will be passed a "permessagestatus"
184 object as its first argument, followed by the supplied (optional)
185 list @args .
186 $status->set_tag($tagname, $value)
188 Set a template tag, as used in "add_header", report templates, etc.
189 This API is intended for use by plugins. Tag names will be
190 converted to an all-uppercase representation internally. Tag names
191 must consist only of [A-Z0-9_] characters and must not contain
192 consecutive underscores. Also the name must not start or end in an
193 underscore, as that is the template tagging format.
194 $value can be a simple scalar (string or number), or a reference to
196 an array, in which case the public method get_tag will join array
197 elements using a space as a separator, returning a single string
198 for backward compatibility.
199 $value can also be a subroutine reference, which will be evaluated
201 each time the template is expanded. The first argument passed by
202 get_tag to a called subroutine will be a PerMsgStatus object (this
203 module's object), followed by optional arguments provided by a
204 caller to get_tag.
205 Note that perl supports closures, which means that variables set in
207 the caller's scope can be accessed inside this "sub". For example:
208 my $text = "hello world!";
210 $status->set_tag("FOO", sub {
211 my $pms = shift;
212 return $text;
213 });
214 See "Mail::SpamAssassin::Conf"'s "TEMPLATE TAGS" and "CAPTURING
216 TAGS USING REGEX NAMED CAPTURE GROUPS" sections for more details on
217 how template tags are used.
218 $string = $status->get_tag($tagname)
220 Get the current value of a template tag, as used in "add_header",
221 report templates, etc. This API is intended for use by plugins.
222 Tag names will be converted to an all-uppercase representation
223 internally.
224 See "Mail::SpamAssassin::Conf"'s "TEMPLATE TAGS" and "CAPTURING
226 TAGS USING REGEX NAMED CAPTURE GROUPS" sections for more details on
227 how template tags are used.
228 "undef" will be returned if a tag by that name has not been
230 defined.
231 $string = $status->get_tag_raw($tagname, @args)
233 Similar to "get_tag", but keeps a tag name unchanged (does not
234 uppercase it), and does not convert arrayref tag values into a
235 single string.
236 $status->set_spamd_result_item($subref)
238 Set an entry for the spamd result log line. $subref should be a
239 code reference for a subroutine which will return a string in
240 'name=VALUE' format, similar to the other entries in the spamd
241 result line:
242 Jul 17 14:10:47 radish spamd[16670]: spamd: result: Y 22 - ALL_NATURAL,
244 DATE_IN_FUTURE_03_06,DIET_1,DRUGS_ERECTILE,DRUGS_PAIN,
245 TEST_FORGED_YAHOO_RCVD,TEST_INVALID_DATE,TEST_NOREALNAME,
246 TEST_NORMAL_HTTP_TO_IP,UNDISC_RECIPS scantime=0.4,size=3138,user=jm,
247 uid=1000,required_score=5.0,rhost=localhost,raddr=127.0.0.1,
248 rport=33153,mid=<9PS291LhupY>,autolearn=spam
249 "name" and "VALUE" must not contain "=" or "," characters, as it is
251 important that these log lines are easy to parse.
252 The code reference will be called by spamd after the message has
254 been scanned, and the PerMsgStatus::check() method has returned.
255 $status->finish ()
257 Indicate that this $status object is finished with, and can be
258 destroyed.
259 If you are using SpamAssassin in a persistent environment, or
261 checking many mail messages from one "Mail::SpamAssassin" factory,
262 this method should be called to ensure Perl's garbage collection
263 will clean up old status objects.
264 $name = $status->get_current_eval_rule_name()
266 Return the name of the currently-running eval rule. "undef" is
267 returned if no eval rule is currently being run. Useful for
268 plugins to determine the current rule name while inside an eval
269 test function call.
270 $status->get_decoded_body_text_array ()
272 Returns the message body, with base64 or quoted-printable encodings
273 decoded, and non-text parts or non-inline attachments stripped.
274 This is the same result text as used in 'rawbody' rules.
276 It is returned as an array of strings, with each string being a
278 2-4kB chunk of the body, split from boundaries if possible.
279 $status->get_decoded_stripped_body_text_array ()
281 Returns the message body, decoded (as described in
282 get_decoded_body_text_array()), with HTML rendered, and with
283 whitespace normalized.
284 This is the same result text as used in 'body' rules.
286 It will always render text/html.
288 It is returned as an array of strings, with each string
290 representing one 'paragraph'. Paragraphs, in plain-text mails, are
291 double-newline-separated blocks of multi-line text.
292 $status->get (header_name [, default_value])
294 Returns a message header, pseudo-header or a real name, email-
295 address or some other parsed value set by modifiers. "header_name"
296 is the name of a mail header, such as 'Subject', 'To', etc.
297 Should be called in list context since 4.0. Will return list of
299 headers content, or other values when modifiers used.
300 If "default_value" is given, it will be used if the requested
302 "header_name" does not exist. This is mainly useful when called in
303 scalar context to set 'undef' instead of legacy '' return value
304 when header does not exist.
305 Appending ":raw" modifier to the header name will inhibit decoding
307 of quoted-printable or base-64 encoded strings.
308 Appending ":addr" modifier to the header name will return all
310 email-addresses found in the header. It is mainly applicable to
311 header fields 'From', 'Sender', 'To', 'Cc' along with their
312 'Resent-*' counterparts, and the 'Return-Path'. For example, all
313 of the following will result in "example@foo" (and "example@bar"):
314 example@foo
316 example@foo (Foo Blah), <example@bar>
317 example@foo, example@bar
318 display: example@foo (Foo Blah), example@bar ;
319 Foo Blah <example@foo>
320 "Foo Blah" <example@foo>
321 "'Foo Blah'" <example@foo>
322 Appending ":name" modifier to the header name will return all
324 "display names" from the header field. As with ":addr", it is
325 mainly applicable to header fields 'From', 'Sender', 'To', 'Cc'
326 along with their 'Resent-*' counterparts, and the 'Return-Path'.
327 For example, all of the following will result in "Foo Blah" (and
328 "Bar Baz"). One level of single quotes is stripped too, as it is
329 often seen.
330 example@foo (Foo Blah)
332 example@foo (Foo Blah), "Bar Baz" <example@bar>
333 display: example@foo (Foo Blah), example@bar ;
334 Foo Blah <example@foo>
335 "Foo Blah" <example@foo>
336 "'Foo Blah'" <example@foo>
337 Appending ":host" to the header name will return the first
339 hostname-looking string that ends with a valid TLD. First it tries
340 to find a match after @ character (possible email), then from any
341 part of the header. Normal use of this would be for example
342 'From:addr:host' to return the hostname portion of a From-address.
343 Appending ":domain" to the header name implies ":host", but will
345 return only domain part of the hostname, as returned by
346 RegistryBoundaries::trim_domain().
347 Appending ":ip" to the header name, will return the first IPv4 or
349 IPv6 address string found. Could be used for example as
350 'X-Originating-IP:ip'.
351 Appending ":revip" to the header name implies ":ip", but will
353 return the found IP in reverse (usually for DNSBL usage).
354 Appending ":first" modifier to the header name will return only the
356 first (topmost) header, in case there are multiple ones. Similarly
357 ":last" will select the last one. These affect only the physical
358 header line selection. If selected header is parsed further with
359 ":addr" or similar, it may return multiple results, if the selected
360 header contains multiple addresses.
361 There are several special pseudo-headers that can be specified:
363 "ALL" can be used to mean the text of all the message's headers.
365 Each header is decoded and unfolded to single line, unless called
366 with :raw.
367 "ALL-TRUSTED" can be used to mean the text of all the message's
368 headers that could only have been added by trusted relays.
369 "ALL-INTERNAL" can be used to mean the text of all the message's
370 headers that could only have been added by internal relays.
371 "ALL-UNTRUSTED" can be used to mean the text of all the message's
372 headers that may have been added by untrusted relays. To make this
373 pseudo-header more useful for header rules the 'Received' header
374 that was added by the last trusted relay is included, even though
375 it can be trusted.
376 "ALL-EXTERNAL" can be used to mean the text of all the message's
377 headers that may have been added by external relays. Like
378 "ALL-UNTRUSTED" the 'Received' header added by the last internal
379 relay is included.
380 "ToCc" can be used to mean the contents of both the 'To' and 'Cc'
381 headers.
382 "EnvelopeFrom" is the address used in the 'MAIL FROM:' phase of the
383 SMTP transaction that delivered this message, if this data has been
384 made available by the SMTP server.
385 "MESSAGEID" is a symbol meaning all Message-Id's found in the
386 message; some mailing list software moves the real 'Message-Id' to
387 'Resent-Message-Id' or 'X-Message-Id', then uses its own one in the
388 'Message-Id' header. The value returned for this symbol is the
389 text from all 3 headers, separated by newlines.
390 "X-Spam-Relays-Untrusted" is the generated metadata of untrusted
391 relays the message has passed through
392 "X-Spam-Relays-Trusted" is the generated metadata of trusted relays
393 the message has passed through
394 "X-Spam-Relays-External" is the generated metadata of external
395 relays the message has passed through
396 "X-Spam-Relays-Internal" is the generated metadata of internal
397 relays the message has passed through
398 $status->get_uri_list ()
399 Returns an array of all unique URIs found in the message. It takes
400 a combination of the URIs found in the rendered (decoded and HTML
401 stripped) body and the URIs found when parsing the HTML in the
402 message. Will also set $status->{uri_list} (the array as returned
403 by this function).
404 The returned array will include the "raw" URI as well as "slightly
406 cooked" versions. For example, the single URI
407 'http://%77w%77.example.com/' will get turned into: (
408 'http://%77w%77.example.com/', 'http://www.example.com/' )
409 $status->get_uri_detail_list ()
411 Returns a hash reference of all unique URIs found in the message
412 and various data about where the URIs were found in the message.
413 It takes a combination of the URIs found in the rendered (decoded
414 and HTML stripped) body and the URIs found when parsing the HTML in
415 the message. Will also set $status->{uri_detail_list} (the hash
416 reference as returned by this function).
417 The hash format looks something like this:
419 raw_uri => {
421 types => { a => 1, img => 1, parsed => 1, domainkeys => 1,
422 unlinked => 1, schemeless => 1 },
423 cleaned => [ canonicalized_uri ],
424 anchor_text => [ "click here", "no click here" ],
425 domains => { domain1 => 1, domain2 => 1 },
426 hosts => { host1 => domain1, host2 => domain2 },
427 }
428 "raw_uri" is whatever the URI was in the message itself
430 (http://spamassassin.apache%2Eorg/). Uris parsed from text will be
431 prefixed with scheme if missing (http://, mailto: etc). HTML uris
432 are as found.
433 "types" is a hash of the HTML tags (lowercase) which referenced the
435 raw_uri. parsed is a faked type which specifies that the raw_uri
436 was seen in the rendered text. domainkeys is defined when raw_uri
437 was found from DK/DKIM d= field. unlinked is defined when it's
438 assumed that MUA will not linkify uri (found in body without scheme
439 or www. prefix). schemeless is always added for uris without
440 scheme, regardless of linkifying (i.e. email address found in body
441 without mailto:).
442 "cleaned" is an array of the raw and canonicalized version of the
444 raw_uri (http://spamassassin.apache%2Eorg/,
445 https://spamassassin.apache.org/).
446 "anchor_text" is an array of the anchor text (text between <a> and
448 </a>), if any, which linked to the URI.
449 "domains" is a hash of the domains found in the canonicalized URIs.
451 "hosts" is a hash of unstripped hostnames found in the
453 canonicalized URIs as hash keys, with their domain part stored as a
454 value of each hash entry.
455 $status->add_uri_detail_list ($raw_uri, $types, $source, $valid_domain)
457 Adds values to internal uri_detail_list. When used from Plugins,
458 recommended to call from parsed_metadata (along with
459 register_method_priority, -10) so other Plugins calling
460 get_uri_detail_list() will see it.
461 "raw_uri" is the URI to be added. The only required parameter.
463 "types" is an optional hash reference, contents are added to
465 uri_detail_list->{types} (see get_uri_detail_list for known keys).
466 parsed is default is no hash given. nocanon does not run
467 uri_list_canonicalize (no redirector, uri fixing). noclean skips
468 adding uri_detail_list->{cleaned}, so it would not be used in "uri"
469 rule checks, but domain/hosts would still be used for URIBL/RBL
470 purposes.
471 "source" is an optional simple string, only used for debug logging
473 purposes to identify where uri originates from (default: "parsed").
474 "valid_domain" is an optional boolean (0/1). If true, uri will not
476 be added unless hostname/domain is in valid format and contains a
477 valid TLD. (default: 0)
478 $status->clear_test_state()
480 DEPRECATED, UNNEEDED SINCE 4.0
481 $status->got_hit ($rulename, $desc_prepend [, name => value, ...])
483 Register a hit against a rule in the ruleset.
484 There are two mandatory arguments. These are $rulename, the name of
486 the rule that fired, and $desc_prepend, which is a short string
487 that will be prepended to the rules "describe" string in output
488 reports.
489 In addition, callers can supplement that with the following
491 optional data:
492 score => $num
494 Optional: the score to use for the rule hit. If unspecified,
495 the value from the "Mail::SpamAssassin::Conf" object's
496 "{scores}" hash will be used (a configured score), and in its
497 absence the "defscore" option value.
498 defscore => $num
500 Optional: the score to use for the rule hit if neither the
501 option "score" is provided, nor a configured score value is
502 provided.
503 value => $num
505 Optional: the value to assign to the rule; the default value is
506 1. tflags multiple rules use values of greater than 1 to
507 indicate multiple hits. This value is accessible to meta
508 rules.
509 ruletype => $type
511 Optional, but recommended: the rule type string. This is used
512 in the "hit_rule" plugin call, called by this method. If
513 unset, 'unknown' is used.
514 tflags => $string
516 Optional: a string, i.e. a space-separated list of additional
517 tflags to be appended to an existing list of flags in
518 $self->{conf}->{tflags}, such as: "nice noautolearn multiple".
519 No syntax checks are performed.
520 description => $string
522 Optional: a custom rule description string. This is used in
523 the "hit_rule" plugin call, called by this method. If unset,
524 the static description is used.
525 Backward compatibility: the two mandatory arguments have been part
527 of this API since SpamAssassin 2.x. The optional name=<gtvalue>
528 pairs, however, are a new addition in SpamAssassin 3.2.0.
529 $status->rule_ready ($rulename [, $no_async])
531 Mark an asynchronous rule ready, so it can be considered for meta
532 rule evaluation. Asynchronous rule is a rule whose eval-function
533 returns undef, marking that it's not ready yet, expecting results
534 later. $status->rule_ready() must be called later to mark it
535 ready, alternatively $status->got_hit() also does this. If neither
536 is called, then any meta rule that depends on this rule might not
537 evaluate.
538 Optional boolean $no_async skips checking if there are pending
540 async DNS lookups for the rule.
541 $status->test_log ($text [, $rulename])
543 Add $text log entry for a hit rule in final message REPORT/SUMMARY.
544 Usually called just before got_hit(), to describe for example what
546 URI the rule matched on. Optional <$rulename> argument is
547 recommended to make sure log is written to correct rule. If
548 rulename is not provided, get_current_eval_rule_name() is used as
549 fallback.
550 Can be called multiple times per rule for additional entries.
552 $status->create_fulltext_tmpfile (fulltext_ref)
554 This function creates a temporary file containing the passed scalar
555 reference data. If no scalar is passed, full/pristine message text
556 is assumed. This is typically used by external programs like pyzor
557 and dccproc, to avoid hangs due to buffering issues.
558 All tempfiles are automatically cleaned up by PerMsgStatus
560 destructor.
561 $status->delete_fulltext_tmpfile (tmpfile)
563 Will cleanup after a $status->create_fulltext_tmpfile() call.
564 Deletes the temporary file and uncaches the filename. Generally
565 there no need to call this, PerMsgStatus destructor cleans up all
566 tmpfiles.
567 all_from_addrs_domains
569 This function returns all the various from addresses in a message
570 using all_from_addrs() and then returns only the domain names.
571
573 Mail::SpamAssassin(3) spamassassin(1)
574perl v5.36.0 2023-01-21Mail::SpamAssassin::PerMsgStatus(3)