Page tree
Skip to end of metadata
Go to start of metadata

 

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.

Note:

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


Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Email/trace_filter?account=user%40example.com&msg=Test

Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Check whether user@example.com's filters are functional.
test_filter = $cpanel->uapi(
    'Email', 'trace_filter',
    array(
        'account'   => 'user@example.com',
        'msg'       => 'Test',
         )
);

Note:

For more information, read our Guide to the LiveAPI System.

 

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Check whether user@example.com's filters are functional.
my test_filter = $cpliveapi->uapi(
    'Email', 'trace_filter',
    {
        'account'   => 'user@example.com',
        'msg'       => 'Test',
    }
);

Note:

For more information, read our Guide to the LiveAPI System.

 

 cPanel Template Toolkit
<!-- Check whether user@example.com's filters are functional. -->
[% execute( 'Email', 'trace_filter', { 'account' => 'user@example.com', 'msg' => 'Test', } ) %]

Note:

For more information, read our Guide to Template Toolkit documentation. 

 

 Command Line
uapi --user=username Email trace_filter account=user%40example.com msg=Test

Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • We introduced this functionality in cPanel & WHM version 56.

 Output (JSON)
{  
   "messages":null,
   "errors":null,
   "status":1,
   "metadata":{  
   },
   "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 did not set up a significant delivery.\n<b>Normal delivery will occur.\n</b>"
   }
}

Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

   

Parameters

ParameterTypeDescriptionPossible valuesExample
accountstring

The email address, to test legacy cPanel filters in the filters directory.

If you do not use this parameter, the function tests the main domain's filters in the /etc/vfilters directory.

A valid email address on the account.

user@example.com
msgstring

Required

The string to test.

The function uses this string as the body of an email message, to check whether filters would match the string.

A string.

Test

Returns

ReturnTypeDescriptionPossible valuesExample
tracestring

A series of messages that describe the trace results.

A series of strings.

Note:

This output may contain HTML. 

 Click to view...
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>