NAME
SYNOPSIS
DESCRIPTION
METHODS
PREREQUISITES
COREQUISITES
MORE DOCUMENTATION
SEE ALSO
BUGS
AUTHOR
COPYRIGHT
AVAILABILITY

NAME

Mail::SpamAssassin - Mail::Audit spam detector plugin

SYNOPSIS

  my $mail = Mail::SpamAssassin::NoMailAudit->new();

  my $spamtest = Mail::SpamAssassin->new();
  my $status = $spamtest->check ($mail);

  if ($status->is_spam ()) {
    $status->rewrite_mail ();
    $mail->accept("spamfolder");

  } else {
    $mail->accept();            # to default incoming mailbox
  }
  ...

DESCRIPTION

Mail::SpamAssassin is a module to identify spam using text analysis and several internet-based realtime blacklists.

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.

Once identified, the mail can then be optionally tagged as spam for later filtering using the user's own mail user-agent application.

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 spamassassin or spamd tools provided.

Note that, if you're using Mail::Audit, the constructor for the Mail::Audit object must use the nomime option, like so:

        my $ma = new Mail::Audit ( nomime => 1 );

SpamAssassin also includes support for reporting spam messages to collaborative filtering databases, such as Vipul's Razor ( http://razor.sourceforge.net/ ).

METHODS

