Introduction

When using filters, you might have issues receiving email depending on how your filters were configured. Identifying which rule caused the problem might be challenging if you have many of them. Fortunately, cPanel has a feature that can help you find the cause.

Testing Filters via the cPanel Interface

Account Level Email Filters

1. Login to the cPanel account
2. Click on the "Email Filters" icon
3. Click on the "Manage Filters" link to the right of your email account
4. Under your existing filters will be a section labeled "Filter Test"
5. Enter a test message that contains the specifics you want to test
6. Click the blue "Test Filter" button

Global Email Filters

1. Login to the cPanel account
2. Click on the "Global Email Filters" icon
3. Under your existing filters will be a section labeled "Filter Test"
4. Enter a test message that contains the specifics you want to test
5. Click the blue "Test Filter" button

Email Filter Test Results

The following shows an example of the test results where a message was discarded because the sender's email contained 'localhost'.

 Sub-condition is false: not first_delivery 
 Condition is false: not first_delivery and error_message 
 Condition is true: $header_from: contains localhost 
Return-path copied from sender
Sender      = test@localhost
Recipient   = test@cptest.tld
Testing Exim filter file "/etc/vfilters/cptest.tld"

Headers charset "UTF-8"
Save message to: /dev/null 0660
Filtering set up at least one significant delivery or other action.
No other deliveries will occur.

Testing Email Filters via Command Line

1. Login to the server as the root user via SSH or Terminal
2. Create a text file that contains the email message to test against your filters. Let's imagine that this file exists at: /home/mydom/mail/path-to-the-email-you-want-to-test
   

   To: test@cptest.tld
   From: cpanelnoreply@gmail.com
   Subject: Test Message
   
   This is a test message.

3. Use the following command to test an Account Level email filter for the test@cptest.tld account. Be sure to update the command to match your account's filter, test message files.
   

   exim -d-all+filter -bf /home/cptest/etc/cptest.tld/test/filter </home/mydom/mail/path-to-the-email-you-want-to-test

4. Use the following command to test the Global Email Filter for a domain. Be sure to replace the path to your domain's vfilters file, and the path to your test message:

   exim -d-all+filter -bf /etc/vfilters/cptest.tld </home/mydom/mail/path-to-the-email-you-want-to-test

5. To test the system filter for the entire server, use the following:

   exim -d-all+filter -bf /etc/cpanel_exim_system_filter </home/mydom/mail/path-to-the-email-you-want-to-test

Please note that instead of a new text file, you can use an actual email file from your inbox as the test message.

Identifying Problems With The Exim Main Log

The following is an example of a message transaction from the Exim main log where a message was unintentionally discarded due to a filter rule.

/var/log/exim_mainlog

2021-08-02 15:51:06 1mATf7-00024K-A9 <= you@yourdomain.com H=server.yourdomain.com [1.2.3.4]:51514 P=esmtps X=TLS1.2:ECDHE-RSA-AES256-GCM-SHA384:256 CV=no S=93039 T="Test" for me@mydomain.com
2021-08-02 15:51:06 1mATf7-00024K-A9 => /dev/null <me@mydomain.com> R=central_filter T=**bypassed**
2021-08-02 15:51:06 1mATf7-00024K-A9 Completed

The following highlight from the above transaction means that the message was discarded because it triggered one of the conditions within the account level filter for mydomain.com:

/dev/null <me@mydomain.com> R=central_filter T=**bypassed**

If a message was filtered by your system filter, then the Exim mainlog will show:

R=system_filter T=**bypassed**

You can use the following guide to learn more about viewing the Exim Logs:

Where are the Exim logs?