Knowledge Base / How to Configure Mail Filters

Home / Knowledge Base / How to Configure Mail Filters



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


 In either of these interfaces, click the + button to add a rule, or click the – button to remove rules.

Filter rules and criteria

The first set of options specifies which part of the email message cPanel will examine to determine whether the message matches your filter parameters.

You can choose from the following options:

  • From — The message’s sender’s address.
  • Subject — The subject line of the message.
  • To — The address to which the sender sent the message.
  • Reply Address — The address at which the sender will receive replies.
  • Body — The content of the message.
  • Any Header — Any part of the header portion of the message.
  • Any recipient — Any recipient of the message.
  • Has not been previously delivered — cPanel will only examine messages that are still in the queue for delivery.
  • is an error message — cPanel will only examine error messages that are from an auto-response system.
  • Spam Status — Whether Apache SpamAssassin™ marked the message as spam. The Spam Status will begin with either 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 message is spam.
  • Spam Score — The total number of plus signs (+) in the Spam Bar value, expressed as an integer.


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

You can choose from the following options:

  • equals — Exactly match the defined string.
  • matches regex — Match a regular expression that you define.


    The filter text box will accept regular expressions when you select this option, rather than more commonly-used wildcard characters (for example, * or ?).
  • contains — Contains a string that you define.
  • does not contain — Does not contain the defined string.
  • begins with — Begins with the defined string.
  • ends with — Ends with the defined string.
  • does not begin — Does not begin with the defined string.
  • does not end with — Does not end with the defined string.
  • does not match — Does not exactly match the defined string.

The following options are only applicable when the Spam Score option is selected.

  • is above (#s only) — Greater than the number that you define.
  • is not above (#s only) — Equal to or less than the number that you define.
  • is below (#s only) — Less than the number that you define.
  • is not below (#s only) — Greater than or equal to the number that you define.


When you create a filter that uses several operators, cPanel will process the and operator before the or operator. As a result, cPanel processes email filters as follows:

  • A or B and C will be processed as A or (B and C).
  • A and B or C will be processed as (A and B) or C.


Enter the criteria that you wish for cPanel to use in the text box under the Rules menus. The type of comparison that you wish cPanel to make determines the type of data that you enter.

For example, if you chose From and Equals, you might enter as the criteria. cPanel would determine that any email from matched the filter, but would not match because it contains additional letters.


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


When cPanel determines that an email message matches your filter, it will handle that message with the actions that you specify.

  • Discard Message — cPanel will discard the incoming message with no failure notice.
  • Redirect to email — cPanel will forward the message to another email address that you specify.
  • Fail with message — cPanel will discard the message and automatically send a failure notice to the sender.
  • Stop Processing Rules — cPanel will skip all filter rules.
  • Deliver to folder — cPanel will deliver the message to a specified folder.
  • Pipe to a program — cPanel will send the incoming message to a specified program. See the Pipe to a Program section below for more information.



Pipe to a Program

You can use the Pipe to a Program option to parse and enter email information into a different system. For example, you can 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.


Make sure 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 stands for your script’s location and file name.


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


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

To ensure that the script will function properly, the script must be executable and the appropriate hashbang line must exist at the top of the script.

  • If you use PHP, use the following hashbang line at the top of the script:
    #!/usr/local/bin/php -q
  • If you use Perl, use the following hashbang line at the top of the script:

If your script does not include a hashbang, enter the path to the Perl or PHP interpreter in the Pipe to a Program text box. Follow it with the full path to the script, as in the following examples:

/usr/local/bin/php /home/john/test.php
/usr/bin/perl /home/john/

Posted in: Webmail

Best Small Business Hosting Services. YOUR E-BUSINESS IS OUR JOB!
WordPress and WHMCS integration by i-Plugins