How-To test email filters

Introduction

On accounts that have account level filters, you might have issues receiving emails depending on how your filters are set up if the sent email triggered one of the conditions within your email filter.

An example:

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 line 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** 

Where are the Exim logs?

Procedure

If you have lots of conditions it might be hard to identify which caused the email to be discarded. Fortunately cPanel has a feature that can help you find the causing condition. To troubleshoot such issues you can use the Filter Test feature within cPanel>Global Email Filters and mimic the contents, sender and recipient of the email that was filtered. Make sure you have an existing filter created otherwise Filter Test will be hidden.

An example of how the output of Filter Test will look like:

 Sub-condition is false: not first_delivery 
 Condition is false: not first_delivery and error_message 
 Condition is true: $header_from: contains gmail.com 
Return-path copied from sender
Sender      = tryit@cent8.argentina.com
Recipient   = tryit@cent8.argentina.com
Testing Exim filter file "/etc/vfilters/tryit.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.

The above example mail was discarded because the sender's email contained 'gmail.com'.

You can read more about Filter Test in our documentation:

https://docs.cpanel.net/cpanel/email/global-email-filters/#test-a-filter

There is a way to test email filters via the command line as well.

You might need to modify your email filters to redirect your emails to a folder or a specific email account instead of discarding it, otherwise this method will not work. Use the following example to test the cPanel account's email filter:

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

To test the system filter use the following example:

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