mail.filter is a program called by sendmail, that forward mails to some cyrus
account.

Optionally, mail.filter use spamprobe for spam detection, and clamav for virus
detection. (Well, it's not really optional actually.)

For defining rules, see CREATING-RULES file.

Configuring the script
----------------------

mail.filter contains several variable definition that you should review and
edit.

Testing
-------

1] Check that Python is able to run the script by running:

    mail.filter -h

2] Try mail.filter without feeding the mail to Cyrus by running:

    mail.filter -t -v < somemail

   with somemail a file containing a email you want to feed to mail.filter for
   testing purpose. Output log should show you what action is deduced from mail
   contents and user rules.

3] You can test again by removing the '-t' option to actually feed Cyrus with
   the mail, and test if Cyrus accept the mail as expected in the right folder.

4] Check that sendmail can run the script (permission, sendmail restriction,..)

Installation
------------

Add the following TWO lines:

-=-=-=-=
Mmailfilter, P=/usr/sbin/mail.filter, F=lsDFMA5:/|@qSPn, A=mail.filter $u
define(`confLOCAL_MAILER', `mailfilter')dnl
-=-=-=-=

in your sendmail.mc, then regenerate sendmail.cf (be carefull if sendmail.cf
was not in sync. with your sendmail.mc ! I suggest to generate 'm4 sendmail.cf'
to a different file, and use diff to see what really change.)

The first line define a new mailer. The second line define it as default mailer
for delivering mail to local system.

Then, you just need to restart sendmail.

Todo
----

[ ] Make spam and antivirus detection more modular, to support other antispam
    or antiviruses program.
[ ] Try to create folder if Cyrus answer with unknown folder error, then
    feed again the mail.
[ ] Add size match (really usefull?)
[ ] Support feature such as vacation, automatic answer, forwarding, calling
    external script (or even "just" python module.)
[ ] For mail rejected by Cyrus because of invalid header, encapsulate the
    mail into a new one, and feed this one to Cyrus (and tagged as broken.)
[ ] Allow mail.filter to re-file mails already present in a Cyrus folder.