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

 

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

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.
 
// List all of the filters for user@example.com.
$filter_list = $cpanel->uapi(
    'Email', 'list_filters',
    array(
        'account'     => 'user@example.com',
         )
);

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.
 
# List all of the filters for user@example.com.
my $filter_list = $cpliveapi->uapi(
    'Email', 'list_filters',
    {
        'account'     => 'user@example.com',
    }
);

Note:

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

 

 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 %]

Note:

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

 

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

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

   

Parameters

ParameterTypeDescriptionPossible valuesExample
accountstring

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

ReturnTypeDescriptionPossible valuesExample
actionsarray of hashesAn array that contains hashes of the filter's actions.This array's hashes include the dest and action returns. 

dest

string

The destination to which the filter sends mail.

The function returns this value in the actions 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 the actions hash.

  • 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.
 
filternamestringThe filter's name.The filtername input parameter's value.coffee
unescapedBoolean

Note:

We deprecated this parameter in cPanel & WHM version 11.

 

 
rulesarray of hashesAn 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 the rules hash.

  • $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 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 the rules 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 the rules hash.

A string value.coconut

opt

string

The connection between multiple conditions.

The function returns this value in the rules hash.

  • and — Match both conditions.
  • or — Match either condition.
  • null — Only one condition exists.
or