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.
62 [[pmg_mailfilter_action]]
66 [thumbnail="pmg-gui-mail-filter-actions.png", big=1]
68 Please note that some actions stop further rule processing. We call
74 Accept mail for Delivery. This is a 'final' action.
80 Block mail. This is a 'final' action.
86 Move to quarantine (virus mails are moved to the “virus quarantine”;
87 other mails are moved to “spam quarantine”). This is also a 'final' action.
93 Send notifications. Please note that object configuration can use
94 xref:rule_system_macros[macros], so it is easy to include additional
95 information. For example, the default 'Notify Admin' object sends the
96 following information:
98 .Sample notification action body:
100 Proxmox Notification:
102 Receiver: __RECEIVERS__
105 Matching Rule: __RULE__
113 Notification can also include a copy of the original mail.
116 Blind Carbon Copy (BCC)
117 ~~~~~~~~~~~~~~~~~~~~~~~
119 The BCC object simply sends a copy to another target. It is possible to
120 send the original unmodified mail, or the processed result. Please
121 note that this can be quite different, for instance, when a previous rule
128 This object is able to add or modify mail header attributes. As with
129 Notifications above, you can use xref:rule_system_macros[macros],
130 making this a very powerful object. For example, the 'Modify Spam
131 Level' actions add detailed information about detected Spam
132 characteristics to the `X-SPAM-LEVEL` header.
134 .'Modify Spam Level' Header Attribute
140 Another prominent example is the 'Modify Spam Subject' action. This
141 simply adds the 'SPAM:' prefix to the original mail subject:
143 .'Modify Spam Subject' Header Attribute
146 Value: SPAM: __SUBJECT__
153 Remove attachments can either remove all attachments, or only those
154 matched by the rule's 'What' - object. You can also specify the
155 replacement text, if you want.
157 You can optionally move these mails into the attachment quarantine, where
158 the original mail with all attachments will be stored. The mail with the
159 attachments removed will continue through the rule system.
161 NOTE: The Attachment Quarantine lifetime is the same as for the Spam Quarantine.
169 The disclaimer can contain HTML markup. It will be added to the first
170 `text/html` and `text/plain` part of an email. A disclaimer only gets added if
171 its text can be encoded in the mail's character encoding.
174 [[pmg_mailfilter_who]]
178 [thumbnail="pmg-gui-mail-filter-who-objects.png", big=1]
180 These types of objects can be used for the 'TO' and/or 'FROM' category,
181 and match the sender or recipient of the email. A single object can
182 combine multiple items, and the following item types are available:
186 Allows you to match a single mail address.
190 Only match the domain part of the mail address.
194 This one uses a regular expression to match the whole mail address.
196 IP Address or Network::
198 This can be used to match the senders IP address.
202 Test if the mail address belongs to a specific LDAP user or group.
204 We have two important 'Who' objects called 'Blacklist' and
205 'Whitelist'. These are used in the default ruleset to globally block
206 or allow specific senders.
209 [[pmg_mailfilter_what]]
213 [thumbnail="pmg-gui-mail-filter-what-objects.png", big=1]
215 'What' objects are used to classify the mail's content. A single
216 object can combine multiple items, and the following item types are
221 Matches if the detected spam level is greater than or equal to the
226 Matches on infected mails.
230 Match specified mail header fields (for example, `Subject:`, `From:`, ...)
232 Content Type Filter::
234 Can be used to match specific content types.
238 Uses regular expressions to match attachment filenames.
242 Can be used to match specific content types inside archives.
243 This also matches the content-types of all regular (non-archived) attachments.
245 Match Archive Filename::
247 Uses regular expressions to match attachment filenames inside archives.
248 This also matches the filenames for all regular (non-archived) attachments.
251 [[pmg_mailfilter_when]]
255 [thumbnail="pmg-gui-mail-filter-when-objects.png", big=1]
257 'When' objects are used to activate rules at specific times of the
258 day. You can compose them from one or more time frame items.
260 The default ruleset defines 'Office Hours', but this is not used by
264 [[pmg_mailfilter_regex]]
265 Using regular expressions
266 -------------------------
268 A regular expression is a string of characters which represents a list
269 of text patterns which you would like to match. The following is a
270 short introduction to the syntax of regular expressions used by some
271 objects. If you are familiar with Perl, you will already know the
274 Simple regular expressions
275 ~~~~~~~~~~~~~~~~~~~~~~~~~~
277 In its simplest form, a regular expression is just a word or phrase to
278 search for. `Mail` would match the string "Mail". The search is case
279 sensitive so "MAIL", "Mail", "mail" would not be matched.
284 Some characters have a special meaning. These characters are called
285 metacharacters. The Period (`.`) is a commonly used metacharacter. It
286 matches exactly one character, regardless of what the character is.
287 `e.mail` would match either "e-mail" or "e2mail" but not
288 "e-some-mail" or "email".
290 The question mark (`?`) indicates that the character immediately
291 preceding it shows up either zero or one time. `e?mail` would match
292 either "email" or "mail" but not "e-mail".
294 Another metacharacter is the asterisk (`*`). This indicates that the
295 character immediately preceding it may be repeated any number of times,
296 including zero. `e*mail` would match "email", "mail", and
299 The plus (`+`) metacharacter indicates that the character immediately
300 preceding it appears one or more times. So `e+mail` does not match
303 Metacharacters can also be combined. A common combination includes the
304 period and asterisk metacharacters (`.*`), with the asterisk
305 immediately following the period. This is used to match an arbitrary
306 string of any length, including the null string. For example:
307 `.*company.*` matches "company@domain.com" or "company@domain.co.uk"
308 or "department.company@domain.com".
310 The book xref:Friedl97[] provides a more comprehensive introduction.