Message Filters

After using KMail for a while, you may find that you have trouble sorting out the new messages in your inbox when they arrive. Filters allow you to automatically perform certain actions on incoming messages and to manually perform actions on selected messages in a folder.

Filters consist of: filter criteria, whose rules are used as criteria to determine whether this filter should be applied to a given message; and a list of filter actions, which describe what is to be done with, or to, the message if the search pattern matches. Read more about filter criteria and filter actions in the following subsections.

Note

Filters are considered one after the other, starting with the first filter in the list. The first one whose pattern matches the given message gets executed; you can request that the remaining filters also be applied, but the default is to stop processing at the first matching filter.

Usually, filters are used on incoming messages, but they can also be applied to sent messages or to an arbitrary message or group of messages. To selectively filter messages, select the messages you want to filter in the message list and either type Ctrl+J or select MessageApply Filter: this will apply all filters that have been marked for manual filtering in the filter dialog to those messages.

Fast Filter Creation

There are two methods for creating a filter; the quick method is to use MessageCreate Filter and select a criteria from the submenu: this will call the filter dialog and present you with a new filter which has the first rule of the search pattern and the first action (as Move into Folder) preset. In most cases, all you have to do is select the folder where the message should be moved to; but you can, of course, edit the filter as you like.

When creating a filter on mailing list messages this method will try really hard to find a criterion that uniquely identifies messages from that list; If it succeeds, the guessed name of the list is presented in the MessageCreate FilterFilter on Mailing-List... menu entry.

The second method is to manually construct a filter from scratch by calling the filter dialog through SettingsConfigure Filters.... The filter dialog is described in detail in the following subsection.

The Filter Dialog

This dialog allows you to manage and edit your list of filters.

You can reach it either via MessageCreate Filter or SettingsConfigure Filters....

The dialog is divided into three main sections on the General and Advanced tab:

Available Filters

This group contains the list of filters and some action buttons to modify the filters, namely: to create new filters; to move them up or down the list; to delete them; or to rename them. If you select a filter from the list, its properties are shown in the right-hand half of the dialog.

Filter Criteria

In this group you can edit the pattern that messages must match for the filter to be applied to them. You can select here whether all of the defined rules must match or whether it suffices that any one of them matches. See Search Patterns below for a detailed description of each search rule type.

You can click on More to get an additional (initially empty) rule if you want to define more-complex patterns and on Fewer to remove the last rule. Clear clears the pattern, i.e. it removes all but two rules from screen and resets those two.

Invalid or empty rules are not evaluated.

Filter Actions

In this group you can edit the list of actions that are applied to all messages that match the defined filter criteria. See Filter Actions below for a detailed description of each action type.

You can click on More to get a new, empty action (if you want to define more than one action) and on Fewer to remove the last action. Clear clears the list, i.e. it removes all but one action and resets that one.

Invalid or empty actions are not executed.

Advanced Options

In this group you can define a few advanced options for filters that allow you to refine your filtering.

Using the first row of check boxes, you can toggle when the filter is applied: the Apply this filter to incoming messages option means that the filter is applied to messages when you receive them (i.e. on Check Mail). The filter can be applied to all messages, to all but online IMAP accounts and to a selection of incoming folders.

The Apply this filter to sent messages option means that the filter is applied to messages when you send them and the Apply this filter on manual filtering option controls whether to apply this filter when filtering is specifically selected (i.e. via MessageApply Filters.)

If Apply this filter to sent messages is checked the filter will be triggered after the message is sent and it will only affect the local copy of the message. If the recipient's copy also needs to be modified, please use Apply this filter before sending messages.

The If this filter matches, stop processing here check box controls whether or not the filters after the current filter will be applied, if the current filter matches.

If the Add this filter to the Apply Filter menu check box is selected, this filter will be inserted in the MessageApply Filter submenu. You can then apply this filter to a message. Another way of applying filters is to use MessageApply Filters menu option, which applies all the filters - one after another until they are all used or one of the filters that matches has the If the filters matches, stop processing here.

Note

Filters are automatically named unless you explicitly rename them using the Rename... button. The dialog assumes that it should continue auto-naming the filter as long as the filter name starts with <.

Note

If you apply filter changes, via OK or Apply, only valid filters are actually copied to the internal filter manager.

Similarly, empty rules and actions are removed from the pattern and action list respectively, before the filter is saved.

Search Patterns

The most common use of filters is to filter on the sender of messages; this can be done by choosing From. A good bet for a mailing list would be <recipients>, but there are other criteria a filter can search for (note that all patterns are interpreted case-insensitively):

<message>

Searches the whole message (i.e. headers, body and attachments, if any);

<body>

Searches the body of the message (i.e. the whole message except the headers);

<any header>

Searches the headers of the message;

<recipients>

Searches the To and CC header fields of the message;

<size in bytes>

Sets upper or lower bounds on the message size;

<age in days>

Sets upper or lower bounds on the message age;

<status>

Sets restrictions on the status of the message;

Any other name

