# Create email filter

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

Important:

When you disable the Receive Mail role, the system disables this function.

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

Endpoint: GET /Email/store_filter
Version: 11.136.0.19
Security: BasicAuth

## Query parameters:

  - `action*` (any, 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.

Important:

* You must increment each action. For example, pass the first action as action1 and the second action as action2.
* This value requires the FileStorage role. For more information, read our How to Use Server Profiles documentation.

  - `filtername` (string, required)
    The filter name.
    Example: "coffee"

  - `match*` (any, 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

Important:

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

  - `part*` (any, required)
    The email section to query.

 * $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.
 * not delivered - Match if the message is not queued for delivery.
 * error_message - Match if the incoming message is bounced.

Important:

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

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.

  - `val*` (any, 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.

  - `account` (string)
    The email address, for user-level filters. If you do not use this parameter, the function creates an account-level filter.
    Example: "user@example.com"

  - `dest*` (any)
    The destination for filtered mail.

Important:

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

  - `oldfiltername` (string)
    The name of an existing filter, to rename it. If you do not use this parameter, the function creates a new filter.
    Example: "pool"

  - `opt*` (any)
    The connection between multiple conditions.

Important:

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

## Response 200 fields (application/json):

  - `apiversion` (integer)
    The version of the API.
    Example: 3

  - `func` (string)
    The name of the method called.
    Example: "store_filter"

  - `module` (string)
    The name of the module called.
    Example: "Email"

  - `result` (object)

  - `result.data` (object)

  - `result.data.account` (string)
    The filter's email address. The function only returns this value if it created a user-level filter.
    Example: "user@example.com"

  - `result.errors` (array,null)
    List of errors if the API failed.

  - `result.messages` (array,null)
    List of messages generated by the API.

  - `result.metadata` (object)

  - `result.metadata.transformed` (integer)
    Post-processing may have transformed the data.
    Enum: 1

  - `result.status` (integer)
    * 1 - Success
* 0 - Failed. Check the errors field for more details.
    Enum: 0, 1

  - `result.warnings` (array,null)
    List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running a API.