UAPI Functions - Email::trace_filter - Knowledgebase

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

 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',
         )
);

 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',
    }
);

cPanel Template Toolkit

[% execute( 'Email', 'trace_filter', { 'account' => 'user@example.com', 'msg' => 'Test', } ) %]

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.

 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 (Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

Parameter	Type	Description	Possible values	Example
account	string	The email address, to test legacy cPanel filters in the filtersdirectory. 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
msg	string	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

Parameter

Type

Description

Possible values

Example

account

string

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

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

msg

string

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

Return	Type	Description	Possible values
trace	string	A series of messages that describe the trace results.	A series of strings. Note: This output may contain HTML.

Return

Type

Description

Possible values

trace

string

A series of messages that describe the trace results.

A series of strings.

Note:

This output may contain HTML.

Knowledgebase

Categories

Categories