Searches the header field that is given by that name.

The list of possible rules depends on what you selected in the first drop down box. The available rules are:

RuleAvailable forDescription
contains/does not containall textual search itemsMatches if the searched item contains (or does not contain) the given text.
equals/does not equalmost textual search itemsMatches if the searched item is equal to (or not equal to) the given text.
matches regular expr./does not match reg. expr.all textual search itemsMatches if a part of the searched item matches the given regular expression (or does not match it). If the regular expression editor is installed then you can edit the regular expression by clicking on the Edit... button.
has an attachment/has no attachment<message>Matches if the message has an attachment (or does not have an attachment).
is in address book/is not in address bookmost textual search itemsMatches if the searched item contains an address that is in your address book (or if the searched items contains only unknown addresses). Of course, this rule only makes sense for address fields like From or <recipients>
is in category/is not in categorymost textual search itemsMatches if the searched item contains an address that is in the specified category in your address book (or if the searched item contains no address that is in the specified category). Again, this rule only makes sense for address fields.
is equal to/is not equal tonumerical search itemsMatches if the value of the search item is equal to (or not equal to) the specified value.
is less thannumerical search itemsMatches if the value of the search item is less than the specified value.
is greater thannumerical search itemsMatches if the value of the search item is greater than the specified value.
is less than or equal tonumerical search itemsMatches if the value of the search item is less than or equal to the specified value.
is greater than or equal tonumerical search itemsMatches if the value of the search item is greater than or equal to the specified value.
is/is not<status>Matches if the message has (or does not have) the specified status.

Filter Action

The most common use of filters is to sort incoming messages to certain folders; this can be done by choosing Move into Folder. Here is a list of all possible actions:

Move Into Folder

This will file the message into another folder, removing it from its current folder if necessary; you cannot, currently use IMAP folders as a target.

Copy Into Folder

This will copy the message to another folder.

Note

You currently cannot use IMAP folders as a target.

Set Identity To

This will set the identity that will be used if you reply to this message.

Mark As

This allows you to mark the message as read or important (flagged), but also as forwarded, replied, etc.

Send Fake MDN

This will send a faked message disposition notification (i.e. a read receipt) to the sender of the message.

Set Transport To

This will set the method of transport (e.g. SMTP) that will be used if you reply to the message.

Set Reply-To To

This will modify the Reply-To field of this message. This can be useful for mailing lists that automatically set a Reply-To which you do not like.

Forward To

This will forward the message inline (i.e. as if you selected MessageForwardInline...) to another email address. You can select the template to be used when forwarding with this filter with the drop down list.

Redirect To

This will redirect the message as-is to another email address.

Confirm Delivery

Will try to return a message to the sender that indicates successful delivery of their message, if the sender requested that.

This action allows you to select who will get delivery receipts from you. Though you can globally enable the sending of delivery confirmations in the Configure KMail... dialog (Security page) we recommended not to send them to everyone, since this makes tracking of spam messages, for example, very easy for the sender.

Execute Command

This will execute a program, but will not modify the message. Specify the full path to the program you want to execute; KMail will then block until the program returns. If you do not want KMail to block then append '&' to the command. You can feed the program with the parts of the mail: %0, %1, etc. stand for files representing the message parts; for common messages %0 is the text, %1 the first attachment and so on. Additionally, the whole message is fed into the program's stdin; and every occurrence of %{foo} is replaced by the content of the foo header. If you need to identify the message via its storage location in the Akonadi store, you can use the %{itemid} or %{itemurl} placeholders to achieve that.

Warning

This currently only works if the message has at least one attachment. No, not even %0 will work in the general case!

Tip

You can enter arbitrarily-complex shell commands here, since KMail uses a sub shell to execute the command line; therefore, even this command will work (within its limits): uudecode -o $(mktemp kmail-uudecoded.XXXXXX) && echo $'\a'

Pipe Through

