5 {pmg} ships with a highly configurable mail filter. This provides an
6 easy but powerful way to define filter rules by user, domain, time
7 frame, content type, and resulting action.
9 [thumbnail="pmg-gui-mail-filter-rules.png", big=1]
11 Every rule has 5 categories ('FROM', 'TO', 'WHEN', 'WHAT', and
12 'ACTION'), and each category may contain several objects to match
17 Who is the sender or recipient of the email? Those objects can be used
18 for the 'TO' and/or 'FROM' category.
21 Example: EMail-object - Who is the sender or recipient of the email?
29 Example: Does the email contain spam?
34 When is the email received by {pmg}?
37 Example: Office Hours - Mail is received between 8:00 and 16:00.
42 Defines the final actions.
45 Example: Mark email with “SPAM:” in the subject.
48 Rules are ordered by priority, so rules with higher priority are
49 executed first. It is also possible to set a processing direction:
51 'In':: Rule applies to all incoming emails
53 'Out':: Rule applies to all outgoing emails
55 'In & Out':: Rule applies to both directions
57 You can also disable a rule completely, which is mostly useful for
58 testing and debugging. The 'Factory Defaults' button allows you to
59 reset the filter rules.
64 When there is more than one object category or multiple objects configured
65 within a single rule, the following logic is used to determine if the rule
66 should be applied by default:
68 * Within one category (WHAT/FROM/TO/WHEN), all objects are logical-or linked,
69 meaning that only one object of any one object group from the same category
70 has to match for the whole category to match.
72 * FROM/TO/WHAT/WHEN category match results are logical-and linked, so all
73 categories that have at least one object in them must match for the rule to
76 When these conditions are met, all configured actions are executed.
78 Alternatively, one can configure the 'mode' to 'any' (the default) or 'all' and
79 set 'invert' (default off) per object group and per object category for each
82 When the mode is 'all' for a group, all objects within must match for the
83 object group to count as a match. This can be helpful when one wants to match
84 multiple conditions at the same time (e.g. file content-type and filename).
86 When 'all' is set for a category of a rule, all object groups for that
87 type must match for the type to match.
89 When 'invert' is active on a group, the original result of the group will
90 simply be inverted, so a match becomes a non-match and vice versa.
92 The same is true for the object group types for rules.
94 Special handling is done for WHAT matches that mark mail parts (e.g. filename)
95 since that is not a simple yes/no match for the complete mail, but could be a
96 match for each part of the e-mail (e.g. attachments, or parts of a multi-part
99 So for WHAT match object groups, the 'mode' and 'invert' is applied to
100 the single parts of the e-mail, not the message as a whole.
102 This means one has to be very careful with the 'invert' option, as previously
103 not matching parts, will match when using 'invert' (e.g. an inverted filename
104 matching will also mark non attachment parts of the mail).
106 On the rule level, these marks of the parts will always be logical-or linked,
107 this way even more scenarios can be represented.
109 To make it a bit easier to understand, the options are combined to a single
110 selection in the web ui:
112 * Any must match => mode: 'any', invert: 'off'
113 * All must match => mode: 'all', invert: 'off'
114 * At least one must not match => mode: 'all', invert: 'on'
115 * None must match => mode: 'any', invert: 'on'
117 [[pmg_mailfilter_action]]
121 [thumbnail="pmg-gui-mail-filter-actions.png", big=1]
123 Please note that some actions stop further rule processing. We call
124 such actions 'final'.
129 Accept mail for Delivery. This is a 'final' action.
135 Block mail. This is a 'final' action.
141 Move to quarantine (virus mails are moved to the “virus quarantine”;
142 other mails are moved to “spam quarantine”). This is also a 'final' action.
148 Send notifications. Please note that object configuration can use
149 xref:rule_system_macros[macros], so it is easy to include additional
150 information. For example, the default 'Notify Admin' object sends the
151 following information:
153 .Sample notification action body:
155 Proxmox Notification:
157 Receiver: __RECEIVERS__
160 Matching Rule: __RULE__
168 Notification can also include a copy of the original mail.
171 Blind Carbon Copy (BCC)
172 ~~~~~~~~~~~~~~~~~~~~~~~
174 The BCC object simply sends a copy to another target. It is possible to
175 send the original unmodified mail, or the processed result. Please
176 note that this can be quite different, for instance, when a previous rule
183 This object is able to add or modify mail header attributes. As with
184 Notifications above, you can use xref:rule_system_macros[macros],
185 making this a very powerful object. For example, the 'Modify Spam
186 Level' actions add detailed information about detected Spam
187 characteristics to the `X-SPAM-LEVEL` header.
189 .'Modify Spam Level' Header Attribute
195 Another prominent example is the 'Modify Spam Subject' action. This
196 simply adds the 'SPAM:' prefix to the original mail subject:
198 .'Modify Spam Subject' Header Attribute
201 Value: SPAM: __SUBJECT__
208 Remove attachments can either remove all attachments, or only those
209 matched by the rule's 'What' - object. You can also specify the
210 replacement text, if you want.
212 You can optionally move these mails into the attachment quarantine, where
213 the original mail with all attachments will be stored. The mail with the
214 attachments removed will continue through the rule system.
216 NOTE: The Attachment Quarantine lifetime is the same as for the Spam Quarantine.
224 The disclaimer can contain HTML markup. It will be added to the first
225 `text/html` and `text/plain` part of an email. A disclaimer only gets added if
226 its text can be encoded in the mail's character encoding.
229 [[pmg_mailfilter_who]]
233 [thumbnail="pmg-gui-mail-filter-who-objects.png", big=1]
235 These types of objects can be used for the 'TO' and/or 'FROM' category,
236 and match the sender or recipient of the email. A single object can
237 combine multiple items, and the following item types are available:
241 Allows you to match a single mail address.
245 Only match the domain part of the mail address.
249 This one uses a regular expression to match the whole mail address.
251 IP Address or Network::
253 This can be used to match the senders IP address.
257 Test if the mail address belongs to a specific LDAP user or group.
259 We have two important 'Who' objects called 'Blacklist' and
260 'Whitelist'. These are used in the default ruleset to globally block
261 or allow specific senders.
264 [[pmg_mailfilter_what]]
268 [thumbnail="pmg-gui-mail-filter-what-objects.png", big=1]
270 'What' objects are used to classify the mail's content. A single
271 object can combine multiple items, and the following item types are
276 Matches if the detected spam level is greater than or equal to the
281 Matches on infected mails.
285 Match specified mail header fields (for example, `Subject:`, `From:`, ...)
287 Content Type Filter::
289 Can be used to match specific content types.
293 Uses regular expressions to match attachment filenames.
297 Can be used to match specific content types inside archives.
298 This also matches the content-types of all regular (non-archived) attachments.
300 Match Archive Filename::
302 Uses regular expressions to match attachment filenames inside archives.
303 This also matches the filenames for all regular (non-archived) attachments.
306 [[pmg_mailfilter_when]]
310 [thumbnail="pmg-gui-mail-filter-when-objects.png", big=1]
312 'When' objects are used to activate rules at specific times of the
313 day. You can compose them from one or more time frame items.
315 The default ruleset defines 'Office Hours', but this is not used by
319 [[pmg_mailfilter_regex]]
320 Using regular expressions
321 -------------------------
323 A regular expression is a string of characters which represents a list
324 of text patterns which you would like to match. The following is a
325 short introduction to the syntax of regular expressions used by some
326 objects. If you are familiar with Perl, you will already know the
329 Simple regular expressions
330 ~~~~~~~~~~~~~~~~~~~~~~~~~~
332 In its simplest form, a regular expression is just a word or phrase to
333 search for. `Mail` would match the string "Mail". The search is case
334 sensitive so "MAIL", "Mail", "mail" would not be matched.
339 Some characters have a special meaning. These characters are called
340 metacharacters. The Period (`.`) is a commonly used metacharacter. It
341 matches exactly one character, regardless of what the character is.
342 `e.mail` would match either "e-mail" or "e2mail" but not
343 "e-some-mail" or "email".
345 The question mark (`?`) indicates that the character immediately
346 preceding it shows up either zero or one time. `e?mail` would match
347 either "email" or "mail" but not "e-mail".
349 Another metacharacter is the asterisk (`*`). This indicates that the
350 character immediately preceding it may be repeated any number of times,
351 including zero. `e*mail` would match "email", "mail", and
354 The plus (`+`) metacharacter indicates that the character immediately
355 preceding it appears one or more times. So `e+mail` does not match
358 Metacharacters can also be combined. A common combination includes the
359 period and asterisk metacharacters (`.*`), with the asterisk
360 immediately following the period. This is used to match an arbitrary
361 string of any length, including the null string. For example:
362 `.*company.*` matches "company@domain.com" or "company@domain.co.uk"
363 or "department.company@domain.com".
365 The book xref:Friedl97[] provides a more comprehensive introduction.