Page tree
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.

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. 
  • We introduced this functionality in cPanel & WHM version 56.

 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

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.

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