This will feed the message to a program: if the program returns output, the entire message (including the headers) will be replaced with this output; if the program does not return output or exits with a return code other than 0 (indicating an error occurred), the message will not change. Specify the full path to the program. The same substitutions (%n, %{foo} as with execute command are performed on the command line.

Warning

Be cautious with this action, as it will easily mess up your messages if the filter program returns garbage or extra lines.

Remove Header

Will remove all header fields with the given name from the message. This is useful mainly for removing bogus Reply-To: headers.

Add Header

If no such field is already present this will add a new header field with the given name and value to the message; if there already is a header field with that name, it is overwritten with the given value; if there are already multiple headers with the given name (e.g. Received: headers), an arbitrary one of them is overwritten and the others are left unchanged -- this is a known limitation. You may want to combine this filter with the remove header filter above to make sure that there are no other headers with that name in the message.

Rewrite Header

Will scan the given header field, modify its contents and write it back. The search string is always interpreted as a case-sensitive regular expression. The replacement string is inserted literally except for occurrences of \n, $n and ${nn}, where n is a positive (single-digit, except for the third form) number or 0. These constructs are interpreted as back references to substrings captured with parentheses in the search string.

Analogous restrictions as in the add header action apply here, too.

Play Sound

Will play the specified sound.

Filter Examples

As of yet KMail does not highlight or mark mails that have an extra Priority: header. If I want to flag all urgent messages as being important, I can use a filter:

Procedure 3.1. Tagging urgent messages as important

  1. Open up the SettingsConfigure Filters... dialog and click the New icon below the Available Filters list.

  2. In the Filter Criteria area, select Anywhere in Headers and contains from the drop down boxes and type Priority in the text field. Select the same criteria in the next line and type urgent in the text field of the second drop down box.

    So your filter will match all messages containing a Priority: urgent header field.

  3. Skip down to the Filter Actions area. Select Mark As from the first drop down box. A new drop down box containing a list of marker flags is shown to the right. Select Important from the drop down box.

  4. Since you want this filter to not prevent other filters message rules from being applied, carefully uncheck the If this filter matches, stop processing here option.

  5. Click on OK, and you are done.

    Just keep in mind to move the Priority: urgent filter entry to the top of the Available Filters list, each time, when you have added another filter, so your non-stopping filter will always be applied first.

If I am subscribed to the (general) KDE List, I could create a folder for the list (I will call it KDE-General) and use a filter to automatically transfer new messages from my inbox to my KDE-General folder if they are from the KDE List. Here is how to create this filter:

Procedure 3.2. Filtering a mailing list

  1. Try if MessageCreate filterFilter on Mailing-List... can identify the mailing list (the name of the list should then appear in the menu item); in this case, this works and I am presented a filter that has List-Id contains <kde.kde.org> preset. You select the desired destination folder from the folder pull-down menu in the Filter Action group and that is it.

    If that does not work, think of a unique way of identifying the messages you want to filter. The (almost) unique property of my KDE List messages is that they always contain kde@kde.org in the To: or CC: field. It is only almost unique, because this fails for cross-posted messages.

  2. Select SettingsConfigure Filters....

  3. Press the New button to create an empty filter. It will appear as <unknown>.

  4. In the Filter Criteria area, select All Recipients from the first drop down box, contains from the second drop down box, and type kde@kde.org in the text field.

  5. Skip down to the Filter Actions section. Select Move Into Folder from the first drop down box. Click on the folder icon and a window containing a list of folders will appear. Select the folder that you want the filtered messages to be transferred to. For this example, you would select KDE-General.

You may find that you need to use more powerful criteria to properly filter your messages; for example, you may only want to filter the KDE List messages that are written by your friend Fred Johnson <fj@anywhere.com>. This is where the rest of the matching criteria section comes into play:

Procedure 3.3. Extending the filter

  1. Open up the Configure Filters... window and select the filter you just created.

  2. Since you want to filter all messages that have kde@kde.org in the To: or CC: field and that are from Fred, check the Match all of the following radio button.

  3. Now, go to the second search rule and select the following from the pull-down menus: From, contains. Now, type fj@anywhere.com in the text field.

You now have a filter that transfers all KDE List messages that are from fj@anywhere.com.

Filter Optimization

It is important to know that, for example, the order of the filters has an impact on the speed of the filter process. Here are some ideas which can help you to improve the filtering:

Stop filter processing as early as possible:

If you know that a filter finally processes a certain class of messages, please make sure to check the option If this filter matches, stop processing here for the filter. This will avoid the evaluation of the filter rules of all subsequent filters. (See the advanced options in the Filter Dialog).

An example is filtering messages from mailing lists via List-Id header into separate folders. Having found out that a message came from list A means that you can avoid checking the next filter for messages from list B.

Consider the costs of the evaluation of filter rules:

The time required to evaluate a filter rule depends on the way the rule is constructed. In particular, scanning for a substring using the contains operation is faster than a pattern matching using the matches regular expr. operation.

Another dependency is on the amount of data which is used for the evaluation of a filter rule. If the rule is based on a message header, its evaluation should normally be much faster than the evaluation of a rule based on the complete message.

You should try to keep the filter rules as simple as possible.

Check the order of your filters:

All the different filter actions have a different complexity. The most expensive filter actions are Pipe Through and Execute Command, because both need external programs to be run. Placing filters containing these filter actions behind other filters that can reduce the number of times these complex actions are required is useful, if the filter logic does allow this.

An example is filtering messages from a mailing list and detecting spam messages. For the spam detection you will usually use an external tool via a Pipe Through action. Filtering the messages for the mailing list is done via the List-Id header. If you do not want to check the messages from the mailing list for spam too, it is better to use the filter for the mailing list messages before the filter for the spam detection. This way you avoid the expensive and slow spam check for all messages which were identified as mailing list messages.

Filter Log

If you want to verify that your filters work as intended, you can open a viewer for the filter log via ToolsFilter Log Viewer....

In the viewer, there you can configure the logging of the filter processing. You can control the detail level of the log, clear the log or save the log into a file. The log can provide valuable information if you need to debug your filtering process.