cPanel API 2 Functions - Email::filterlist - Knowledgebase

Description

This function lists mail filters.

Warning:

We strongly recommend that you use UAPI instead of cPanel API 2. However, no equivalent UAPI function exists.

Note:

We deprecated this function in cPanel & WHM version 11.

WHM API (JSON)

https://hostname.example.com:2087/cpsess##########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=filterlist&account=user@example.com

LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
  
// List filters for user@example.com.
$filter_list = $cpanel->api2(
    'Email', 'filterlist', 
    array(
        'account'      => 'user@example.com',
    ) 
);

LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# List filters for user@example.com.

my $filter_list = $cpliveapi->api2(

'Email', 'filterlist',

{

'account' => 'user@example.com',

}

);

cPanel Tag System (deprecated)

Warning:

In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs.

cPanel API 2 calls that use cPanel tags vary widely in code syntax and in their output. For more information, read our Deprecated cPanel Tag Usage documentation. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.

Command Line

cpapi2 --user=username Email filterlist account=user%40example.com

Notes:

You must URI-encode values.
username represents your account-level username.

 Output (JSON)

{
  "cpanelresult": {
    "apiversion": 2,
    "func": "filterlist",
    "data": [
      {
        "actions": [
          {
            "dest": "/dev/null",
            "action": "save"
          }
        ],
        "filtername": "coffee",
        "unescaped": "1",
        "rules": [
          {
            "match": "is",
            "part": "$header_from:",
            "opt": "or",
            "val": "user@example.com"
          }
        ],
        "enabled": 1
      },
      {
        "filtername": "myfilter",
        "actions": [
          {
            "dest": "filteredmsgs@example.com",
            "action": "deliver"
          }
        ],
        "unescaped": 1,
        "rules": [
          {
            "match": "contains",
            "part": "$message_body",
            "opt": null,
            "val": "test"
          }
        ],
        "enabled": 1
      }
    ],
    "event": {
      "result": 1
    },
    "module": "Email"
  }
}

Note:

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

Parameter	Type	Description	Possible values	Example
account	string	The cPanel account name or email address, to limit results to that account's user-level filters. If you do not use this parameter, the function returns account-level filters.	The cPanel username. A user-level filter's email address.	user

Parameter

Type

Description

Possible values

Example

account

string

The cPanel account name or email address, to limit results to that account's user-level filters.

If you do not use this parameter, the function returns account-level filters.

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

user

Return	Type	Description	Possible values	Example
actions	array of hashes	An array of hashes of the filter's actions.	Each hash includes the dest andaction returns.
dest	string	The destination to which the filter sends mail. The function returns this value in theactions array.	A file path. An application path. A valid email address.	filteredmsgs@example.com
action	string	The filter's action. The function returns this value in theactions array.	deliver — The filter sends mail to the dest address. fail — The filter forces a delivery failure. finish — The filter stops message processing. save — The filter saves mail to the dest file. pipe — The filter sends mail to the dest application.	deliver
filtername	string	The filter name.	A string value.	coffee
unescaped	Boolean	A legacy Boolean value.	1 0	1
rules	array of hashes	An array of hashes of the filter's rules.	Each hash includes the match, part,opt, and val returns.
match	string	The filter's match type. The function returns this value in the rulesarray.	is matches contains does not contain begins does not begin ends does not end does not match is above is not above is below is not below	contains
part	string	The queried email section. The function returns this value in the rulesarray.	$header_from: — Matches against the From: section. $header_subject: — Matches against the Subject: section. $header_to: — Matches against the To: section. $reply_address: — Matches against the Reply To: section. $message_body — Matches against the message's body. $message_headers — Matches against the message's headers. foranyaddress $h_to:,$h_cc:,$h_bcc: — Matches against all message recipients. not delivered — Matches if the message is not queued for delivery. error_message — Matches if the incoming message bounced.	$message_body
opt	string	The connection between multiple conditions. The function returns this value in the rulesarray.	and — Match both conditions. or — Match either condition. null — Only one condition exists.	and
val	string	The matched value. The function returns this value in the rulesarray.	A string value.	coconut
enabled	Boolean	Whether the filter is currently enabled.	1 — Enabled. 0 — Disabled.	1
reason	string	A reason for failure. Note: This functiononly returns areason value if it failed.	A string that describes the error.	This is an error message.
result	Boolean	Whether the function succeeded.	1 — The function succeeded. 0 — The function failed.	1

Knowledgebase

Categories

Categories