Description

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

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


Examples 




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



$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', 
    ) 
);



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', 
    }
);




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



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



Parameters

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


ParameterTypeDescriptionPossible valuesExample
accountstring

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
filternamestring

Required

The filter's name.

A string.

coffee
oldfilternamestring

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.

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.
      
  • 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 action1dest1match1opt1part1, and val1 parameters.
  • Assign the information for the second filter rule to the action2dest2match2opt2part2, 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 match1opt1part1, and val1 parameters.
  • Assign the second set of conditions to the match2opt2part2, and val2 parameters.

Returns

ReturnTypeDescriptionPossible valuesExample
okBooleanWhether the function succeeded.
  • 1 — The function succeeded.
  • 0 — The function failed.
1
accountstringThe 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
errorBooleanWhether the function encountered an error.
  • 1 — Errors.
  • 0No errors.
0
resultstringA message of success or a reason for failure.
  • Filter Saved. — The function succeeded.
  • An error message. — The function failed.
Filter Saved.
reasonstring

A reason for failure.

This function only returns a reason value if it failed. 


A string that describes the error.

This is an error message.
resultBoolean

Whether the function succeeded.

  • 1 — The function succeeded.
  • 0 — The function failed.
1