Added a README and CREATING-RULES file
[confparser-old] / CREATING-RULES
1 Defining rules
2 --------------
3
4 There is one file per user.  (If there is no rules file for an user, mail are
5 just delivered to its default folder 'INBOX'.)
6
7 You can check configuration file from command line by using mail.filter '-c'
8 option.  mail.filter will report any syntax error found in the file given as
9 argument.  It's HIGHLY recommended to test change with this method prior to
10 "commiting" change to user's configuration.
11
12 Syntax
13 ------
14
15 The syntax is very simple.
16
17 expr = keyword string* { expr* }
18      | keyword string* ;
19
20 In english, that mean that an expression is a keyword followed by optionally
21 one or more "string", then followed by end of expression character ';', or
22 followed by nested expression enclosed by {}.
23
24 Examples:
25
26 folder 'Spam' { spam ; }
27
28 Action
29 ------
30
31 The file contains a set of actions. Each action contains a match description.
32
33 Some examples of action:
34
35 folder 'Friend.Joe' {
36         header 'from' contains '<some@email.address.com>' ;
37         header 'from' match '@joedomain\.(com|net|org)>' ;
38         header 'subject' contains '[joe]' ;
39 }
40
41 folder 'Store.Amazon' {
42         header 'to' is 'some@email.address.com' ;
43         and {
44                 or {
45                         header 'from' is 'confirmation-commande@amazon.fr' ;
46                         header 'from' is 'confirmation-envoi@amazon.fr' ;
47                         header 'from' is 'modification-commande@amazon.fr' ;
48                 }
49                 header 'to' is 'another@email.address.com' ;
50         }
51 }
52
53 reject NOUSER {
54         header 'from' contains '<some@email.address>' ;
55 }
56
57
58 In the current mail.filter, there is two possible action.
59
60 Either 'folder' or 'reject'.
61
62
63 Action 'folder'
64 ---------------
65
66 Syntax: folder <folder-name> { matches.. }
67
68 The 'folder' action instruct mail.filter to file the mail into a particular
69 folder. So, folder take one argument that give the folder name.
70
71
72 Action 'reject'
73 ---------------
74
75 Syntax: reject <error-code> { matches.. }
76
77 The 'reject' action instruct mail.filter to not file the mail, and instead
78 return an error code to sendmail.
79
80 Supported textual error code are: nouser, tempfail and dataerr.
81
82 But, reject can also take a numeral error code.
83
84
85 Matches
86 -------
87
88 For matches listed in action, only one need to match for the action to be
89 taken (logical 'or' by default.)
90
91 The following matches are supported:
92
93 Match 'header'
94 --------------
95
96 Syntax: header <HEADER-NAME> <MATCH-TYPE> <MATCH-ARGUMENT> ;
97
98 where:
99
100  * HEADER-NAME name a header, where all blanks character sequence are
101    considered as just one space character.
102
103  * MATCH-TYPE give the type of match to perform against the header.
104    Each match type take an argument.
105
106    * 'is' test if the header is equal to the argument (case
107       insensitive)
108    * 'contains' test if argument appear in header (case insensitive.)
109    * 'match' test if regular expression defined by argument match
110      the header.
111
112 Match 'broken'
113 --------------
114
115 Syntax: broken ;
116
117 Test if the mail was parsed correctly. Usefull to move such mail apart from the
118 INBOX, since most of the time they are spams or viruses.
119
120 Match 'infected'
121 ----------------
122
123 Syntax: infected ;
124
125 Test with clamav if the mail contains a virus.
126
127 Match 'spam'
128 ------------
129
130 Syntax: spam ;
131
132 Test with spamprobe if the mail *could* be a spam.
133
134 Note that spamprobe need to be "enseigner"(fr->en?).
135
136 Match 'and', 'or' and 'not'
137 ---------------------------
138
139 These matches allow you to build logical conditions.
140
141 Syntax: and { ... }
142 Syntax: or { ... }
143 Syntax: not { ... }
144
145 For 'and', everything inside it must match.
146 For 'or', only one match is required.
147 For 'not', everything inside must don't match.
148
149
150 Detailed example
151 ----------------
152
153 folder 'Store.Amazon' {
154         header 'to' is 'some@email.address.com' ;
155         and {
156                 or {
157                         header 'from' is 'confirmation-commande@amazon.fr' ;
158                         header 'from' is 'confirmation-envoi@amazon.fr' ;
159                         header 'from' is 'modification-commande@amazon.fr' ;
160                 }
161                 header 'to' is 'another@email.address.com' ;
162         }
163 }
164
165 Here we fill mail to 'Store.Amazon' IMAP folder for the user specified on
166 command line (which sendmail automatically set when calling the script)
167 when mail match the following:
168
169 Either:
170
171  - The mail is destined to 'some@email.address.com',
172  - OR The mail is both:
173    - destined to 'another@email.address.com'
174    - AND from one of the three emails address listed.
175