<!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 - Mail::Audit spam detector plugin</title>
<link rev="made" href="mailto:root@localhost" />
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<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="#prerequisites">PREREQUISITES</a></li>
<li><a href="#corequisites">COREQUISITES</a></li>
<li><a href="#more_documentation">MORE DOCUMENTATION</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<li><a href="#author">AUTHOR</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
<li><a href="#availability">AVAILABILITY</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Mail::SpamAssassin - Mail::Audit spam detector plugin</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
my $mail = Mail::SpamAssassin::NoMailAudit->new();</pre>
<pre>
my $spamtest = Mail::SpamAssassin->new();
my $status = $spamtest->check ($mail);</pre>
<pre>
if ($status->is_spam ()) {
$status->rewrite_mail ();
$mail->accept("spamfolder");</pre>
<pre>
} else {
$mail->accept(); # to default incoming mailbox
}
...</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>Mail::SpamAssassin is a module to identify spam using text analysis and several
internet-based realtime blacklists.</p>
<p>Using its rule base, it uses a wide range of heuristic tests on mail headers
and body text to identify ``spam'', also known as unsolicited commercial email.</p>
<p>Once identified, the mail can then be optionally tagged as spam for later
filtering using the user's own mail user-agent application.</p>
<p>This module also implements a Mail::Audit plugin, allowing SpamAssassin to be
used in a Mail::Audit filter. If you wish to use a command-line filter tool,
try the <code>spamassassin</code> or <code>spamd</code> tools provided.</p>
<p>Note that, if you're using Mail::Audit, the constructor for the Mail::Audit
object must use the <code>nomime</code> option, like so:</p>
<pre>
my $ma = new Mail::Audit ( nomime => 1 );</pre>
<p>SpamAssassin also includes support for reporting spam messages to collaborative
filtering databases, such as Vipul's Razor ( <a href="http://razor.sourceforge.net/">http://razor.sourceforge.net/</a> ).</p>
<p>
</p>
<hr />
<h1><a name="methods">METHODS</a></h1>
<dl>
<dt><strong><a name="item_spamassassin">$f = new Mail::SpamAssassin( [ { opt => val, ... } ] )</a></strong><br />
</dt>
<dd>
Constructs a new <code>Mail::SpamAssassin</code> object. You may pass the
following attribute-value pairs to the constructor.
</dd>
<dl>
<dt><strong><a name="item_rules_filename">rules_filename</a></strong><br />
</dt>
<dd>
The filename to load spam-identifying rules from. (optional)
</dd>
<p></p>
<dt><strong><a name="item_userprefs_filename">userprefs_filename</a></strong><br />
</dt>
<dd>
The filename to load preferences from. (optional)
</dd>
<p></p>
<dt><strong><a name="item_userstate_dir">userstate_dir</a></strong><br />
</dt>
<dd>
The directory user state is stored in. (optional)
</dd>
<p></p>
<dt><strong><a name="item_config_text">config_text</a></strong><br />
</dt>
<dd>
The text of all rules and preferences. If you prefer not to load the rules
from files, read them in yourself and set this instead. As a result, this will
override the settings for <a href="#item_rules_filename"><code>rules_filename</code></a> and <a href="#item_userprefs_filename"><code>userprefs_filename</code></a>.
</dd>
<p></p>
<dt><strong><a name="item_local_tests_only">local_tests_only</a></strong><br />
</dt>
<dd>
If set to 1, no tests that require internet access will be performed. (default:
0)
</dd>
<p></p>
<dt><strong><a name="item_dont_copy_prefs">dont_copy_prefs</a></strong><br />
</dt>
<dd>
If set to 1, the user preferences file will not be created if it doesn't
already exist. (default: 0)
</dd>
<p></p>
<dt><strong><a name="item_save_pattern_hits">save_pattern_hits</a></strong><br />
</dt>
<dd>
If set to 1, the patterns hit can be retrieved from the
<code>Mail::SpamAssassin::PerMsgStatus</code> object. Used for debugging.
</dd>
<p></p>
<dt><strong><a name="item_home_dir_for_helpers">home_dir_for_helpers</a></strong><br />
</dt>
<dd>
If set, the <strong>HOME</strong> environment variable will be set to this value
when using test applications that require their configuration data,
such as Razor, Pyzor and DCC.
</dd>
<p></p></dl>
<p>If none of <a href="#item_rules_filename"><code>rules_filename</code></a>, <a href="#item_userprefs_filename"><code>userprefs_filename</code></a>, or <a href="#item_config_text"><code>config_text</code></a> is set,
the <code>Mail::SpamAssassin</code> module will search for the configuration files in the
usual installed locations.</p>
<dt><strong><a name="item_check">$status = $f->check ($mail)</a></strong><br />
</dt>
<dd>
Check a mail, encapsulated in a <code>Mail::Audit</code> object, to determine if
it is spam or not.
</dd>
<dd>
<p>Returns a <code>Mail::SpamAssassin::PerMsgStatus</code> object which can be
used to test or manipulate the mail message.</p>
</dd>
<dd>
<p>Note that the <code>Mail::SpamAssassin</code> object can be re-used for further messages
without affecting this check; in OO terminology, the <code>Mail::SpamAssassin</code>
object is a ``factory''. However, if you do this, be sure to call the
<code>finish()</code> method on the status objects when you're done with them.</p>
</dd>
<p></p>
<dt><strong><a name="item_check_message_text">$status = $f->check_message_text ($mailtext)</a></strong><br />
</dt>
<dd>
Check a mail, encapsulated in a plain string, to determine if it is spam or
not.
</dd>
<dd>
<p>Otherwise identical to <code>$f-</code>check()> above.</p>
</dd>
<p></p>
<dt><strong><a name="item_report_as_spam">$f->report_as_spam ($mail, $options)</a></strong><br />
</dt>
<dd>
Report a mail, encapsulated in a <code>Mail::Audit</code> object, as human-verified spam.
This will submit the mail message to live, collaborative, spam-blocker
databases, allowing other users to block this message.
</dd>
<dd>
<p>Options is an optional reference to a hash of options. Currently these
can be:</p>
</dd>
<dl>
<dt><strong><a name="item_dont_report_to_razor">dont_report_to_razor</a></strong><br />
</dt>
<dd>
Inhibits reporting of the spam to Razor; useful if you know it's already
been listed there.
</dd>
<p></p></dl>
<dt><strong><a name="item_add_address_to_whitelist">$f->add_address_to_whitelist ($addr)</a></strong><br />
</dt>
<dd>
Given a string containing an email address, add it to the automatic
whitelist database.
</dd>
<p></p>
<dt><strong><a name="item_add_all_addresses_to_whitelist">$f->add_all_addresses_to_whitelist ($mail)</a></strong><br />
</dt>
<dd>
Given a mail message, find as many addresses in the usual headers (To, Cc, From
etc.), and the message body, and add them to the automatic whitelist database.
</dd>
<p></p>
<dt><strong><a name="item_remove_address_from_whitelist">$f->remove_address_from_whitelist ($addr)</a></strong><br />
</dt>
<dd>
Given a string containing an email address, remove it from the automatic
whitelist database.
</dd>
<p></p>
<dt><strong><a name="item_remove_all_addresses_from_whitelist">$f->remove_all_addresses_from_whitelist ($mail)</a></strong><br />
</dt>
<dd>
Given a mail message, find as many addresses in the usual headers (To, Cc, From
etc.), and the message body, and remove them from the automatic whitelist
database.
</dd>
<p></p>
<dt><strong><a name="item_add_address_to_blacklist">$f->add_address_to_blacklist ($addr)</a></strong><br />
</dt>
<dd>
Given a string containing an email address, add it to the automatic
whitelist database with a high score, effectively blacklisting them.
</dd>
<p></p>
<dt><strong><a name="item_add_all_addresses_to_blacklist">$f->add_all_addresses_to_blacklist ($mail)</a></strong><br />
</dt>
<dd>
Given a mail message, find as many addresses in the usual headers (To,
Cc, From etc.), and the message body, and adds them to the automatic
whitelist database with a high score, effectively blacklisting them.
</dd>
<p></p>
<dt><strong><a name="item_reply_with_warning">$f->reply_with_warning ($mail, $replysender)</a></strong><br />
</dt>
<dd>
Reply to the sender of a mail, encapsulated in a <code>Mail::Audit</code> object,
explaining that their message has been added to spam-tracking databases
and deleted. To be used in conjunction with <a href="#item_report_as_spam"><code>report_as_spam</code></a>. The
<code>$replysender</code> argument should contain an email address to use as the
sender of the reply message.
</dd>
<p></p>
<dt><strong><a name="item_remove_spamassassin_markup">$text = $f->remove_spamassassin_markup ($mail)</a></strong><br />
</dt>
<dd>
Returns the text of the message, with any SpamAssassin-added text (such
as the report, or X-Spam-Status headers) stripped.
</dd>
<dd>
<p>Note that the <strong>$mail</strong> object is not modified.</p>
</dd>
<p></p>
<dt><strong><a name="item_read_scoreonly_config">$f->read_scoreonly_config ($filename)</a></strong><br />
</dt>
<dd>
Read a configuration file and parse only scores from it. This is used
to safely allow multi-user daemons to read per-user config files
without having to use <code>setuid()</code>.
</dd>
<p></p>
<dt><strong><a name="item_load_scoreonly_sql">$f->load_scoreonly_sql ($username)</a></strong><br />
</dt>
<dd>
Read configuration paramaters from SQL database and parse scores from it. This
will only take effect if the perl <code>DBI</code> module is installed, and the
configuration parameters <code>user_scores_dsn</code>, <code>user_scores_sql_username</code>, and
<code>user_scores_sql_password</code> are set correctly.
</dd>
<p></p>
<dt><strong><a name="item_set_persistent_address_list_factory">$f->set_persistent_address_list_factory ($factoryobj)</a></strong><br />
</dt>
<dd>
Set the persistent address list factory, used to create objects for the
automatic whitelist algorithm's persistent-storage back-end. See
<code>Mail::SpamAssassin::PersistentAddrList</code> for the API these factory objects
must implement, and the API the objects they produce must implement.
</dd>
<p></p>
<dt><strong><a name="item_compile_now">$f->compile_now ($use_user_prefs)</a></strong><br />
</dt>
<dd>
Compile all patterns, load all configuration files, and load all
possibly-required Perl modules.
</dd>
<dd>
<p>Normally, Mail::SpamAssassin uses lazy evaluation where possible, but if you
plan to <code>fork()</code> or start a new perl interpreter thread to process a message,
this is suboptimal, as each process/thread will have to perform these actions.</p>
</dd>
<dd>
<p>Call this function in the master thread or process to perform the actions
straightaway, so that the sub-processes will not have to.</p>
</dd>
<dd>
<p>If <code>$use_user_prefs</code> is 0, this will initialise the SpamAssassin
configuration without reading the per-user configuration file and it will
assume that you will call <a href="#item_read_scoreonly_config"><code>read_scoreonly_config</code></a> at a later point.</p>
</dd>
<p></p>
<dt><strong><a name="item_lint_rules">$failed = $f->lint_rules ()</a></strong><br />
</dt>
<dd>
Syntax-check the current set of rules. Returns the number of
syntax errors discovered, or 0 if the configuration is valid.
</dd>
<p></p>
<dt><strong><a name="item_init">$f->init ($use_user_prefs)</a></strong><br />
</dt>
<dd>
Read and parse the current configuration. <code>$use_user_prefs</code> can
be <code>0</code> (do not read user preferences) or <code>1</code> (do).
</dd>
<p></p>
<dt><strong><a name="item_create_default_prefs">$f->create_default_prefs ()</a></strong><br />
</dt>
<dd>
Copy default prefs file into home directory for later use and modification.
</dd>
<p></p></dl>
<p>
</p>
<hr />
<h1><a name="prerequisites">PREREQUISITES</a></h1>
<p><code>Mail::Audit</code>
<code>Mail::Internet</code></p>
<p>
</p>
<hr />
<h1><a name="corequisites">COREQUISITES</a></h1>
<p><code>Net::DNS</code></p>
<p>
</p>
<hr />
<h1><a name="more_documentation">MORE DOCUMENTATION</a></h1>
<p>See also <a href="http://spamassassin.org/">http://spamassassin.org/</a> for more information.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><code>Mail::SpamAssassin::Conf</code>
<code>Mail::SpamAssassin::PerMsgStatus</code>
<code>spamassassin</code></p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Justin Mason <jm /at/ jmason.org></p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>SpamAssassin is distributed under Perl's Artistic license.</p>
<p>
</p>
<hr />
<h1><a name="availability">AVAILABILITY</a></h1>
<p>The latest version of this library is likely to be available from CPAN
as well as:</p>
<pre>
<a href="http://spamassassin.org/">http://spamassassin.org/</a></pre>
</body>
</html>
