git.intra.tuxee.net Git - confparser-old/blob - 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