Run test for main domain email filters

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:

If the domain or account does not contain a filter file, this function will fail.

Important:

When you disable the Receive Mail role, the system disables this function.

Authorizations:
query Parameters
msg
required
string

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

Example: msg=Test
account
string <email>

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.

Example: account=user@example.com

Responses

Response Schema: application/json
apiversion
integer

The version of the API.

func
string

The name of the method called.

module
string

The name of the module called.

object

Request samples

uapi --output=jsonpretty \
  --user=username \
  Email \
  trace_filter \
  msg='Test'

Response samples

Content type
application/json
{
  • "apiversion": 3,
  • "func": "trace_filter",
  • "module": "Email",
  • "result": {
    • "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>"
      },
    • "errors": null,
    • "messages": null,
    • "metadata": { },
    • "status": 1,
    • "warnings": null
    }
}