5 {pmg} ships with a highly configurable mail filter. It’s an easy but
6 powerful way to define filter rules by user, domains, time frame,
7 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 for all incoming emails
53 'Out':: Rule applies for all outgoing emails
55 'In & Out':: Rule applies for both directions
57 And you can also disable a rule completely, which is mostly useful for
58 testing and debugging. The 'Factory Defaults' button alows 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, i.e. when a previous rule
128 This object is able to add or modify mail header attributes. As with notifications above, you can use xref:rule_system_macros[macros], making this a very powerful object. For example, the 'Modify Spam Level' actions adds detailed information about detected Spam characteristics to the `X-SPAM-LEVEL` header.
130 .'Modify Spam Level' Header Attribute
136 Another prominent example is the 'Modify Spam Subject' action. This
137 simply adds the 'SPAM:' prefix to the original mail subject:
139 .'Modify Spam Subject' Header Attribute
142 Value: SPAM: __SUBJECT__
149 Remove attachments can either remove all attachments, or only those
150 matched by the rules 'What' - object. You can also specify the
151 replacement text if you want.
153 You can optionally move those mails into the attachment quarantine, where
154 the original mail with all attachments will be stored. The mail with the
155 attachments removed will continue in the rule system.
157 NOTE: The Attachment Quarantine Lifetime is the same as for the Spam Quarantine.
165 The disclaimer can contain HTML markup. It will be added to the first
166 `text/html` and `text/plain` part of an email. A disclaimer only gets added if
167 its text can be encoded in the mail's character encoding.
170 [[pmg_mailfilter_who]]
174 [thumbnail="pmg-gui-mail-filter-who-objects.png", big=1]
176 This type of objects can be used for the 'TO' and/or 'FROM' category,
177 and match the sender or recipient of the email. A single object can
178 combine multiple items, and the following item types are available:
182 Allows you to match a single mail address.
186 Only match the domain part of the mail address.
190 This one uses a regular expression to match the whole mail address.
192 IP Address or Network::
194 This can be used to match the senders IP address.
198 Test if the mail address belongs to a specific LDAP user or group.
200 We have two important 'Who' - objects called 'Blacklist' and
201 'Whitelist'. These are used in the default ruleset to globally block
202 or allow specific senders.
205 [[pmg_mailfilter_what]]
209 [thumbnail="pmg-gui-mail-filter-what-objects.png", big=1]
211 'What' - objects are used to classify the mail content. A single
212 object can combine multiple items, and the following item types are
217 Matches if detected spam level is equal or greater than the configured value.
221 Matches on infected mails.
225 Match specified mail header fields (eg. `Subject:`, `From:`, ...)
227 Content Type Filter::
229 Can be used to match specific content types.
233 Uses regular expressions to match attachment filenames.
237 Can be used to match specific content types inside archives.
238 This also matches the content-types of all regular (non-archived) attachments.
240 Match Archive Filename::
242 Uses regular expressions to match attachment filenames inside archives.
243 This also matches the filenames for all regular (non-archived) attachments.
246 [[pmg_mailfilter_when]]
250 [thumbnail="pmg-gui-mail-filter-when-objects.png", big=1]
252 'When' - objects are use to activate rules at specific daytimes. You
253 can compose them of one or more time frame items.
255 The default ruleset defines 'Office Hours', but this is not used by
259 [[pmg_mailfilter_regex]]
260 Using regular expressions
261 -------------------------
263 A regular expression is a string of characters which tells us which
264 string you are looking for. The following is a short introduction in
265 the syntax of regular expressions used by some objects. If you are
266 familiar with Perl, you already know the syntax.
268 Simple regular expressions
269 ~~~~~~~~~~~~~~~~~~~~~~~~~~
271 In its simplest form, a regular expression is just a word or phrase to
272 search for. `Mail` would match the string "Mail". The search is case
273 sensitive so "MAIL", "Mail", "mail" would not be matched.
278 Some characters have a special meaning. These characters are called
279 metacharacters. The Period (`.`) is a commonly used metacharacter. It
280 matches exactly one character, regardless of what the character is.
281 `e.mail` would match either "e-mail" or "e2mail" but not
282 "e-some-mail" or "email".
284 The question mark (`?`) indicates that the character immediately
285 preceding it shows up either zero or one time. `e?mail` would match
286 either "email" or "mail" but not "e-mail".
288 Another metacharacter is the star (`*`). This indicates that the
289 character immediately preceding it may be repeated any number of times,
290 including zero. `e*mail` would match either "email" or "mail" or
293 The plus (`+`) metacharacter does the same as the star (*) excluding
294 zero. So `e+mail` does not match "mail".
296 Metacharacters may be combined. A common combination includes the
297 period and star metacharacters (`.*`), with the star immediately following
298 the period. This is used to match an arbitrary string of any length,
299 including the null string. For example: `.*company.*` matches
300 "company@domain.com" or "company@domain.co.uk" or
301 "department.company@domain.com".
303 The book xref:Friedl97[] provides a more comprehensive introduction.