-Mail Filter
-===========
+[[chapter_mailfilter]]
+Rule-Based Mail Filter
+======================
-{pmg} ships with a highly configurable mail filter. It’s an easy but
-powerful way to define filter rules by user, domains, time frame,
-content type and resulting action.
+{pmg} ships with a highly configurable mail filter. This provides an
+easy but powerful way to define filter rules by user, domain, time
+frame, content type, and resulting action.
-image::images/screenshot/pmg-gui-mail-filter-rules.png[]
+[thumbnail="pmg-gui-mail-filter-rules.png", big=1]
-Every rule has 5 categories ('FROM', 'TO', 'WHEN', 'WHAT' and
+Every rule has 5 categories ('FROM', 'TO', 'WHEN', 'WHAT', and
'ACTION'), and each category may contain several objects to match
certain criteria:
-WHO - objects::
+'Who' - objects::
-Who is the sender or receiver of the e-mail? Those objects can be used
+Who is the sender or recipient of the email? Those objects can be used
for the 'TO' and/or 'FROM' category.
+
====
-Example: EMail-object - Who is the sender or receiver of the e-mail?
+Example: EMail-object - Who is the sender or recipient of the email?
====
-WHAT - objects::
+'What' - objects::
-What is in the e-mail?
+What is in the email?
+
====
-Example: Does the e-mail contain spam?
+Example: Does the email contain spam?
====
-WHEN - objects::
+'When' - objects::
-When is the e-mail received by {pmg}?
+When is the email received by {pmg}?
+
====
Example: Office Hours - Mail is received between 8:00 and 16:00.
====
-ACTIONS - objects::
+'Action' - objects::
Defines the final actions.
+
====
-Example: Mark e-mail with “SPAM:” in the subject.
+Example: Mark email with “SPAM:” in the subject.
====
Rules are ordered by priority, so rules with higher priority are
executed first. It is also possible to set a processing direction:
-'In':: Rule applies for all incoming e-mails
+'In':: Rule applies to all incoming emails
-'Out':: Rule applies for all outgoing e-mails
+'Out':: Rule applies to all outgoing emails
-'In & Out':: Rule applies for both directions
+'In & Out':: Rule applies to both directions
-And you can also disable a rule completely, which is mostly useful for
-testing and debugging. The 'Factory Defaults' button alows you to
+You can also disable a rule completely, which is mostly useful for
+testing and debugging. The 'Factory Defaults' button allows you to
reset the filter rules.
-Actions
--------
+[[pmg_mailfilter_action]]
+'Action' - objects
+------------------
-image::images/screenshot/pmg-gui-mail-filter-actions.png[]
+[thumbnail="pmg-gui-mail-filter-actions.png", big=1]
-Please note that some actions stops further rule precessing. We call
+Please note that some actions stop further rule processing. We call
such actions 'final'.
Accept
Quarantine
~~~~~~~~~~
-Move to quarantine (virus mails are moved to the “virus quarantine”,
+Move to quarantine (virus mails are moved to the “virus quarantine”;
other mails are moved to “spam quarantine”). This is also a 'final' action.
The BCC object simply sends a copy to another target. It is possible to
send the original unmodified mail, or the processed result. Please
-note that this can be quite different, i.e. when a previous rule
+note that this can be quite different, for instance, when a previous rule
removed attachments.
Header Attributes
~~~~~~~~~~~~~~~~~
-This object is able to add or modify mail header attributes. As notice above, you can use xref:rule_system_macros[macros], making this a very powerful object. For example, the 'Modify Spam Level' actions adds detailed infomation about detected Spam characteristics to the ` X-SPAM-LEVEL` header.
+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 add detailed information about detected Spam
+characteristics to the `X-SPAM-LEVEL` header.
-.Modify Spam Level Header Attribute
+.'Modify Spam Level' Header Attribute
----
Field: X-SPAM-LEVEL
Value: __SPAM_INFO__
Another prominent example is the 'Modify Spam Subject' action. This
simply adds the 'SPAM:' prefix to the original mail subject:
-.Modify Spam Subject Header Attribute
+.'Modify Spam Subject' Header Attribute
----
Field: subject
Value: SPAM: __SUBJECT__
~~~~~~~~~~~~~~~~~~
Remove attachments can either remove all attachments, or only those
-matched by the rules 'WHAT' object. You can also specify the
-replacement text if you want.
+matched by the rule's 'What' - object. You can also specify the
+replacement text, if you want.
+
+You can optionally move these mails into the attachment quarantine, where
+the original mail with all attachments will be stored. The mail with the
+attachments removed will continue through the rule system.
+
+NOTE: The Attachment Quarantine lifetime is the same as for the Spam Quarantine.
Disclaimer
~~~~~~~~~~
Add a Disclaimer.
+
+The disclaimer can contain HTML markup. It will be added to the first
+`text/html` and `text/plain` part of an email. A disclaimer only gets added if
+its text can be encoded in the mail's character encoding.
+
+
+[[pmg_mailfilter_who]]
+'Who' objects
+-------------
+
+[thumbnail="pmg-gui-mail-filter-who-objects.png", big=1]
+
+These types of objects can be used for the 'TO' and/or 'FROM' category,
+and match the sender or recipient of the email. A single object can
+combine multiple items, and the following item types are available:
+
+EMail::
+
+Allows you to match a single mail address.
+
+Domain::
+
+Only match the domain part of the mail address.
+
+Regular Expression::
+
+This one uses a regular expression to match the whole mail address.
+
+IP Address or Network::
+
+This can be used to match the senders IP address.
+
+LDAP User or Group::
+
+Test if the mail address belongs to a specific LDAP user or group.
+
+We have two important 'Who' objects called 'Blacklist' and
+'Whitelist'. These are used in the default ruleset to globally block
+or allow specific senders.
+
+
+[[pmg_mailfilter_what]]
+'What' objects
+--------------
+
+[thumbnail="pmg-gui-mail-filter-what-objects.png", big=1]
+
+'What' objects are used to classify the mail's content. A single
+object can combine multiple items, and the following item types are
+available:
+
+Spam Filter::
+
+Matches if the detected spam level is greater than or equal to the
+configured value.
+
+Virus Filter::
+
+Matches on infected mails.
+
+Match Field::
+
+Match specified mail header fields (for example, `Subject:`, `From:`, ...)
+
+Content Type Filter::
+
+Can be used to match specific content types.
+
+Match Filename::
+
+Uses regular expressions to match attachment filenames.
+
+Archive Filter::
+
+Can be used to match specific content types inside archives.
+This also matches the content-types of all regular (non-archived) attachments.
+
+Match Archive Filename::
+
+Uses regular expressions to match attachment filenames inside archives.
+This also matches the filenames for all regular (non-archived) attachments.
+
+
+[[pmg_mailfilter_when]]
+'When' objects
+--------------
+
+[thumbnail="pmg-gui-mail-filter-when-objects.png", big=1]
+
+'When' objects are used to activate rules at specific times of the
+day. You can compose them from one or more time frame items.
+
+The default ruleset defines 'Office Hours', but this is not used by
+the default rules.
+
+
+[[pmg_mailfilter_regex]]
+Using regular expressions
+-------------------------
+
+A regular expression is a string of characters which represents a list
+of text patterns which you would like to match. The following is a
+short introduction to the syntax of regular expressions used by some
+objects. If you are familiar with Perl, you will already know the
+syntax.
+
+Simple regular expressions
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In its simplest form, a regular expression is just a word or phrase to
+search for. `Mail` would match the string "Mail". The search is case
+sensitive so "MAIL", "Mail", "mail" would not be matched.
+
+Metacharacters
+~~~~~~~~~~~~~~
+
+Some characters have a special meaning. These characters are called
+metacharacters. The Period (`.`) is a commonly used metacharacter. It
+matches exactly one character, regardless of what the character is.
+`e.mail` would match either "e-mail" or "e2mail" but not
+"e-some-mail" or "email".
+
+The question mark (`?`) indicates that the character immediately
+preceding it shows up either zero or one time. `e?mail` would match
+either "email" or "mail" but not "e-mail".
+
+Another metacharacter is the asterisk (`*`). This indicates that the
+character immediately preceding it may be repeated any number of times,
+including zero. `e*mail` would match "email", "mail", and
+"eeemail".
+
+The plus (`+`) metacharacter indicates that the character immediately
+preceding it appears one or more times. So `e+mail` does not match
+"mail".
+
+Metacharacters can also be combined. A common combination includes the
+period and asterisk metacharacters (`.*`), with the asterisk
+immediately following the period. This is used to match an arbitrary
+string of any length, including the null string. For example:
+`.*company.*` matches "company@domain.com" or "company@domain.co.uk"
+or "department.company@domain.com".
+
+The book xref:Friedl97[] provides a more comprehensive introduction.
projects / pmg-docs.git / blobdiff