
=head1 NAME

Mail::Box::Search::SpamAssassin - select spam messages with Mail::SpamAssassin

=head1 CLASS INHERITANCE

 Mail::Box::Search::SpamAssassin
   is a Mail::Box::Search
   is a Mail::Reporter

=head1 SYNOPSIS

 use Mail::Box::Manager;
 my $mgr    = Mail::Box::Manager->new;
 my $folder = $mgr->open('Inbox');

 my $spam = Mail::Box::Search::SpamAssassin->new;
 if($spam->search($message)) {...}

 my @msgs   = $filter->search($folder);
 foreach my $msg ($folder->messages)
 {   $msg->delete if $msg->label('spam');
 }

 my $spam2 = Mail::Box::Search::SpamAssassin->new(deliver => 'DELETE');
 $spam2->search($folder);
 $mgr->moveMessages($folder->messages('spam'), $spamfolder);

=head1 DESCRIPTION

I<Spam> means "unsollicited e-mail", and is as name derived from a
Monty Python scatch.  Although Monty Python is fun, spam is a pain:
it needlessly spoils minutes of time from most people: telephone
bills, overful mailboxes which block honest e-mail, and accidentally
removal of honest e-mail which looks like spam.  Spam is the pest
of Internet.

Happily, Mail::Box can be used as spam filter, in combination with
the useful Mail::SpamAssassin module (which must be installed separately).
Each message which is searched is wrapped in a
Mail::Message::Wrapper::SpamAssassin object.

The spam-assassin module version 2 is not really well adapted for
Mail::Message objects, which will make this search even slower than
spam-detection already is.

=head1 METHODS

=head2 Initiation

=over 4

=item B<assassinator> 

Returns the internally maintained assassinator object.  You may want
to reach this object for complex configuration.

=item B<new> OPTIONS

(Class method) 
Create a spam filter.  Internally, a Mail::SpamAssassin object is
maintained.


Only the whole message can be searched; this is a limitation of
the Mail::SpamAssassin module.

 OPTION               DEFAULT
 binaries             <false>
 decode               <true>
 delayed              <true>
 deleted              <false>
 deliver              undef
 in                   'MESSAGE'
 label                'spam'
 limit                0
 log                  'WARNINGS'
 logical              'REPLACE'
 multiparts           <true>
 rewrite_mail         <true>
 sa_options           {}
 spam_assassin        undef
 trace                'WARNINGS'

=over 4

=item B<binaries> =E<gt> BOOLEAN

See Mail::Box::Search::new(binaries)

=item B<decode> =E<gt> BOOLEAN

See Mail::Box::Search::new(decode)

=item B<delayed> =E<gt> BOOLEAN

See Mail::Box::Search::new(delayed)

=item B<deleted> =E<gt> BOOLEAN

See Mail::Box::Search::new(deleted)

=item B<deliver> =E<gt> undef|CODE|'DELETE'

See Mail::Box::Search::new(deliver)

=item B<in> =E<gt> 'HEAD'|'BODY'|'MESSAGE'

See Mail::Box::Search::new(in)

=item B<label> =E<gt> STRING|undef

Mark all selected selected message with the specified STRING.  If this
option is explicitly set to C<undef>, the label will not be set.

=item B<limit> =E<gt> NUMBER

See Mail::Box::Search::new(limit)

=item B<log> =E<gt> LEVEL

See Mail::Reporter::new(log)

=item B<logical> =E<gt> 'REPLACE'|'AND'|'OR'|'NOT'|'AND NOT'|'OR NOT'

See Mail::Box::Search::new(logical)

=item B<multiparts> =E<gt> BOOLEAN

See Mail::Box::Search::new(multiparts)

=item B<rewrite_mail> =E<gt> BOOLEAN

Add lines to the message header describing the results of the spam
scan. See Mail::SpamAssassin::PerMessageStatus::rewrite_mail().

=item B<sa_options> =E<gt> HASH_REF

Options to create the internal Mail::SpamAssassin object; see its
manual page for the available options.

=item B<spam_assassin> =E<gt> OBJECT

Provide a Mail::SpamAssassin object to be used for searching spam.  If
none is specified, one is created internally.  The object can be
retreived with assassinator().

=item B<trace> =E<gt> LEVEL

See Mail::Reporter::new(trace)

=back

Examples:

 my $filter = Mail::Box::Search::SpamAssassin->new
  ( in    => 'HEAD'
  , found => 'DELETE'
  );

=back

=head2 Searching

=over 4

=item B<inBody> PART, BODY

See Mail::Box::Search::inBody()

=item B<inHead> PART, HEAD

See Mail::Box::Search::inHead()

=item B<search> FOLDER|THREAD|MESSAGE|ARRAY-OF-MESSAGES

See Mail::Box::Search::search()

=item B<searchPart> PART

See Mail::Box::Search::searchPart()

=back

=head2 The Results

=over 4

=item B<printMatch> [FILEHANDLE], HASH

See Mail::Box::Search::printMatch()

=back

=head2 Logging and Tracing

=over 4

=item B<defaultTrace> [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

=item B<errors> 

See Mail::Reporter::errors()

=item B<log> [LEVEL [,STRINGS]]

See Mail::Reporter::log()

=item B<report> [LEVEL]

See Mail::Reporter::report()

=item B<reportAll> [LEVEL]

See Mail::Reporter::reportAll()

=item B<trace> [LEVEL]

See Mail::Reporter::trace()

=item B<warnings> 

See Mail::Reporter::warnings()

=back

=head2 Other Methods

=over 4

=item B<AUTOLOAD> 

See Mail::Reporter::AUTOLOAD()

=item B<DESTROY> 

See Mail::Reporter::DESTROY()

=item B<inGlobalDestruction> 

See Mail::Reporter::inGlobalDestruction()

=item B<logPriority> LEVEL

See Mail::Reporter::logPriority()

=item B<logSettings> 

See Mail::Reporter::logSettings()

=item B<notImplemented> 

See Mail::Reporter::notImplemented()

=back

=head1 SEE ALSO

A good start to read is Mail::Box-Overview.
More documentation and a mailinglist are available from the project's
website at L<http://perl.overmeer.net/mailbox/>.

=head1 AUTHOR

Written by Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>)
with the help of many.  See the ChangeLog for details.

=head1 VERSION

This code is beta, version 2.037.

Copyright (c) 2001-2003 by the authors. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
