cPanel API 2 Functions - Email::storefilter

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

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

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

 cPanel Tag System (deprecated)

Warning:

In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that youonly 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.

 

 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

 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 (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 thedest* application.

 deliver

 dest*

 string

 The destination for filtered mail.

 Note:

 You must use this parameter if the actionvalue isdeliver, 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 BCCfield in an email's header. For this reason, you cannot use the BCCfield 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 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

 

 

 

 
  • 7 Users Found This Useful
Was this answer helpful?

Related Articles

The cPanel Interface

For  cPanel  &  WHM  version  58 Overview The cPanel interface is...

User Preferences

For cPanel & WHM version 58 Overview This document outlines how to access your cPanel...

Manage External Authentications

For cPanel & WHM version 58 Overview Manage credentials Additional documentation...

What is cPanelID?

In This Article:  Overview ServicesHow to get a cPanelID cPanelID External...

Guide to cPanel Interface Customization - cPanel Style Development

Introduction You can develop custom styles that modify the appearance of the cPanel interface....