How to Configure Email Filters

filters email

Last modified: November 13, 2024

Overview

Email filters use the criteria that you specify to determine how to handle email messages. The following cPanel interfaces allow you to configure email filters:

The Global Email Filters interface (cPanel » Home » Email » Global Email Filters) — Global email filters affect the cPanel account’s email addresses.
The Email Filters interface (cPanel » Home » Email » Email Filters) — User-level filters affect specific email addresses on the cPanel account.

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.

Note:

In these interfaces, click + to add a rule, or click - to remove rules.

Filter rules and criteria

The first set of options specifies which part of the email message the system examines to determine whether the text matches your filter parameters.

You can choose from the following options:

From — The message sender’s address.
Subject — The message’s subject line.
To — The address to which the sender sent the message.

Note:

Generally, the recipient does not receive the BCC field in an email’s header. For this reason, you cannot use the BCC field in a filter.
Reply Address — The address at which the sender receives replies.
Body — The message’s content.
Any Header — Any Header refers to any part of the header in an email, including: To, From, Envelope-To, Content-Type, etc.
Any Recipient — Any recipient of the message.
Has Not Been Previously Delivered — The system only examines messages that remain in the queue for delivery.
Is an Error Message — The system only examines error messages that an auto-response system sends.
List ID — The account’s mailing lists.
Spam Status — Whether Apache SpamAssassin™ marked the message as spam. The Spam Status line begins with Yes or No.
Spam Bar — The content of the Spam Bar header that Apache SpamAssassin generated for this message. The more plus signs (+) that Apache SpamAssassin assigns to a message, the greater the likelihood that the system marks the message as spam.
Spam Score — The total number of plus signs (+) in the Spam Bar value, expressed as an integer. For more information about the Spam Score option, read the Spam Score section below.

Operators

After you select the portion of the email that the system will examine, select the type of comparison between that portion and the criteria that you enter.

You can choose from the following operators:

equals — The text exactly matches a defined string.
Click to view an example rule that exactly matches a string

example@example.com

This rule will only match emails from [email protected].

You could use this rule with the Redirect to Email action to forward all emails from one address to another address.
matches regex — The text matches a regular expression that you define.
Click to view an example rule that matches a regular expression
[Cc]ongratulations[!.+]

This rule matches these example Subject lines (among others):
- Congratulations!
- congratulations!
- Congratulations!!!!!
- congratulations!!!!!!!!!!
You could use this rule with the Fail With Message action to bounce emails that contain Subject lines that may indicate spam.
Note:
- When you select this option, the filter interprets characters as Perl-Compatible Regular Expressions (PCRE), rather than as literal characters that are part of a string. This includes commonly-used wildcard characters such as the * and ? characters.
- Exim interprets backslashes as escaped characters. As a result, you may need to include additional backslashes in your PCRE. For more information about how Exim interprets backslashes, read Exim’s documentation.
contains — The text contains a string that you define.
Click to view an example rule that contains a string match
purchase

This rule matches these example sentences in an email’s body text (among others):
- I want to purchase a product from you.
- There was a problem with my purchase.
- This was the best purchase our company has made!
You could use this rule with the Deliver to Folder action to direct business-specific emails into a Business email folder.
does not contain — The text does not contain the defined string.
Click to view an example rule that filters out a string
Sale

This rule matches emails with the following example Subject lines (among others):
- Let's catch up
- Wedding photos
This rule does not match emails with the following example Subject lines (among others):
- Sale! Great purchase opportunity!
- Once-In-A-Lifetime Sale
You could use this rule with the Redirect to Email action to direct emails that are not about sales to a personal email address.
begins with — The text begins with the defined string.
Click to view an example rule that matches a beginning string
example

This rule matches emails from the following example addresses (among others):
- [email protected]
- [email protected]
This rule does not match emails from the following example addresses (among others):
- [email protected]
- [email protected]
You could use this rule with the Deliver to Folder action to redirect emails from your website’s users to a Priority folder.
ends with — The text ends with the defined string.
Click to view an example rule that matches an ending string
example.com

This rule matches emails from the following example addresses (among others):
- [email protected]
- [email protected]
This rule does not match emails from the following example addresses (among others):
- [email protected]
- [email protected]
You could use this rule with the Pipe to a Program action to automatically pipe emails from your website’s users into a ticket program.
does not begin — The text does not begin with the defined string.
Click to view an example rule that filters out a beginning string

TEST

This rule matches emails that do not begin the body text with TEST.

You could use this rule with the Fail With Message action to confirm that test emails can reach your email address without cluttering up your inbox.
does not end with — The text does not end with the defined string.
Click to view an example rule that filters out an ending string

This is an automated message, please do not reply

