Defining rules
--------------

There is one file per user.  (If there is no rules file for an user, mail are
just delivered to its default folder 'INBOX'.)

You can check configuration file from command line by using mail.filter '-c'
option.  mail.filter will report any syntax error found in the file given as
argument.  It's HIGHLY recommended to test change with this method prior to
"commiting" change to user's configuration.

Syntax
------

The syntax is very simple.

expr = keyword string* { expr* }
     | keyword string* ;

In english, that mean that an expression is a keyword followed by optionally
one or more "string", then followed by end of expression character ';', or
followed by nested expression enclosed by {}.

Examples:

folder 'Spam' { spam ; }

Action
------

The file contains a set of actions. Each action contains a match description.

Some examples of action:

folder 'Friend.Joe' {
        header 'from' contains '<some@email.address.com>' ;
        header 'from' match '@joedomain\.(com|net|org)>' ;
        header 'subject' contains '[joe]' ;
}

folder 'Store.Amazon' {
        header 'to' is 'some@email.address.com' ;
        and {
                or {
                        header 'from' is 'confirmation-commande@amazon.fr' ;
                        header 'from' is 'confirmation-envoi@amazon.fr' ;
                        header 'from' is 'modification-commande@amazon.fr' ;
                }
                header 'to' is 'another@email.address.com' ;
        }
}

reject NOUSER {
        header 'from' contains '<some@email.address>' ;
}


In the current mail.filter, there is two possible action.

Either 'folder' or 'reject'.


Action 'folder'
---------------

Syntax: folder <folder-name> { matches.. }

The 'folder' action instruct mail.filter to file the mail into a particular
folder. So, folder take one argument that give the folder name.


Action 'reject'
---------------

Syntax: reject <error-code> { matches.. }

The 'reject' action instruct mail.filter to not file the mail, and instead
return an error code to sendmail.

Supported textual error code are: nouser, tempfail and dataerr.

But, reject can also take a numeral error code.


Matches
-------

For matches listed in action, only one need to match for the action to be
taken (logical 'or' by default.)

The following matches are supported:

Match 'header'
--------------

Syntax: header <HEADER-NAME> <MATCH-TYPE> <MATCH-ARGUMENT> ;

where:

 * HEADER-NAME name a header, where all blanks character sequence are
   considered as just one space character.

   HEADER-NAME can optionnaly be followed by one of the following
   extension to match a subset of the text in the header:

   - '.raw'     do nothing.
   - '.name'    extract the name part.
   - '.address' extract the email address part.
   - '.user'    extract the username before the @ in email address.
   - '.domain'  extract the domain name of the email address.

   Example with header 'From: Frederic Jolliton <frederic@jolliton.com>, a@b.c (Foo)':

     'From.name'    -> [ 'Frederic Jolliton' , 'Foo' ]
     'From.address' -> [ 'frederic@jolliton.com' , 'a@b.c' ]
     'From.user'    -> [ 'frederic' , 'a' ]
     'From.domain'  -> [ 'jolliton.com' , 'b.c' ]

 * MATCH-TYPE give the type of match to perform against the header.
   Each match type take an argument.

   * 'is' test if the header is equal to the argument (case
      insensitive)
   * 'contains' test if argument appear in header (case insensitive.)
   * 'match' test if regular expression defined by argument match
     the header.

Match 'broken'
--------------

Syntax: broken ;

Test if the mail was parsed correctly. Usefull to move such mail apart from the
INBOX, since most of the time they are spams or viruses.

Match 'infected'
----------------

Syntax: infected ;

Test with clamav if the mail contains a virus.

Match 'spam'
------------

Syntax: spam ;

Test with spamprobe if the mail *could* be a spam.

Note that spamprobe need to be "enseigner"(fr->en?).

Match 'and', 'or' and 'not'
---------------------------

These matches allow you to build logical conditions.

Syntax: and { ... }
Syntax: or { ... }
Syntax: not { ... }

For 'and', everything inside it must match.
For 'or', only one match is required.
For 'not', everything inside must don't match.


Detailed example
----------------

folder 'Store.Amazon' {
        header 'to' is 'some@email.address.com' ;
        and {
                or {
                        header 'from' is 'confirmation-commande@amazon.fr' ;
                        header 'from' is 'confirmation-envoi@amazon.fr' ;
                        header 'from' is 'modification-commande@amazon.fr' ;
                }
                header 'to' is 'another@email.address.com' ;
        }
}

Here we fill mail to 'Store.Amazon' IMAP folder for the user specified on
command line (which sendmail automatically set when calling the script)
when mail match the following:

Either:

 - The mail is destined to 'some@email.address.com',
 - OR The mail is both:
   - destined to 'another@email.address.com'
   - AND from one of the three emails address listed.