cPanel API 2 Functions - Email::storefilter

Warning:

The cPanel API 2 system is deprecated. We strongly recommend that you use UAPI instead of cPanel API 2.

Description

This function creates an email filter.

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::store_filter — This function creates a new email filter.

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=storefilter&filtername=coffee&account=user@example.com&action1=deliver&dest1=cheesecloth%40example.com&part1=%24header_subject%3A&match1=contains&val1=curds&opt1=or&part2=%24message_body&match2=is&val2=whey

Note:

For more information, read our Calls from the WHM API documentation.

LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.

// Create an email filter.
$create_mail_filter = $cpanel->api2(
    'Email', 'storefilter',
    array(
        'filtername'      => 'coffee',
        'account'         => 'user@example.com',
        'action1'         => 'deliver',
        'dest1'           => 'cheesecloth@example.com',
        'part1'           => '$header_subject:',
        'match1'          => 'contains',
        'val1'            => 'curds',
        'opt1'            => 'or',
        'part2'           => '$message_body',
        'match2'          => 'is',
        'val2'            => 'whey',
    )
);

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.

# Create an email filter.
my $create_mail_filter = $cpliveapi->api2(
    'Email', 'storefilter',
    {
        'filtername'      => 'coffee',
        'account'         => 'user@example.com',
        'action1'         => 'deliver',
        'dest1'           => 'cheesecloth@example.com',
        'part1'           => '$header_subject:',
        'match1'          => 'contains',
        'val1'            => 'curds',
        'opt1'            => 'or',
        'part2'           => '$message_body',
        'match2'          => 'is',
        'val2'            => 'whey',
    }
);

Note:

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

cPanel Tag System (deprecated)

Warnings:

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

Command Line

cpapi2 --user=username Email storefilter filtername=coffee account=user%40example.com action1=deliver dest1=cheesecloth@example.com part1=$header_subject: match1=contains val1=curds opt1=or part2=$message_body match2=is val2=whey

Notes:

You must URI-encode values.
username represents your account-level username.
You must run the --user=username command.
For more information and additional output options, read our Guide to cPanel API 2 documentation or run the cpapi2 --help command.
If you run CloudLinux™, you must use the full path of the cpapi2 command:
```
/usr/local/cpanel/bin/cpapi2
```

Output (JSON)

{
  "cpanelresult": {
    "apiversion": 2,
    "func": "storefilter",
    "data": [
      {
        "ok": 1,
        "account": "user@example.com",
        "error": 0,
        "result": "Filter Saved."
      }
    ],
    "event": {
      "result": 1
    },
    "module": "Email"
  }
}

Note:

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

Parameters

Important:

For additional use information, read the Create multiple rules section.

Parameter	Type	Description	Possible values	Example
`account`	string	The email address, for user-level filters. If you do not use this parameter, the function creates an account-level filter.	A valid email address on the account.	`user@example.com`
`filtername`	string	Required The filter's name.	A string.	`coffee`
`oldfiltername`	string	An existing filter's name, to rename it. If you do not use this parameter, the function creates a new filter.	A filter on the account.	`pool`
`action*`	string	Required The filter's action.	`deliver` — Deliver the message to the `dest` address. `fail` — Force a delivery failure. `finish` — Stop processing the message. `save` — Save the message to the `dest` file. `pipe` — Pipe the message to the `dest*` application.	`deliver`
`dest*`	string	The destination for filtered mail. Note: You must use this parameter if the `action` value is `deliver`, `save`, or `pipe`.	A file path. An application path. A valid email address.	`cheesecloth@example.com`
`match*`	string	Required The filter's match type. If the `val` parameter is a string, use a string operator. If the `val` parameter is an integer, use a numeric operator.	String operators: `is` `matches` `contains` `does not contain` `begins` `does not begin` `ends` `does not end` `does not match` Numeric operators: `is above` `is not above` `is below` `is not below`	`contains`
`opt*`	string	The connection between multiple conditions.	`and` `or`	`and`
`part*`	string	Required The email section to query.	`$header_from:` — Match against the `From:` section. `$header_subject:` — Match against the `Subject:` section. `$header_to:` — Match against the `To:` section. `$reply_address:` — Match against the `Reply To:` section. `$message_body` — Match against the message's body. `$message_headers` — Match against the message's headers. `foranyaddress $h_to:,$h_cc:` — Match against all message recipients. Note: Generally, the recipient does not receive the `BCC` field in an email's header. For this reason, you cannot use the `BCC` field in a filter. `not delivered` — Match if the message is not queued for delivery. `error_message` — Match if the incoming message bounced.	`$message_body`
`val*`	string or integer	Required The value to match.	Any string value. A positive integer.	`coconut`

Create multiple rules

You may create up to 4,096 separate sets of conditions in one filter. To do this, append numbers to the parameter names.

To create a filter with two sets of actions and conditions, use the following parameters:

Assign the information for the first filter rule to the action1 , dest1 , match1 , opt1 , part1 , and val1 parameters.
Assign the information for the second filter rule to the action2 , dest2 , match2 , opt2 , part2 , and val2 parameters.

To create a filter that uses one set of actions but two sets of conditions, use the following parameters:

Assign the actions to the action1 and dest1 parameters.
Assign the first set of conditions to the match1 , opt1 , part1 , and val1 parameters.
Assign the second set of conditions to the match2 , opt2 , part2 , and val2 parameters.

Returns

Return	Type	Description	Possible values	Example
`ok`	Boolean	Whether the function succeeded.	`1` — The function succeeded. `0` — The function failed.	`1`
`account`	string	The email address or cPanel account to which the filter applies.	An email address, for account-level filters. The cPanel username, for user-level filters.	`user@example.com`
`error`	Boolean	Whether the function encountered an error.	`1` — Errors. `0` — No errors.	`0`
`result`	string	A message of success or a reason for failure.	`Filter Saved.` — The function succeeded. An error message. — The function failed.	`Filter Saved.`
`reason`	string	A reason for failure. Note: This function only returns a `reason` 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`