Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Description

Excerpt
This function creates an email filter.

 For more information about Exim filters, read Exim's documentation.

Warning
titleWarning:

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

  • Email::store_filter

    Excerpt Include
    DD:UAPI Functions - Email::store_filter
    DD:UAPI Functions - Email::store_filter
    nopaneltrue

Multiexcerpt include
SpaceWithExcerptcom.atlassian.confluence.content.render.xhtml.model.resource.identifiers.SpaceResourceIdentifier@12665
MultiExcerptNameAPIDisabledReceiveMailRole
PageWithExcerptLIB:_ServerRoleDisabledAPI

Panel
bgColor#F2F2F2
borderStylenone

Examples 


Panel
bgColor#FFFFFF
borderStylenone


Expand
titleWHM API (JSON)


Code Block
languagetext
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

Include Page
LIB:_CallFromWHMAPILink
LIB:_CallFromWHMAPILink


Expand
titleLiveAPI PHP Class


Code Block
languagephp
linenumberstrue
$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', 
    ) 
);

Include Page
LIB:_LiveAPIPHPLink
LIB:_LiveAPIPHPLink


Expand
titleLiveAPI Perl Module


Code Block
languageperl
linenumberstrue
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', 
    }
);

Include Page
LIB:_LiveAPIPerlLink
LIB:_LiveAPIPerlLink


Expand
titlecPanel Tag System (deprecated)

Include Page
LIB:_cPanelAPI2cPanelTagsWarning
LIB:_cPanelAPI2cPanelTagsWarning


Expand
titleCommand Line


Code Block
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

Include Page
LIB:_cPanelAPI2CLINote
LIB:_cPanelAPI2CLINote


Expand
titleOutput (JSON)


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


Include Page
LIB:_cPanelAPIShellNote
LIB:_cPanelAPIShellNote


Parameters

Warning
titleImportant:

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.

Note
titleNote:

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.
    Include Page
    LIB:_BCCNote
    LIB:_BCCNote
      
  • 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

Anchor
multirule
multirule
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.

Note
titleNote:

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