UAPI Functions - Email::list_filters - Knowledgebase

Description

This function lists account-level mail filters. For more information about Exim filters, read Exim's documentation.

Examples

cPanel or Webmail Session URL

https://hostname.example.com:2083/cpsess##########/execute/Email/list_filters?account=user%40example.com

 LiveAPI PHP Class

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

 LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# List all of the filters for user@example.com.
my $filter_list = $cpliveapi->uapi(
    'Email', 'list_filters',
    {
        'account'     => 'user@example.com',
    }
);

 cPanel Template Toolkit

<!-- Get a hash of data, then display the filter name for each filter. -->
[% data = execute( 'Email', 'list_filters', { 'account' => 'user@example.com', } ); %]
[% FOREACH q = data.filtername %]
     <p>
         [% q %]
     </p>
[% END %]
   
<!-- Get only the filter names. -->
[% execute( 'Email', 'list_filters', { 'account' => 'user@example.com', } ).data.filtername %]

Command Line

uapi --user=username Email list_filters account=user%40example.com

Notes:

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

 Output (JSON)

{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": {
    "actions": [
      {
        "dest": "/dev/null",
        "action": "save"
      }
    ],
    "filtername": "FilterTest",
    "unescaped": 1,
    "rules": [
      {
        "part": "$header_from:",
        "match": "contains",
        "val": "example.com",
        "opt": "or"
      }
  "metadata": {
    "transformed": 1
  }
}

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 or cPanel account username for which to return a list of filters. If you do not specify this value, the function lists all of the cPanel account's account-level filters.	A valid email address on the cPanel account to return that email address's user-level filters. The cPanel account username to return all of the account's default email address's user-level filters.	user@example.com

Parameter

Type

Description

Possible values

Example

account

string

The email address or cPanel account username for which to return a list of filters.

If you do not specify this value, the function lists all of the cPanel account's account-level filters.

A valid email address on the cPanel account to return that email address's user-level filters.
The cPanel account username to return all of the account's default email address's user-level filters.

user@example.com

Returns

Return	Type	Description	Possible values	Example
actions	array of hashes	An array that contains hashes of the filter's actions.	This array's hashes include the dest and actionreturns.
dest	string	The destination to which the filter sends mail. The function returns this value in theactions hash.	A file path. An application path. A valid email address.	/dev/null
action	string	The filter's action. The function returns this value in theactions hash.	deliver — The filter sends mail to the destaddress. 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 destapplication.
filtername	string	The filter's name.	The filtername input parameter's value.	coffee
unescaped	Boolean	Note: We deprecated this parameter in cPanel & WHM version 11.
rules	array of hashes	An array that contains hashes of the filter's rules.	This array's hashes include the match, part, opt, and val returns.
part	string	The queried email section. The function returns this value in therules hash.	$header_from: — Matches against the From:section. $header_subject: — Matches against theSubject: section. $header_to: — Matches against the To:section. $reply_address: — Matches against theReply 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 system has not queued the message for delivery. error_message — Matches if the incoming message bounced.	$message_body
match	string	The filter's match type. The function returns this value in therules hash.	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
val	string	The matched value. The function returns this value in therules hash.	A string value.	coconut
opt	string	The connection between multiple conditions. The function returns this value in therules hash.	and — Match both conditions. or — Match either condition. null — Only one condition exists.	or

Knowledgebase

Categories

Categories