This rule matches emails that do not end with the sentence This is an automated message, please do not reply.

You could use this rule with the Deliver to Folder action to direct out-of-office emails into an email folder.
does not match — The text does not exactly match the defined string.
Click to view an example rule that filters out a string

sale

This rule matches emails with any Subject line except sale.

You could use this rule with the Stop Processing Rules action to stop a filter from acting on emails with the Subject line sale.

Spam Score

The following options are only applicable when you select the Spam Score option:

is above (#s only) — The message’s Spam Score is greater than the number that you define.
is not above (#s only) — The message’s Spam Score is equal to or less than the number that you define.
is below (#s only) — The message’s Spam Score is less than the number that you define.
is not below (#s only) — The message’s Spam Score is greater than or equal to the number that you define.

Criteria

Enter the criteria to use in the text box under the Rules menus. The type of data that you enter determines the comparison that the system performs.

For example, if you select the From and Equals filters, enter [email protected] as the criteria. The system determines that any email from [email protected] matches the filter, but does not match [email protected] because it contains additional letters.

Important:

Exim converts newlines into spaces in the $message_body field. Do not add \n characters to any body filters that you create.

Multiple rules

To create additional rules for a filter, click the plus symbol to the right of a rule. A new option menu, operator menu, and criteria text box will appear on the interface.

To delete a rule, click the minus symbol to the right of that rule. The system will remove that rule from the interface.

Select how the system processes the list of rules with the or menu to the right of the rules:

or — Any rule in the list must be true for the system to perform the actions.
and — All rules in the list must be true for the system to perform the actions.

For example, you could create a filter that checks the following rules:

The email has a Subject line that contains the word alert.
The email comes From a website monitoring service.

This filter will return website monitoring alert emails.

Operator interactions

When you create a filter that uses multiple rules, the system processes rules that contain and operators before rules that contain or operators. In logical notation:

The system processes A or B and C as A or (B and C).
It processes A and B or C as (A and B) or C.

For example, you could create a filter that checks the following rules:

From lines begin with user and end with example.com, or
Subject lines begin with A user from example.com reports

This filter will match the following emails:

Emails whose From lines begin with user and do not end with example.com, and whose Subject lines begin with A user from example.com reports.
Emails whose From lines do not begin with user but end with example.com, and whose Subject lines begin with A user from example.com reports.
Emails whose From lines begin with user and end with example.com, and whose Subject lines do not begin with A user from example.com reports.

This filter will not match the following emails:

Emails whose From lines begin with user but do not end with example.com, and whose Subject lines do not begin with A user from example.com reports.
Emails whose From lines do not begin with user but end with example.com, and whose Subject lines do not begin with A user from example.com reports.

Actions

When cPanel determines that an email message matches your filter, it handles that message with the any of the following actions that you specify:

Discard Message — The system discards the incoming message with no failure notice.
Redirect to Email — The system forwards the message to another email address that you specify.

Note:

This action does not retain a copy of the message in the mailbox. To retain a copy of the message in the inbox and forward it to another address, add a Deliver to Folder action to the filter and set it to deliver it to the INBOX folder.
Fail With Message — The system discards the message and automatically send a failure notice to the sender.
Stop Processing Rules — The system stops performing further actions or applying any remaining filters on this message.
Deliver to Folder — The system delivers the message to a specified folder.
Pipe to a Program — The system sends the incoming message to a specified program. For more information, read the Pipe to a Program section below.

Pipe to a Program

Important:

Make certain that your script uses the proper file permissions (0700). To change your script’s file permissions, run the chmod 0700 myscript.php command, where myscript.php represents your script’s location and file name.
This option only appears if your hosting provider enables it.

Use the Pipe to a Program option to parse and enter email information into a different system. For example, use the Pipe to a Program option to pipe email information to a program that enters email information into a ticket system.

STDIN pipes email and headers to the program.
Pipes can accept variables from the $_SERVER array and variables on the command line.
The language or environment that you use may cause memory limit issues.
If your script produces any output, even a blank line, the system will create a bounce message that contains that output.

When you use the Pipe to a Program option, enter a path that is relative to your home directory. For example, to use the /home/user/script.pl script, enter script.pl in the Pipe to a Program text box, where user represents your username.

Note:

If you use PHP, make certain that you appropriately wrap your code in start and end tags.

Multiple actions

To create additional actions for a rule, click a plus symbol to the right of an action. A new action menu will appear on the interface. For example, you could add the Deliver to Folder action to ensure that an inbox keeps a copy of all emails sent to it, then add the Redirect to Email action to forward those emails to a new destination address.

To delete an additional action, click the minus symbol to the right of the action. The system will remove that action from the interface.