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.
Authorizations:
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:
action*=action1=deliver action2=save
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:
match*=match1=contains match2=matches
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:
part*=part1=$header_from part2=$message_body
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:
val*=val1=coconut val2=12
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:
dest*=dest1=user@example.com dest2=user2@example.com
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:
opt*=opt1=and opt2=and
opt*=and

Responses

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

Request samples

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

Response samples

Content type
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
    }
}