Child pages
  • UAPI Functions - Email::store_filter

Versions Compared

Key

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

Description

Excerpt
This function creates a new email filter.

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

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
titlecPanel or Webmail Session URL


Code Block
languagetext
https://hostname.example.com:2083/cpsess##########/execute/Email/store_filter?filtername=coffee&account=user%40example.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:_CallUAPIFromBrowserLink
LIB:_CallUAPIFromBrowserLink


Expand
titleLiveAPI PHP Class


Code Block
languagephp
linenumberstrue
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Create a new filter for user@example.com.
$new_filter = $cpanel->uapi(
    'Email', 'store_filter',
    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 a new filter for user@example.com.
my $new_filter = $cpliveapi->uapi(
    'Email', 'store_filter',
    {
        '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 Template Toolkit


Code Block
languagexml
<!-- Create a new filter for user@example.com. -->
[% execute( 'Email', 'store_filter', { '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:_TTLink
LIB:_TTLink


Expand
titleCommand Line


Code Block
languagebash
uapi --user=username Email store_filter filtername=coffee account=user%40example.com action1=deliver dest1=cheesecloth%40example.com part1=\$header_subject: match1=contains val1=curds opt1=or part2=\$message_body match2=is val2=whey

Include Page
LIB:_UAPICLINote
LIB:_UAPICLINote


Expand
titleOutput (JSON)


Code Block
languagetext
linenumberstrue
{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": {
    "account": "user@example.com"
  }
  "metadata": {
    "transformed": 1
  }
}


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 name.

A string.

coffee
oldfilternamestring

The name of an existing filter, 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.

Warning
titleImportant:

You must increment each action. For example, pass the first action as action1 and the second action as action2.


  • 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.

This parameter defaults to an empty string.

Warning
titleImportant:
  • You must increment each destination. For example, pass the first destination as dest1 and the second destination as dest2.
  • This parameter is required if the action value is deliver, save, or pipe.


  • A file path.
  • An application path.
  • A valid email address.
cheesecloth@example.com
match*

string

or

integer

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.
Warning
titleImportant:

You must increment each match type. For example, pass the first match type as match1 and the second match type as match2.


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.

This parameter defaults to and.

Warning
titleImportant:

You must increment each connection. For example, pass the first connection as opt1 and the second connection as opt2.


  • and
  • or
and
part*string

Required

The email section to query.

Warning
titleImportant:

You must increment each section. For example, pass the first section as part1 and the second section as part2.


  • $h_x-Spam-Bar — Match against the message's spam score value, measured in plus (+) characters.
  • $h_x-Spam-Score — Match against the message's spam score value.
  • $h_X-Spam-Status — Match against whether the system detected the message as spam.
  • $h_List-Id — Match against the message's List-ID header value.
  • $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.

Warning
titleImportant:

You must increment each value. For example, pass the first value as val1 and the second value as val2.


  • 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
accountstring

The filter's email address.

The function only returns this value if it created a user-level filter.

The account input return's value.user@example.com