$f = new Mail::SpamAssassin( [ { opt => val, ... } ] ): Constructs a new Mail::SpamAssassin object. You may pass the following attribute-value pairs to the constructor.
$f->trim_rules ($regexp): Remove all rules that don't match the given regexp (or are sub-rules of meta-tests that match the regexp).
$status = $f->check ($mail): Check a mail, encapsulated in a Mail::Audit or Mail::SpamAssassin::Message object, to determine if it is spam or not.; Returns a Mail::SpamAssassin::PerMsgStatus object which can be used to test or manipulate the mail message.; Note that the Mail::SpamAssassin object can be re-used for further messages without affecting this check; in OO terminology, the Mail::SpamAssassin object is a ``factory''. However, if you do this, be sure to call the finish() method on the status objects when you're done with them.
$status = $f->learn ($mail, $id, $isspam, $forget): Learn from a mail, encapsulated in a Mail::Audit or Mail::SpamAssassin::Message object.; If $isspam is set, the mail is assumed to be spam, otherwise it will be learnt as non-spam.; If $forget is set, the attributes of the mail will be removed from both the non-spam and spam learning databases.; $id is an optional message-identification string, used internally to tag the message. If it is undef, the Message-Id of the message will be used. It should be unique to that message.; Returns a Mail::SpamAssassin::PerMsgLearner object which can be used to manipulate the learning process for each mail.; Note that the Mail::SpamAssassin object can be re-used for further messages without affecting this check; in OO terminology, the Mail::SpamAssassin object is a ``factory''. However, if you do this, be sure to call the finish() method on the learner objects when you're done with them.; learn() and check() can be run using the same factory. init_learner() must be called before using this method.
$f->init_learner ( [ { opt => val, ... } ] ): Initialise learning. You may pass the following attribute-value pairs to this method.
$f->rebuild_learner_caches ({ opt => val }): Rebuild any cache databases; should be called after the learning process. Options include: verbose, which will output diagnostics to stdout if set to 1.
$f->finish_learner (): Finish learning.
$f->dump_bayes_db(): Dump the contents of the Bayes DB
$f->signal_user_changed ( [ { opt => val, ... } ] ): Signals that the current user has changed (possibly using setuid), meaning that SpamAssassin should close any per-user databases it has open, and re-open using ones appropriate for the new user.; Note that this should be called after reading any per-user configuration, as that data may override some paths opened in this method. You may pass the following attribute-value pairs:
$status = $f->check_message_text ($mailtext): Check a mail, encapsulated in a plain string, to determine if it is spam or not.; Otherwise identical to $f-check()> above.
$f->report_as_spam ($mail, $options): Report a mail, encapsulated in a Mail::Audit object, as human-verified spam. This will submit the mail message to live, collaborative, spam-blocker databases, allowing other users to block this message.; It will also submit the mail to SpamAssassin's Bayesian learner.; Options is an optional reference to a hash of options. Currently these can be:
$f->revoke_as_spam ($mail, $options): Revoke a mail, encapsulated in a Mail::Audit object, as human-verified ham (non-spam). This will revoke the mail message from live, collaborative, spam-blocker databases, allowing other users to block this message.; It will also submit the mail to SpamAssassin's Bayesian learner as nonspam.; Options is an optional reference to a hash of options. Currently these can be:
$f->add_address_to_whitelist ($addr): Given a string containing an email address, add it to the automatic whitelist database.
$f->add_all_addresses_to_whitelist ($mail): 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.
$f->remove_address_from_whitelist ($addr): Given a string containing an email address, remove it from the automatic whitelist database.
$f->remove_all_addresses_from_whitelist ($mail): 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.
$f->add_address_to_blacklist ($addr): Given a string containing an email address, add it to the automatic whitelist database with a high score, effectively blacklisting them.
$f->add_all_addresses_to_blacklist ($mail): Given a mail message, find addresses in the From headers and add them to the automatic whitelist database with a high score, effectively blacklisting them.; Note that To and Cc addresses are not used.
$f->reply_with_warning ($mail, $replysender): Reply to the sender of a mail, encapsulated in a Mail::Audit object, explaining that their message has been added to spam-tracking databases and deleted. To be used in conjunction with report_as_spam. The $replysender argument should contain an email address to use as the sender of the reply message.
$text = $f->remove_spamassassin_markup ($mail): Returns the text of the message, with any SpamAssassin-added text (such as the report, or X-Spam-Status headers) stripped.; Note that the $mail object is not modified.
$f->read_scoreonly_config ($filename): 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 setuid().
$f->load_scoreonly_sql ($username): Read configuration paramaters from SQL database and parse scores from it. This will only take effect if the perl DBI module is installed, and the configuration parameters user_scores_dsn, user_scores_sql_username, and user_scores_sql_password are set correctly.; The username in $username will also be used for the username attribute of the Mail::SpamAssassin object.
$f->set_persistent_address_list_factory ($factoryobj): Set the persistent address list factory, used to create objects for the automatic whitelist algorithm's persistent-storage back-end. See Mail::SpamAssassin::PersistentAddrList for the API these factory objects must implement, and the API the objects they produce must implement.
$f->compile_now ($use_user_prefs): Compile all patterns, load all configuration files, and load all possibly-required Perl modules.; Normally, Mail::SpamAssassin uses lazy evaluation where possible, but if you plan to fork() or start a new perl interpreter thread to process a message, this is suboptimal, as each process/thread will have to perform these actions.; Call this function in the master thread or process to perform the actions straightaway, so that the sub-processes will not have to.; If $use_user_prefs is 0, this will initialise the SpamAssassin configuration without reading the per-user configuration file and it will assume that you will call read_scoreonly_config at a later point.
$failed = $f->lint_rules (): Syntax-check the current set of rules. Returns the number of syntax errors discovered, or 0 if the configuration is valid.
$f->create_default_prefs ($filename, $username [ , $userdir ] ): Copy default preferences file into home directory for later use and modification, if it does not already exist and dont_copy_prefs is not set.

PREREQUISITES

Mail::Audit Mail::Internet

COREQUISITES

Net::DNS

BUGS

http://bugzilla.spamassassin.org/

AUTHOR

Justin Mason <jm /at/ jmason.org>

COPYRIGHT

SpamAssassin is distributed under Perl's Artistic license.

AVAILABILITY

The latest version of this library is likely to be available from CPAN as well as:

  http://spamassassin.org/