cPanel API 2 Functions - Email::loadfilter - Knowledgebase

Description

This function retrieves an email filter's information. For more information about Exim filters, read Exim's documentation.

Warning:

We strongly recommend that you use the following UAPI function instead of this function:

Email::get_filter — This function retrieves an email filter's information.

Examples

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=loadfilter&filtername=

 LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
  
// List information for the "coffee" mail filter.
$filter_info = $cpanel->api2(
    'Email', 'loadfilter', 
    array(
        'filtername'      => 'coffee',
    ) 
);

 LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# List information for the "coffee" mail filter.
my $filter_info = $cpliveapi->api2(
    'Email', 'loadfilter',
    {
        'filtername'      => 'coffee',
    }
);

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.

 Output (JSON)

{
  "cpanelresult": {
    "apiversion": 2,
    "func": "loadfilter",
    "data": [
      {
        "filtername": "coffee",
        "actions": [
          {
            "dest": "\/dev\/null",
            "number": 1,
            "action": "save"
          }
        ],
        "rules": [
          {
            "number": 1,
            "match": "is",
            "part": "$header_from:",
            "opt": "or",
            "val": "user@example.com"
          }
        ]
      }
    ],
    "event": {
      "result": 1
    },
    "module": "Email"
  }
}

Note:

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

Parameters

Parameter	Type	Description	Possible values	Example
filtername	string	Required The filter's name.	A string value.	coffee
account	string	The cPanel account name or email address, to retrieve a user-level filter. If you do not use this parameter, the function retrieves an account-level filter.	The cPanel username. A user-level filter's email address.	user

Parameter

Type

Description

Possible values

Example

filtername

string

Required

The filter's name.

A string value.

coffee

account

string

The cPanel account name or email address, to retrieve a user-level filter.

If you do not use this parameter, the function retrieves an account-level filter.

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

user

Returns

Return	Type	Description	Possible values	Example
filtername	string	The filter name.	A string value.	coffee
actions	hash	A hash of the filter's actions.	This hash includes the dest, number, and action parameters.
dest	string	The destination to which the filter sends mail. The function returns this parameter in theactions hash.	A file path. An application path. A valid email address.	filteredmsgs@example.com
number	integer	The rule's order in the list. The function returns this parameter in theactions hash.	A positive integer that represents the rule's order in the filter. For example, the filter's first rule returns 1.	1
action	string	The filter's action. The function returns this parameter in theactions 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 thedest file. pipe — The filter sends mail to the dest application.	deliver
rules	hash	A hash of the filter's rules.	This hash includes the number,match, part, opt, and valparameters.
number	integer	The rule's order in the list. The function returns this parameter in therules hash.	A positive integer that represents the rule's order in the filter. For example, the filter's first rule returns 1.	1
match	string	The filter's match type. The function returns this parameter 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
part	string	The queried email section. The function returns this parameter in therules 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 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 parameter in therules hash.	and — Match both conditions. or — Match either condition. null — There is only one condition.	and
val	string	The matched value. The function returns this parameter in therules hash.	A string value.	coconut
reason	string	A reason for failure. Note: This function only 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