Create filter

Create a sieve (message) filter

  • HTTP Method: POST
  • URL: https://example.domain.tld/api/v1/sieve_filters/
  • Require authentication: Yes
  • Permission level required: MailUser

Request parameters

Parameter Type Description Required
filter_position int Filters are processed sequentially in order 1 to 99 Required
filter_name str Friendly name (identifier) for filter Required
match_type str all_rules / any_rule / all_messages Required
rules list List of rules to be matched Required if match_type is not all_messages
search_property str Size OR any header like Subject / From / To / Cc / X-Spam Required
search_type str contains / does_not_contain / is / is_not OR greater_than / less_than for search_property : Size Required
search_term str/int Search term as string; integer (KB) for search_property : Size Required
actions list List of actions to be carried out Required
perform_action str move / copy / keep / forward / keep_and_forward / reject / discard / stop Required
action_arg str Action argument; mailbox folder name for move / copy, email address for forward / keep_and_forward, reject reason for reject, empty string for others Required

Tip

Mailbox folder will be created if it does not exist.

Mailbox folder name for subfolders can be specified using the dot notation like Inbox.Personal. This specifies a subfolder Personal under Inbox.

Forwards are limited to a maximum of 4 per MailUser.

Response parameters

Parameter Type Description
filter_position int Filter position from 1 to 99
filter_name str Friendly name (identifier) of filter
match_type str all_rules / any_rule / all_messages
rules list List of rules to be matched
search_property str Size OR any header like Subject / From / To / Cc / X-Spam
search_type str contains / does_not_contain / is / is_not OR greater_than / less_than for search_property : Size
search_term str/int Search term as string; integer (KB) for search_property : Size
actions list List of actions to be carried out
perform_action str move / copy / keep / forward / keep_and_forward / reject / discard / stop
action_arg str Action argument; mailbox folder name for move / copy, email address for forward / keep_and_forward, reject reason for reject, empty string for others
status str Status

Example request (Python)

import requests
import json
from pprint import pprint

url = "https://example.domain.tld/api/v1/sieve_filters/"
data = {
"filter_position" : 1,
"filter_name" : "My filter 1",
"match_type" : "any_rule",
"rules" : [
    {
        "search_property" : "Subject",
        "search_type" : "contains",
        "search_term" : "jackpot"
    }
],
"actions" : [
    {
        "perform_action" : "reject",
        "action_arg" : "This message seems like spam and I refuse to accept it."
    }
]
}
r = requests.post(url, json=data, auth=("u1@vonmail.com","long-auth_token-here"))
try:
    pprint(r.json())
except: 
    print(r.text)

Example response (JSON)

{'actions': '[{"action_arg": "This message seems like spam and I refuse to '
           'accept it.", "perform_action": "reject"}]',
 'filter_name': 'My filter 1',
 'filter_position': 1,
 'match_type': 'any_rule',
 'rules': '[{"search_property": "Subject", "search_type": "contains", '
          '"search_term": "jackpot"}]',
 'status': 'generating'}