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.

SecurityBasicAuth

Request

query Parameters

required	string 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. Examples: Use multiple filter actions. action=action1=deliver action2=save Use a single filter action. action=deliver
filtername required	string The filter name. Example: filtername=coffee
required	string 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`. Examples: Use multiple match types. match=match1=contains match2=matches Use a single match type. match=contains
required	string 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. Examples: Query multiple email sections. part=part1=$header_from part2=$message_body Query a single email section. part=$header_from
required	string or integer The value to match. Important: You must increment each value. For example, pass the first value as `val1` and the second value as `val2`. Examples: Match multiple values. val=val1=coconut val2=12 Match a single value. val=coconut
account	string <email> The email address, for user-level filters. If you do not use this parameter, the function creates an account-level filter. Example: account=user@example.com
	string or string Default: "" 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`. Examples: Use multiple destinations for filtered mail. dest=dest1=user@example.com dest2=user2@example.com Use a single destination for filtered mail. dest=user@example.com
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: oldfiltername=pool
	string Default: "and" 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`. Examples: Use multiple connections between conditions. opt=opt1=and opt2=and Use a single connection between conditions. opt=and

Responses

200

HTTP Request was successful.

Response Schema: application/json

apiversion	integer The version of the API.
func	string The name of the method called.
module	string The name of the module called.
	object

get/Email/store_filter

Request samples

CLI
URL
LiveAPI Perl
LiveAPI PHP

uapi --output=jsonpretty \
  --user=username \
  Email \
  store_filter \
  filtername='coffee' \
  action*='deliver' \
  match*='contains' \
  part*='$header_from' \
  val*='coconut'

Response samples

application/json

{"apiversion": 3,
"func": "store_filter",
"module": "Email",
"result": {"data": {"account": "user@example.com"
},
"errors": null,
"messages": null,
"metadata": {"transformed": 1
},
"status": 1,
"warnings": null
}
}