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

In this group you can edit the pattern that messages must match before the filter is applied to them. You can select whether all of the defined rules must match, or whether a single match is enough. See Search Patterns below for a detailed description of each search rule type.

You can click on  +  to get an additional (initially empty) rule if you want to define more complex patterns, and on  −  to remove the selected rule. Clear clears the pattern, i.e., it removes all but one rule from the screen and resets it.

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  +  to get a new, empty action (if you want to define more than one action), and on  −  to remove the selected action. Clear clears the list, i.e. it removes all but one action and resets that one.

In this group you can define a few advanced options that allow you to fine tune 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, or to particular incoming email accounts.

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 Message → Apply 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 processed when 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 Message → Apply Filter submenu. You can then apply this single filter to a message or a set of messages. If you select this option, you may optionally select a keyboard shortcut and insert a special icon to invoke this filter from the toolbar.

Another way of applying filters is to use the Message → Apply Filters menu option, which applies all the filters – one after another – until they are all used or one of the filters that matches specifies the If this filter matches, stop processing here option.

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

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

Searches all the headers in the message.

Searches the “To” and “CC” header fields of the message.

Sets upper or lower bounds on the message's size.

Sets upper or lower bounds on the message's age.

Sets restrictions on the status of the message (Important / Read / Unread / etc. see Message → Mark Message >).

Checks for tagged messages. See Message → Mark Message >.

Checks for encrypted messages.

Searches the header field with that name.

This will move the message into another folder, and remove it from its current folder.

This will copy the message to another folder, and leave the message in the current folder.

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

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

This will add a tag to the message. You may choose from a list of all the tags that have been defined.

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

This will set the method of transport (e.g. SMTP) that will be used when you reply to the message. You may choose from a list of all your outgoing email accounts.

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

This will forward the message inline (i.e. as if you selected Message → Forward → Inline...) to another email address. You may select a custom forwarding template if such a template has been defined. If KAddressBook is installed, you may choose the “Forward To” address from a pop-up window.

This will redirect the message as-is to another email address. If KAddressBook is installed, you may choose the “Redirect To” address from a pop-up window.

Will return a message to the sender that verifies 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 do not recommend that you send them to everyone, since this makes tracking of spam messages very easy for the spammers.

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 wait until the program returns. If you do not want KMail to wait, append '&' to the command. You can feed the segments of the message into the program one by one: %0, %1, etc. stand for files representing the message segments. For common messages, %0 is the plain text message, %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 database, you can use the %{itemid} or %{itemurl} placeholders to achieve that.

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 may be performed on the command line.

Both the Anti-Spam Wizard and the Anti-Virus Wizard use the “Pipe Through” action to check for spam / malware. The commonly available anti-spam and anti-virus programs return the message, and insert an extra header record, if spam (or a virus) is detected.

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

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.

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.

Will play the specified sound. A browse button lets you choose a pre-recorded sound (e.g. .wav) file.

If KAddressBook is installed, this action will let you specify which header to scan (From, To, CC, or BCC), what tag to assign, if any, and which named address book to store the addresses in.

Deletes the selected message(s). Use this option cautiously. Deleted messages cannot be recovered.

This is the inverse of Mark As, above. Instead of marking the selected message as important, read, etc., this action will clear the specified flag.

Will encrypt the selected message(s) with the specified public key. You may choose from any public / private key pairs saved on your key ring.

Will decrypt the selected message(s). Use this action with caution. KMail will decrypt messages automatically when you open them for viewing, so you probably don't really need to use this action.

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.

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.

Try to keep the filter rules as simple as possible.

The various filter actions have different degrees of 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 allows 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.