Child pages
  • UAPI Functions - Email::store_filter
Skip to end of metadata
Go to start of metadata

Description

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

Important:

In cPanel & WHM version 76 and later, when you disable the MailReceive role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Examples 


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


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

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


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


Note:

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

 cPanel Template Toolkit
<!-- 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', } ) %]


Note:

For more information, read our Guide to Template Toolkit documentation. 

 Command Line
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


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": {
    "account": "user@example.com"
  }
  "metadata": {
    "transformed": 1
  }
}


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.

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.

Important:

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.

Important:

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

Important:

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.

Important:

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.

Important:

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.

    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.

Important:

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

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