You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spamassassin.apache.org by pa...@apache.org on 2011/06/22 17:01:03 UTC
svn commit: r1138498 [7/15] - in /spamassassin/site/full/3.3.x: ./ doc/
Added: spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PerMsgStatus.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PerMsgStatus.html?rev=1138498&view=auto
==============================================================================
--- spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PerMsgStatus.html (added)
+++ spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PerMsgStatus.html Wed Jun 22 15:00:59 2011
@@ -0,0 +1,506 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::PerMsgStatus - per-message status</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:parker@minotaur.apache.org" />
+</head>
+
+<body style="background-color: white">
+
+
+<!-- INDEX BEGIN -->
+<div name="index">
+<p><a name="__index__"></a></p>
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+
+<hr name="index" />
+</div>
+<!-- INDEX END -->
+
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::PerMsgStatus - per-message status (spam or not-spam)</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ my $spamtest = new Mail::SpamAssassin ({
+ 'rules_filename' => '/etc/spamassassin.rules',
+ 'userprefs_filename' => $ENV{HOME}.'/.spamassassin/user_prefs'
+ });
+ my $mail = $spamtest->parse();</pre>
+<pre>
+ my $status = $spamtest->check ($mail);</pre>
+<pre>
+ my $rewritten_mail;
+ if ($status->is_spam()) {
+ $rewritten_mail = $status->rewrite_mail ();
+ }
+ ...</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>The Mail::SpamAssassin <a href="#check"><code>check()</code></a> method returns an object of this
+class. This object encapsulates all the per-message state.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="check" class="item">$status->check ()</a></strong></dt>
+
+<dd>
+<p>Runs the SpamAssassin rules against the message pointed to by the object.</p>
+</dd>
+<dt><strong><a name="learn" class="item">$status-><code>learn()</code></a></strong></dt>
+
+<dd>
+<p>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.</p>
+</dd>
+<dt><strong><a name="get_autolearn_points" class="item">$score = $status-><code>get_autolearn_points()</code></a></strong></dt>
+
+<dd>
+<p>Return the message's score as computed for auto-learning. Certain tests are
+ignored:</p>
+<pre>
+ - rules with tflags set to 'learn' (the Bayesian rules)</pre>
+<pre>
+ - rules with tflags set to 'userconf' (user white/black-listing rules, etc)</pre>
+<pre>
+ - rules with tflags set to 'noautolearn'</pre>
+<p>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.</p>
+</dd>
+<dt><strong><a name="get_head_only_points" class="item">$score = $status-><code>get_head_only_points()</code></a></strong></dt>
+
+<dd>
+<p>Return the message's score as computed for auto-learning, ignoring
+all rules except for header-based ones.</p>
+</dd>
+<dt><strong><a name="get_learned_points" class="item">$score = $status-><code>get_learned_points()</code></a></strong></dt>
+
+<dd>
+<p>Return the message's score as computed for auto-learning, ignoring
+all rules except for learning-based ones.</p>
+</dd>
+<dt><strong><a name="get_body_only_points" class="item">$score = $status-><code>get_body_only_points()</code></a></strong></dt>
+
+<dd>
+<p>Return the message's score as computed for auto-learning, ignoring
+all rules except for body-based ones.</p>
+</dd>
+<dt><strong><a name="is_spam" class="item">$isspam = $status->is_spam ()</a></strong></dt>
+
+<dd>
+<p>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.</p>
+</dd>
+<dt><strong><a name="get_names_of_tests_hit" class="item">$list = $status->get_names_of_tests_hit ()</a></strong></dt>
+
+<dd>
+<p>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.</p>
+</dd>
+<dt><strong><a name="get_names_of_subtests_hit" class="item">$list = $status->get_names_of_subtests_hit ()</a></strong></dt>
+
+<dd>
+<p>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.</p>
+</dd>
+<dt><strong><a name="get_score" class="item">$num = $status->get_score ()</a></strong></dt>
+
+<dd>
+<p>After a mail message has been checked, this method can be called. It will
+return the message's score.</p>
+</dd>
+<dt><strong><a name="get_required_score" class="item">$num = $status->get_required_score ()</a></strong></dt>
+
+<dd>
+<p>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.</p>
+</dd>
+<dt><strong><a name="get_autolearn_status" class="item">$num = $status->get_autolearn_status ()</a></strong></dt>
+
+<dd>
+<p>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".</p>
+</dd>
+<dt><strong><a name="get_report" class="item">$report = $status->get_report ()</a></strong></dt>
+
+<dd>
+<p>Deliver a "spam report" on the checked mail message. This contains details of
+how many spam detection rules it triggered.</p>
+<p>The report is returned as a multi-line string, with the lines separated by
+<code>\n</code> characters.</p>
+</dd>
+<dt><strong><a name="get_content_preview" class="item">$preview = $status->get_content_preview ()</a></strong></dt>
+
+<dd>
+<p>Give a "preview" of the content.</p>
+<p>This is returned as a multi-line string, with the lines separated by <code>\n</code>
+characters, containing a fully-decoded, safe, plain-text sample of the first
+few lines of the message body.</p>
+</dd>
+<dt><strong><a name="get_message" class="item">$msg = $status-><code>get_message()</code></a></strong></dt>
+
+<dd>
+<p>Return the object representing the message being scanned.</p>
+</dd>
+<dt><strong><a name="rewrite_mail" class="item">$status->rewrite_mail ()</a></strong></dt>
+
+<dd>
+<p>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.</p>
+<p>The actual modifications depend on the configuration (see
+<code>Mail::SpamAssassin::Conf</code> for more information).</p>
+<p>The possible modifications are as follows:</p>
+<dl>
+<dt><strong><a name="to_from_and_subject_modification_on_spam_mails" class="item">To:, From: and Subject: modification on spam mails</a></strong></dt>
+
+<dd>
+<p>Depending on the configuration, the To: and From: lines can have a
+user-defined <a href="http://www.ietf.org/rfc/rfc2822.txt" class="rfc">RFC 2822</a> comment appended for spam mail. The subject line
+may have a user-defined string prepended to it for spam mail.</p>
+</dd>
+<dt><strong><a name="x_spam_headers_for_all_mails" class="item">X-Spam-* headers for all mails</a></strong></dt>
+
+<dd>
+<p>Depending on the configuration, zero or more headers with names
+beginning with <code>X-Spam-</code> will be added to mail depending on whether
+it is spam or ham.</p>
+</dd>
+<dt><strong><a name="spam_message_with_report_safe" class="item">spam message with report_safe</a></strong></dt>
+
+<dd>
+<p>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.</p>
+<p>If report_safe is set to false (0), then the message will only have the
+above headers added/modified.</p>
+</dd>
+</dl>
+</dd>
+<dt><strong><a name="set_tag" class="item">$status->set_tag($tagname, $value)</a></strong></dt>
+
+<dd>
+<p>Set a template tag, as used in <code>add_header</code>, report templates, etc. This API
+is intended for use by plugins. Tag names will be converted to an
+all-uppercase representation internally.</p>
+<p><code>$value</code> 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 <code>sub</code>.
+For example:</p>
+<pre>
+ my $text = "hello world!";
+ $status->set_tag("FOO", sub {
+ return $text;
+ });</pre>
+<p>See <code>Mail::SpamAssassin::Conf</code>'s <code>TEMPLATE TAGS</code> section for more details on
+how template tags are used.</p>
+<p><code>undef</code> will be returned if a tag by that name has not been defined.</p>
+</dd>
+<dt><strong><a name="get_tag" class="item">$string = $status-><code>get_tag($tagname)</code></a></strong></dt>
+
+<dd>
+<p>Get the current value of a template tag, as used in <code>add_header</code>, report
+templates, etc. This API is intended for use by plugins. Tag names will be
+converted to an all-uppercase representation internally. See
+<code>Mail::SpamAssassin::Conf</code>'s <code>TEMPLATE TAGS</code> section for more details on
+tags.</p>
+<p><code>undef</code> will be returned if a tag by that name has not been defined.</p>
+</dd>
+<dt><strong><a name="set_spamd_result_item" class="item">$status-><code>set_spamd_result_item($subref)</code></a></strong></dt>
+
+<dd>
+<p>Set an entry for the spamd result log line. <code>$subref</code> should be a code
+reference for a subroutine which will return a string in <code>'name=VALUE'</code>
+format, similar to the other entries in the spamd result line:</p>
+<pre>
+ 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</pre>
+<p><code>name</code> and <code>VALUE</code> must not contain <code>=</code> or <code>,</code> characters, as it
+is important that these log lines are easy to parse.</p>
+<p>The code reference will be called by spamd after the message has been scanned,
+and the <a href="#check"><code>PerMsgStatus::check()</code></a> method has returned.</p>
+</dd>
+<dt><strong><a name="finish" class="item">$status->finish ()</a></strong></dt>
+
+<dd>
+<p>Indicate that this <code>$status</code> object is finished with, and can be destroyed.</p>
+<p>If you are using SpamAssassin in a persistent environment, or checking many
+mail messages from one <code>Mail::SpamAssassin</code> factory, this method should be
+called to ensure Perl's garbage collection will clean up old status objects.</p>
+</dd>
+<dt><strong><a name="get_current_eval_rule_name" class="item">$name = $status-><code>get_current_eval_rule_name()</code></a></strong></dt>
+
+<dd>
+<p>Return the name of the currently-running eval rule. <code>undef</code> 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.</p>
+</dd>
+<dt><strong><a name="get_decoded_body_text_array" class="item">$status->get_decoded_body_text_array ()</a></strong></dt>
+
+<dd>
+<p>Returns the message body, with <strong>base64</strong> or <strong>quoted-printable</strong> encodings
+decoded, and non-text parts or non-inline attachments stripped.</p>
+<p>It is returned as an array of strings, with each string representing
+one newline-separated line of the body.</p>
+</dd>
+<dt><strong><a name="get_decoded_stripped_body_text_array" class="item">$status->get_decoded_stripped_body_text_array ()</a></strong></dt>
+
+<dd>
+<p>Returns the message body, decoded (as described in
+get_decoded_body_text_array()), with HTML rendered, and with whitespace
+normalized.</p>
+<p>It will always render text/html, and will use a heuristic to determine if other
+text/* parts should be considered text/html.</p>
+<p>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.</p>
+</dd>
+<dt><strong><a name="get" class="item">$status->get (header_name [, default_value])</a></strong></dt>
+
+<dd>
+<p>Returns a message header, pseudo-header, real name or address.
+<code>header_name</code> is the name of a mail header, such as 'Subject', 'To',
+etc. If <code>default_value</code> is given, it will be used if the requested
+<code>header_name</code> does not exist.</p>
+<p>Appending <code>:raw</code> to the header name will inhibit decoding of quoted-printable
+or base-64 encoded strings.</p>
+<p>Appending <code>:addr</code> 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":</p>
+<dl>
+<dt><strong><a name="example_foo2" class="item">example@foo</a></strong></dt>
+
+<dt><strong><a name="foo" class="item">example@foo (Foo Blah)</a></strong></dt>
+
+<dt><strong><a name="example_foo_example_bar2" class="item">example@foo, example@bar</a></strong></dt>
+
+<dt><strong>display: example@foo (Foo Blah), example@bar ;</strong></dt>
+
+<dt><strong><a name="foo_blah_example_foo7" class="item">Foo Blah <example@foo></a></strong></dt>
+
+<dt><strong><a name="foo_blah_example_foo8" class="item">"Foo Blah" <example@foo></a></strong></dt>
+
+<dt><strong><a name="foo_blah_example_foo9" class="item">"'Foo Blah'" <example@foo></a></strong></dt>
+
+</dl>
+<p>Appending <code>:name</code> to the header name will cause everything except
+the first display name to be removed from the header. For example,
+all of the following will result in "Foo Blah"</p>
+<dl>
+<dt><strong>example@foo (Foo Blah)</strong></dt>
+
+<dt><strong>example@foo (Foo Blah), example@bar</strong></dt>
+
+<dt><strong>display: example@foo (Foo Blah), example@bar ;</strong></dt>
+
+<dt><strong><a name="foo_blah_example_foo10" class="item">Foo Blah <example@foo></a></strong></dt>
+
+<dt><strong><a name="foo_blah_example_foo11" class="item">"Foo Blah" <example@foo></a></strong></dt>
+
+<dt><strong><a name="foo_blah_example_foo12" class="item">"'Foo Blah'" <example@foo></a></strong></dt>
+
+</dl>
+<p>There are several special pseudo-headers that can be specified:</p>
+<dl>
+<dt><strong><a name="all_can_be_used_to_mean_the_text_of_all_the_message_s_headers" class="item"><code>ALL</code> can be used to mean the text of all the message's headers.</a></strong></dt>
+
+<dt><strong><a name="all_trusted_can_be_used_to_mean_the_text_of_all_the_message_s_headers_that_could_only_have_been_added_by_trusted_relays" class="item"><code>ALL-TRUSTED</code> can be used to mean the text of all the message's headers
+that could only have been added by trusted relays.</a></strong></dt>
+
+<dt><strong><a name="all_internal_can_be_used_to_mean_the_text_of_all_the_message_s_headers_that_could_only_have_been_added_by_internal_relays" class="item"><code>ALL-INTERNAL</code> can be used to mean the text of all the message's headers
+that could only have been added by internal relays.</a></strong></dt>
+
+<dt><strong><a name="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" class="item"><code>ALL-UNTRUSTED</code> 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.</a></strong></dt>
+
+<dt><strong><a name="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" class="item"><code>ALL-EXTERNAL</code> can be used to mean the text of all the message's headers
+that may have been added by external relays. Like <code>ALL-UNTRUSTED</code> the
+'Received' header added by the last internal relay is included.</a></strong></dt>
+
+<dt><strong><a name="tocc_can_be_used_to_mean_the_contents_of_both_the_to_and_cc_headers2" class="item"><code>ToCc</code> can be used to mean the contents of both the 'To' and 'Cc'
+headers.</a></strong></dt>
+
+<dt><strong><a name="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" class="item"><code>EnvelopeFrom</code> 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.</a></strong></dt>
+
+<dt><strong><a name="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" class="item"><code>MESSAGEID</code> 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.</a></strong></dt>
+
+<dt><strong><a name="x_spam_relays_untrusted_is_the_generated_metadata_of_untrusted_relays_the_message_has_passed_through" class="item"><code>X-Spam-Relays-Untrusted</code> is the generated metadata of untrusted relays
+the message has passed through</a></strong></dt>
+
+<dt><strong><a name="x_spam_relays_trusted_is_the_generated_metadata_of_trusted_relays_the_message_has_passed_through" class="item"><code>X-Spam-Relays-Trusted</code> is the generated metadata of trusted relays
+the message has passed through</a></strong></dt>
+
+</dl>
+</dd>
+<dt><strong><a name="get_uri_list" class="item">$status->get_uri_list ()</a></strong></dt>
+
+<dd>
+<p>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_list} (the array as returned by this function).</p>
+<p>The returned array will include the "raw" URI as well as
+"slightly cooked" versions. For example, the single URI
+'http://%77&#00119;%77.example.com/' will get turned into:
+( 'http://%77&#00119;%77.example.com/', 'http://www.example.com/' )</p>
+</dd>
+<dt><strong><a name="get_uri_detail_list" class="item">$status->get_uri_detail_list ()</a></strong></dt>
+
+<dd>
+<p>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 HTML stripped)
+body and the URIs found when parsing the HTML in the message. Will also
+set $status->{uri_detail_list} (the hash reference as returned by this
+function). This function will also set $status->{uri_domain_count} (count of
+unique domains).</p>
+<p>The hash format looks something like this:</p>
+<pre>
+ raw_uri => {
+ types => { a => 1, img => 1, parsed => 1 },
+ cleaned => [ canonified_uri ],
+ anchor_text => [ "click here", "no click here" ],
+ domains => { domain1 => 1, domain2 => 1 },
+ }</pre>
+<p><code>raw_uri</code> is whatever the URI was in the message itself
+(http://spamassassin.apache%2Eorg/).</p>
+<p><code>types</code> is a hash of the HTML tags (lowercase) which referenced
+the raw_uri. <em>parsed</em> is a faked type which specifies that the
+raw_uri was seen in the rendered text.</p>
+<p><code>cleaned</code> is an array of the raw and canonified version of the raw_uri
+(http://spamassassin.apache%2Eorg/, <a href="http://spamassassin.apache.org/).">http://spamassassin.apache.org/).</a></p>
+<p><code>anchor_text</code> is an array of the anchor text (text between <a> and
+</a>), if any, which linked to the URI.</p>
+<p><code>domains</code> is a hash of the domains found in the canonified URIs.</p>
+</dd>
+<dt><strong><a name="clear_test_state" class="item">$status-><code>clear_test_state()</code></a></strong></dt>
+
+<dd>
+<p>Clear test state, including test log messages from <code>$status->test_log()</code>.</p>
+</dd>
+<dt><strong><a name="got_hit" class="item">$status->got_hit ($rulename, $desc_prepend [, name => value, ...])</a></strong></dt>
+
+<dd>
+<p>Register a hit against a rule in the ruleset.</p>
+<p>There are two mandatory arguments. These are <code>$rulename</code>, the name of the rule
+that fired, and <code>$desc_prepend</code>, which is a short string that will be
+prepended to the rules <code>describe</code> string in output reports.</p>
+<p>In addition, callers can supplement that with the following optional
+data:</p>
+<dl>
+<dt><strong><a name="score_num" class="item">score => $num</a></strong></dt>
+
+<dd>
+<p>Optional: the score to use for the rule hit. If unspecified,
+the value from the <code>Mail::SpamAssassin::Conf</code> object's <code>{scores}</code>
+hash will be used (a configured score), and in its absence the
+<code>defscore</code> option value.</p>
+</dd>
+<dt><strong><a name="defscore_num" class="item">defscore => $num</a></strong></dt>
+
+<dd>
+<p>Optional: the score to use for the rule hit if neither the
+option <code>score</code> is provided, nor a configured score value is provided.</p>
+</dd>
+<dt><strong><a name="value_num" class="item">value => $num</a></strong></dt>
+
+<dd>
+<p>Optional: the value to assign to the rule; the default value is <code>1</code>.
+<em>tflags multiple</em> rules use values of greater than 1 to indicate
+multiple hits. This value is accessible to meta rules.</p>
+</dd>
+<dt><strong><a name="ruletype_type" class="item">ruletype => $type</a></strong></dt>
+
+<dd>
+<p>Optional, but recommended: the rule type string. This is used in the
+<code>hit_rule</code> plugin call, called by this method. If unset, <em>'unknown'</em> is
+used.</p>
+</dd>
+<dt><strong><a name="tflags_string" class="item">tflags => $string</a></strong></dt>
+
+<dd>
+<p>Optional: a string, i.e. a space-separated list of additional tflags
+to be appended to an existing list of flags in $self->{conf}->{tflags},
+such as: "nice noautolearn multiple". No syntax checks are performed.</p>
+</dd>
+<dt><strong><a name="description_string" class="item">description => $string</a></strong></dt>
+
+<dd>
+<p>Optional: a custom rule description string. This is used in the
+<code>hit_rule</code> plugin call, called by this method. If unset, the static
+description is used.</p>
+</dd>
+</dl>
+<p>Backwards compatibility: the two mandatory arguments have been part of this API
+since SpamAssassin 2.x. The optional <em>name=<gt</em>value> pairs, however, are a
+new addition in SpamAssassin 3.2.0.</p>
+</dd>
+<dt><strong><a name="create_fulltext_tmpfile" class="item">$status->create_fulltext_tmpfile (fulltext_ref)</a></strong></dt>
+
+<dd>
+<p>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-><a href="#create_fulltext_tmpfile"><code>create_fulltext_tmpfile($fulltext)</code></a> to retrieve the temporary
+filename; it will be created if it has not already been.</p>
+<p>Note: This can only be called once until $status-><a href="#delete_fulltext_tmpfile"><code>delete_fulltext_tmpfile()</code></a> is
+called.</p>
+</dd>
+<dt><strong><a name="delete_fulltext_tmpfile" class="item">$status->delete_fulltext_tmpfile ()</a></strong></dt>
+
+<dd>
+<p>Will cleanup after a $status-><a href="#create_fulltext_tmpfile"><code>create_fulltext_tmpfile()</code></a> call. Deletes the
+temporary file and uncaches the filename.</p>
+</dd>
+</dl>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><code>Mail::SpamAssassin</code>
+<code>spamassassin</code></p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PerMsgStatus.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PerMsgStatus.txt?rev=1138498&view=auto
==============================================================================
--- spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PerMsgStatus.txt (added)
+++ spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PerMsgStatus.txt Wed Jun 22 15:00:59 2011
@@ -0,0 +1,400 @@
+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);
+
+ my $rewritten_mail;
+ if ($status->is_spam()) {
+ $rewritten_mail = $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.
+
+ $score = $status->get_autolearn_points()
+ Return the message's score as computed for auto-learning. Certain
+ tests are ignored:
+
+ - 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.
+
+ $score = $status->get_head_only_points()
+ Return the message's score as computed for auto-learning, ignoring
+ all rules except for header-based ones.
+
+ $score = $status->get_learned_points()
+ Return the message's score as computed for auto-learning, ignoring
+ all rules except for learning-based ones.
+
+ $score = $status->get_body_only_points()
+ Return the message's score as computed for auto-learning, ignoring
+ all rules except for body-based ones.
+
+ $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->set_tag($tagname, $value)
+ Set a template tag, as used in "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.
+
+ $string = $status->get_tag($tagname)
+ Get the current value of a template tag, as used in "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.
+
+ $status->set_spamd_result_item($subref)
+ Set an entry for the spamd result log line. $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->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_decoded_body_text_array ()
+ Returns the message body, with base64 or quoted-printable encodings
+ decoded, and non-text parts or non-inline attachments stripped.
+
+ It is returned as an array of strings, with each string representing
+ one newline-separated line of the body.
+
+ $status->get_decoded_stripped_body_text_array ()
+ Returns the message body, decoded (as described in
+ get_decoded_body_text_array()), with HTML rendered, and with
+ whitespace normalized.
+
+ 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.
+
+ $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 <ex...@foo>
+ "Foo Blah" <ex...@foo>
+ "'Foo Blah'" <ex...@foo>
+
+ Appending ":name" to the header name will cause everything except
+ the first display 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 <ex...@foo>
+ "Foo Blah" <ex...@foo>
+ "'Foo Blah'" <ex...@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.
+ "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 through
+ "X-Spam-Relays-Trusted" is the generated metadata of trusted relays
+ the message has passed through
+
+ $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_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->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
+ HTML stripped) body and the URIs found when parsing the HTML in the
+ message. Will also set $status->{uri_detail_list} (the hash
+ reference as returned by this function). This function will also set
+ $status->{uri_domain_count} (count of unique domains).
+
+ 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.
+
+ $status->clear_test_state()
+ Clear test state, including test log messages from
+ "$status->test_log()".
+
+ $status->got_hit ($rulename, $desc_prepend [, name => value, ...])
+ Register a hit against a rule in the ruleset.
+
+ 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:
+
+ score => $num
+ Optional: the score to use for the rule hit. If unspecified, the
+ value from the "Mail::SpamAssassin::Conf" object's "{scores}"
+ hash will be used (a configured score), and in its absence the
+ "defscore" option value.
+
+ defscore => $num
+ Optional: the score to use for the rule hit if neither the
+ option "score" is provided, nor a configured score value is
+ provided.
+
+ value => $num
+ Optional: the value to assign to the rule; the default value is
+ 1. *tflags multiple* rules use values of greater than 1 to
+ indicate multiple hits. This value is accessible to meta rules.
+
+ ruletype => $type
+ Optional, but recommended: the rule type string. This is used in
+ the "hit_rule" plugin call, called by this method. If unset,
+ *'unknown'* is used.
+
+ tflags => $string
+ Optional: a string, i.e. a space-separated list of additional
+ tflags to be appended to an existing list of flags in
+ $self->{conf}->{tflags}, such as: "nice noautolearn multiple".
+ No syntax checks are performed.
+
+ description => $string
+ Optional: a custom rule description string. This is used in the
+ "hit_rule" plugin call, called by this method. If unset, the
+ static description is used.
+
+ Backwards compatibility: the two mandatory arguments have been part
+ of this API since SpamAssassin 2.x. The optional *name=<gt*value>
+ pairs, however, are a new addition in SpamAssassin 3.2.0.
+
+ $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"
+
Added: spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PersistentAddrList.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PersistentAddrList.html?rev=1138498&view=auto
==============================================================================
--- spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PersistentAddrList.html (added)
+++ spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PersistentAddrList.html Wed Jun 22 15:00:59 2011
@@ -0,0 +1,107 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::PersistentAddrList - persistent address list base class</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:parker@minotaur.apache.org" />
+</head>
+
+<body style="background-color: white">
+
+
+<!-- INDEX BEGIN -->
+<div name="index">
+<p><a name="__index__"></a></p>
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+</ul>
+
+<hr name="index" />
+</div>
+<!-- INDEX END -->
+
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::PersistentAddrList - persistent address list base class</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ my $factory = PersistentAddrListSubclass->new();
+ $spamtest->set_persistent_addr_list_factory ($factory);
+ ... call into SpamAssassin classes...</pre>
+<p>SpamAssassin will call:</p>
+<pre>
+ my $addrlist = $factory->new_checker($spamtest);
+ $entry = $addrlist->get_addr_entry ($addr);
+ ...</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>All persistent address list implementations, used by the auto-whitelist
+code to track known-good email addresses, use this as a base class.</p>
+<p>See <code>Mail::SpamAssassin::DBBasedAddrList</code> for an example.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="new" class="item">$factory = PersistentAddrListSubclass-><code>new()</code>;</a></strong></dt>
+
+<dd>
+<p>This creates a factory object, which SpamAssassin will call to create
+a new checker object for the persistent address list.</p>
+</dd>
+<dt><strong><a name="new_checker" class="item">my $addrlist = $factory-><code>new_checker()</code>;</a></strong></dt>
+
+<dd>
+<p>Create a new address-list checker object from the factory. Called by the
+SpamAssassin classes.</p>
+</dd>
+<dt><strong><a name="get_addr_entry" class="item">$entry = $addrlist->get_addr_entry ($addr);</a></strong></dt>
+
+<dd>
+<p>Given an email address <code>$addr</code>, return an entry object with the details of
+that address.</p>
+<p>The entry object is a reference to a hash, which must contain at least
+two keys: <code>count</code>, which is the count of times that address has been
+encountered before; and <code>totscore</code>, which is the total of all scores for
+messages associated with that address. From these two fields, an average
+score will be calculated, and the score for the current message will be
+regressed towards that mean message score.</p>
+<p>The hash can contain whatever other data your back-end needs to store,
+under other keys.</p>
+<p>The method should never return <code>undef</code>, or a hash that does not contain
+a <code>count</code> key and a <code>totscore</code> key.</p>
+</dd>
+<dt><strong><a name="add_score" class="item">$entry = $addrlist->add_score($entry, $score);</a></strong></dt>
+
+<dd>
+<p>This method should add the given score to the whitelist database for the
+given entry, and then return the new entry.</p>
+</dd>
+<dt><strong><a name="remove_entry" class="item">$entry = $addrlist->remove_entry ($entry);</a></strong></dt>
+
+<dd>
+<p>This method should remove the given entry from the whitelist database.</p>
+</dd>
+<dt><strong><a name="finish" class="item">$entry = $addrlist->finish ();</a></strong></dt>
+
+<dd>
+<p>Clean up, if necessary. Called by SpamAssassin when it has finished
+checking, or adding to, the auto-whitelist database.</p>
+</dd>
+</dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PersistentAddrList.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PersistentAddrList.txt?rev=1138498&view=auto
==============================================================================
--- spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PersistentAddrList.txt (added)
+++ spamassassin/site/full/3.3.x/doc/Mail_SpamAssassin_PersistentAddrList.txt Wed Jun 22 15:00:59 2011
@@ -0,0 +1,59 @@
+NAME
+ Mail::SpamAssassin::PersistentAddrList - persistent address list base
+ class
+
+SYNOPSIS
+ my $factory = PersistentAddrListSubclass->new();
+ $spamtest->set_persistent_addr_list_factory ($factory);
+ ... call into SpamAssassin classes...
+
+ SpamAssassin will call:
+
+ my $addrlist = $factory->new_checker($spamtest);
+ $entry = $addrlist->get_addr_entry ($addr);
+ ...
+
+DESCRIPTION
+ All persistent address list implementations, used by the auto-whitelist
+ code to track known-good email addresses, use this as a base class.
+
+ See "Mail::SpamAssassin::DBBasedAddrList" for an example.
+
+METHODS
+ $factory = PersistentAddrListSubclass->new();
+ This creates a factory object, which SpamAssassin will call to
+ create a new checker object for the persistent address list.
+
+ my $addrlist = $factory->new_checker();
+ Create a new address-list checker object from the factory. Called by
+ the SpamAssassin classes.
+
+ $entry = $addrlist->get_addr_entry ($addr);
+ Given an email address $addr, return an entry object with the
+ details of that address.
+
+ The entry object is a reference to a hash, which must contain at
+ least two keys: "count", which is the count of times that address
+ has been encountered before; and "totscore", which is the total of
+ all scores for messages associated with that address. From these two
+ fields, an average score will be calculated, and the score for the
+ current message will be regressed towards that mean message score.
+
+ The hash can contain whatever other data your back-end needs to
+ store, under other keys.
+
+ The method should never return "undef", or a hash that does not
+ contain a "count" key and a "totscore" key.
+
+ $entry = $addrlist->add_score($entry, $score);
+ This method should add the given score to the whitelist database for
+ the given entry, and then return the new entry.
+
+ $entry = $addrlist->remove_entry ($entry);
+ This method should remove the given entry from the whitelist
+ database.
+
+ $entry = $addrlist->finish ();
+ Clean up, if necessary. Called by SpamAssassin when it has finished
+ checking, or adding to, the auto-whitelist database.
+