Broken test now check if headers are correctly encoded.
[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    HEADER-NAME can optionnaly be followed by one of the following
104    extension to match a subset of the text in the header:
105
106    - '.raw'     do nothing.
107    - '.name'    extract the name part.
108    - '.address' extract the email address part.
109    - '.user'    extract the username before the @ in email address.
110    - '.domain'  extract the domain name of the email address.
111
112    Example with header 'From: Frederic Jolliton <frederic@jolliton.com>, a@b.c (Foo)':
113
114      'From.name'    -> [ 'Frederic Jolliton' , 'Foo' ]
115      'From.address' -> [ 'frederic@jolliton.com' , 'a@b.c' ]
116      'From.user'    -> [ 'frederic' , 'a' ]
117      'From.domain'  -> [ 'jolliton.com' , 'b.c' ]
118
119  * MATCH-TYPE give the type of match to perform against the header.
120    Each match type take an argument.
121
122    * 'is' test if the header is equal to the argument (case
123       insensitive)
124    * 'contains' test if argument appear in header (case insensitive.)
125    * 'match' test if regular expression defined by argument match
126      the header.
127
128 Match 'broken'
129 --------------
130
131 Syntax: broken ;
132
133 Test if the mail was parsed correctly. Usefull to move such mail apart from the
134 INBOX, since most of the time they are spams or viruses.
135
136 Match 'infected'
137 ----------------
138
139 Syntax: infected ;
140
141 Test with clamav if the mail contains a virus.
142
143 Match 'spam'
144 ------------
145
146 Syntax: spam ;
147
148 Test with spamprobe if the mail *could* be a spam.
149
150 Note that spamprobe need to be "enseigner"(fr->en?).
151
152 Match 'and', 'or' and 'not'
153 ---------------------------
154
155 These matches allow you to build logical conditions.
156
157 Syntax: and { ... }
158 Syntax: or { ... }
159 Syntax: not { ... }
160
161 For 'and', everything inside it must match.
162 For 'or', only one match is required.
163 For 'not', everything inside must don't match.
164
165
166 Detailed example
167 ----------------
168
169 folder 'Store.Amazon' {
170         header 'to' is 'some@email.address.com' ;
171         and {
172                 or {
173                         header 'from' is 'confirmation-commande@amazon.fr' ;
174                         header 'from' is 'confirmation-envoi@amazon.fr' ;
175                         header 'from' is 'modification-commande@amazon.fr' ;
176                 }
177                 header 'to' is 'another@email.address.com' ;
178         }
179 }
180
181 Here we fill mail to 'Store.Amazon' IMAP folder for the user specified on
182 command line (which sendmail automatically set when calling the script)
183 when mail match the following:
184
185 Either:
186
187  - The mail is destined to 'some@email.address.com',
188  - OR The mail is both:
189    - destined to 'another@email.address.com'
190    - AND from one of the three emails address listed.
191