1. cPanel & WHM Documentation
  2. cPanel
  3. Email
  4. Email Filters
filters email cpanelui webmail

Email Filters

Valid for versions 82 through the latest version

Version:

82

Last modified: May 28, 2024

Looking for this interface?
Note:

Your hosting provider can enable or disable this interface in WHM's Feature Manager interface (WHM >> Home >> Packages >> Feature Manager).

Overview

This interface allows you to create, edit, and remove email filters for a selected email account.

An email filter allows you to set a rule for incoming messages (for example, a message from desired sender). If a message matches that rule, then the system can automatically perform an action on that message (for example, deleting the message).

Important:
We strongly recommend that you use multiple, simple filters instead of a single large filter. Exim, the server’s mail transfer agent, handles many small rules more efficiently than a single large rule.

Create a filter

To create a new filter, perform the following steps:

  1. In the Filters by Users table, click Manage Filters for the appropriate email account.

    Note:
    If you access this interface from cPanel’s Webmail interface, proceed to step 2.

  2. Click Create a New Filter.

  3. Enter a name for the filter in the Filter Name text box.

  4. Configure your filter’s rules and actions.

    Note:
    For detailed information on how to configure your filter, read our How to Configure Email Filters article.

  5. Click Create.

Current Filters

To list an email account’s filters, click Manage Filters in the row of the appropriate email account. The Current Filters table lists all of the filters for the selected email account in the order the filters run.

New filters are appended to the Current Filters list, meaning they will run after pre-existing filters. You may drag and drop the filters to change the order in which the filters will run.

Edit a filter

To edit an existing filter, perform the following steps:

  1. Click Edit next to the appropriate filter name.

  2. Make the desired changes to the filter.

  3. Click Save.

Delete a filter

To delete a filter, perform the following steps:

  1. Click Delete for the appropriate filter name.

  2. Click Delete Filter.

Test a filter

To test a filter, perform the following steps:

  1. In the Filters by Users table, click Manage Filters next to the desired email account.

  2. Enter a test email message in the Filter Test text box.

    Note:
    Include the characters, words, and conditions that you configured for your filter.

  3. Click Test Filter. The Filter Trace Results interface will appear.

The Filter Trace Results interface

The Filter Trace Results interface will display results similar to the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Sub-condition is false: not first_delivery
Condition is false: not first_delivery and error_message
Condition is false: $message_body contains Keyword
Return-path copied from sender
Sender      = username@hostname.example.com
Recipient   = username@hostname.example.com
Testing Exim filter file "/home/example/etc/example.com/filtertest/filter"

Headers charset "UTF-8"
Filtering did not set up a significant delivery.
Normal delivery will occur.

The results contain the following information:

  • Each condition in the filter, and whether it returned a true or false result.
  • The Sender and the Recipient of the test message.
  • The filter file’s name.
  • The character set of the message.
  • Whether the filter triggers a change in delivery or if it will deliver normally.
    • Filtering did not set up a significant delivery. Normal delivery will occur. — The system will deliver the message to the mailbox.
    • Filtering set up at least one significant delivery or other action. No other deliveries will occur. — The system will deliver the message to another mailbox or folder, or it will not deliver the message.

Additional Documentation