Description

This function tests mail filters.

 The function only tests filters for the cPanel account's main domain, and only tests against the message's body.

For more information about Exim filters, read Exim's documentation.

We strongly recommend that you use the following UAPI function instead of this function:


In cPanel & WHM version 11.50 and later, if the domain or account does not contain a filter file, this function will fail.

Examples 




https://hostname.example.com:2087/cpsess##########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=tracefilter&filtername="coffee"



$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Test a filter.
$test_filter = $cpanel->api2(
    'Email', 'tracefilter', 
    array(
        'filtername'      => 'coffee',
    ) 
);



my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Test an email filter.
my $test_filter = $cpliveapi->api2(
    'Email', 'tracefilter',
    { 
        'filtername'      => 'coffee',
    }
);




cpapi2 --user=username Email tracefilter filtername=coffee



{
  "cpanelresult": {
    "apiversion": 2,
    "func": "tracefilter",
    "data": [
      {
        "trace": "Warning: no message headers read\nReturn-path copied from sender\nSender      = user@example.com\nRecipient   = user@example.com\nTesting Exim filter file &quot;/etc/vfilters/example.com&quot;\n\nFiltering set up at least one significant delivery.\n<b>No other deliveries will occur.\n<\/b>"
      }
    ],
    "event": {
      "result": 1
    },
    "module": "Email"
  }
}



Parameters

ParameterTypeDescriptionPossible valuesExample
accountstring

The cPanel account name or email address, to test a user-level filter.

If you do not use this parameter, the function tests an account-level filter.

  • The cPanel username.
  • A user-level filter's email address.
user
filternamestring

Required

The filter name.

The name of a filter on the account.

coffee

Returns

ReturnTypeDescriptionPossible valuesExample
tracestringA series of messages that describe the trace results.

A series of strings.

This output may contain HTML. 



Warning: no message headers read\nReturn-path copied from sender\nSender      = user@example.com\nRecipient   = user@example.com\nTesting Exim filter file &quot;/etc/vfilters/example.com&quot;\n\nFiltering did not set up a significant delivery.\n<b>Normal delivery will occur.\n</b>


reasonstring

A reason for failure.

This function only returns a reason value if it failed. 


A string that describes the error.

This is an error message.
resultBoolean

Whether the function succeeded.

  • 1 — The function succeeded.
  • 0 — The function failed.
1