HTTP API MailFilter
Introduction
This document describes only the mail filter HTTP-API. So it's only a part which must be embedded into something which counts for login/logout, session handling and low-level protocol issues such as error handling. At the moment this will be the groupware server. So the modules needed for basic operations can be found there.
Module mailfilter
This module is used to access all mail filter related options.
First of all the main structure of a mail filter script is, that it has different rules. Each of them contains one command. This command takes a test condition which executes the actions given in that command if the test condition is true.
The test condition consists of a test command and some arguments for this command depending on the command itself. Because the available tests depend on the mail filter server, these tests must be determined at runtime. So that no test field is transferred to the server which it isn't able to handle. Examples for tests are address, allof and anyof.
Each test has a special comparison. The list of available comparisons depends on the test given and the mail filter server configuration so they have to be determined at runtime too.
Each time you want to do some action on a mail you need a so called action command. This describes what to do with a mail. To action commands the same applies as to the test commands and their comparison types, they must be determined at runtime.
All those dynamical values can be fetched via a config object at startup. This object shows the capabilities of the server to the client. This allows the client to show only the capabilities the server actually has to the user and to send only objects to the server which produce no errors on the server side.
To deal with this high flexibility of mail filters this specification can be roughly divided into 2 parts. A non-changing core and dynamical extensions. The core specification is that each rule consists of a name, an ID, a value showing if this rule is active or not and a tag which can be set on a rule to mark that rule for a special purpose. Furthermore each rule takes a test object, specifying in what case the following actions are triggered, and one or many actioncommands, specifying the actions itself. For a detailed specification see Table 1.
The objects for the tests and the actions are dynamical, so the set presented in this specification may be changed over the time, but only compatible changes are allowed to the objects, otherwise new test or action objects have to be introduced. Due to the fact that not every sieve implementation will offer all the capabilities written in this document, the server will sent his configuration if a special request is made. This configuration will show which of the tests and which of the actions are allowed. So for example if the server signals that it is capable of handling vacation, sending a vacation object as action is safe.
Furthermore some tests use a comparison field as stated above which specifies how the fields are compared. The values of this field must also be determined at runtime. So in the configuration object there is a special part which shows the comparisons which are available. Note that not all comparisons can be used with every test. Some of them are denoted to a special test, which can be found in the Table 3.
The core
As written in the introduction the main part of a mail filter are the rules. A rule object will always have the structure you can see in the table below (#Table 1). The dynamical parts are the test, which are represented by different options, see 4.1. Tests, and the actions, also represented in 4.2. Actions. Note that the test and actioncmds fields and the text and errormsg fields are mutual exclusive. So if test and actioncmds fields are filled the text and errormsg fields are not present and vice versa.
| id | Integer | A unique identifier (once created must not be changed) | |
| position | Integer | The position inside the mail filter list. Starts with 0 | |
| rulename | String | A name describing the rule, can be empty but must not contain a line break | |
| active | Boolean | If this rule is active or not | |
| flags | Array | A string array containing flags which are set on this rule. Each flag can only contain the following characters: 1-9 a-z A-Z. Currently 2 flags are reserved here: "spam" which marks the default spam rule and "vacation" which marks the vacation rules. | |
| test | Object | The structure of the different test objects can be found in section 4.1. Tests. The valid tests in the current setup can be found in the configuration object | |
| actioncmds | Array | An array of action objects whose different structures can be found in section 4.2. Actions. The action commands which are valid here can be determined through the config object see Table 24 | |
| text | String | If this rule cannot be read in this string is filled containing the whole lines of this command. | |
| errormsg | String | If this rule cannot be read in this string is filled containing a message why, or what part of the rule isn't known |
The dynamical part
Tests
In this section you will find the structures of all test commands which are specified until now. First a complete list of all test commands is given with a short description of them, afterwards a complete list of all comparison as they belong to the test section. Finally the different objects for those test commands are specified.
| address | This test type applies to addresses only. So it may be used for all header fields which contain addresses. This test returns true if any combination of the header-list and values-list arguments match. |
| envelope | This test applies to the envelope of a mail. This test isn't used under normal circumstances as the envelope isn't accessible in all mail setups. This test returns true if any combination of the header-list and values-list arguments match. |
| true | A test for a true result (can be used if an action command should be executed every time). |
| not | Negates a given test. |
| size | Deals with the size of the mail. |
| header | Tests against all headers of a mail. So with this test in contrast to the address test also fields such as subject can be handled. This test returns true if any combination of the header-list and values-list arguments match. |
| body | Tests against the content of a mail. |
| allof | Defines an AND condition between several tests. |
| anyof | Defines an OR condition between several tests. |
| is | If a field is equal to a given value |
| contains | If a field contains a given value at any position |
| matches | Tests if the value matches the value in the specified field. Here some wild cards can be used. "*" matches zero or more characters, and "?" matches a single character. To use the characters themselves they have to be escaped via a backslash. |
| regex | Tests if a given regular expression matches with the value present in the specified field. |
| user | Tests if the user part of an e-mail address is the value given here. This means in herbert+mustermann@example.com. The user checks the part herbert.
Attention: This comparison can only be used in conjunction with the address test |
| detail | Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann.
Attention: This comparison can only be used in conjunction with the address test |
| id | String | address | A string describing the test command. |
| comparison | String | Available types can be found in the config object. (see Table 25). | |
| headers | Array | A string array containing the header fields | |
| values | Array | A string array containing the value for the header fields |
| id | String | envelope | A string describing the test command. |
| comparison | String | Available types can be found in the config object. (see Table 25). | |
| headers | Array | A string array containing the header fields | |
| values | Array | A string array containing the value for the header fields |
| id | String | true | A string describing the test command. |
| id | String | not | A string describing the test command. |
| test | Object | One of the test objects which result will be negated |
| id | String | size | A string describing the test command. |
| comparison | String | Only two types are valid here. A description can be found in . | |
| size | Number | A number specifying the size for this comparison, in bytes. |
| over | Used in the size test to check for a value greater than the given one |
| under | Used in the size test to check for a value less than the given one |
| id | String | header | A string describing the test command. |
| comparison | String | Available types can be found in the config object. (see Table 25) | |
| headers | Array | A string array containing the header fields | |
| values | Array | A string array containing the value for the header fields |
| id | String | body | A string describing the test command. |
| comparison | String | Available types can be found in the config object. (see Table 25). | |
| extensionskey | String | The extension key can be one of the value found in Table 12 | |
| extensionsvalue | String | A value for the given key. If the key has no value (see Table 12 for this information) the value given here is ignored | |
| values | Array | A string array containing the values for the body |
| content | An extension used in conjunction with the body test to define the content which should be considered. This extension will need a parameter specifying the mime-type of the part of the message which will be searched. |
| text | An extension used in conjunction with the body test to define that only the text of the body should be considered in this test. This extension takes no parameter |
| id | String | allof | A string describing the test command. |
| tests | Array | A array of tests |
| id | String | anyof | A string describing the test command. |
| tests | Array | A array of tests |
Actions
In this section you will find the structures of all action commands which are specified until now. First a complete list of all action commands is given with a short description of them, later on the different objects for those commands are specified.
| keep | Keeps a mail non changed |
| discard | Discards a mail without any processing |
| redirect | Redirects a mail to a given e-mail address |
| move | Moves a mail into a given subfolder. The syntax for the subfolder given here. Must be the correct syntax of the underlying IMAP-server. So it is up to the GUI to detect things such as altnamespace or unixhierarchysep. |
| reject | Rejects the mail with a given text |
| stop | Stops any further progressing of a mail |
| vacation | Creates a vacation mail |
| addflags | Adds flags to a mail |
| id | String | keep | A string defining the object itself |
| id | String | discard | A string defining the object itself |
| id | String | redirect | A string defining the object itself |
| to | String | A string containing where the mail should be redirected to |
| id | String | move | A string defining the object itself |
| into | String | This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware |
| id | String | reject | A string defining the object itself |
| text | String | A string containing the reason why the mail is rejected |
| id | String | stop | A string defining the object itself |
| id | String | vacation | A string defining the object itself |
| days | Integer | The days for which a vacation text is returned | |
| addresses | Array | The addresses for which this vacation is responsible. That means for which addresses out of the aliases array of the user defining this filter, vacations will be sent. | |
| subject | String | The new subject for the returned message (can be left empty, when only adding RE:) | |
| text | String | The vacation text itself |
| id | String | addflags | A string defining the object itself |
| flags | Array | An array containing the flags which should be added to that mail. A flag can be either a system flag or a user flag. System flags begin with a backslash (\) and can be one of the following:
System flags are case-insensitive. User flags begin with a dollar sign ($) and can contain any ASCII characters between 0x21 (!) and 0x7E (~), inclusive, except for the characters 0x22, 0x25, 0x28, 0x29, 0x2A, 0x5C, 0x5D and 0x7B, which correspond to "%()*\]{
Mail color flags as used by OX are implemented by user flags of the form $cl_n, where n is a number between 1 and 10, includive. See RFC 3501 for further details on IMAP flags and their meanings. |
Requests
Get the configuration of the mail filter backend
GET /ajax/mailfilter?action=config
Parameters:
- username This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed
Response body: An object describing the configuration like described in #Table 24.
| tests | Array | An array containing test-objects like described in Table 25 | |
| actioncommands | Array | An array containing the valid action commands as strings. A list of all possible values can be found in Table 15. |
| test | String | A name for the test. A list of all possible tests can be found in Table 2. The corresponding objects can be used in the test field in Table 1. | |
| comparison | Array | A string array containing the valid comparison types for this test. Possible values are given in Table 3. Values given in this array can be used in the comparison field in |
Get all mail filter rules
GET /ajax/mailfilter?action=list
Parameters:
- flag If given, only rules with this flag are returned
- username This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed
Response body: An array of rule objects like described in Table 1.
Create a mail filter rule
PUT /ajax/mailfilter?action=new
Parameters:
- username This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed
Request body: Rule object as described in Table 1. If the field position is included in Table 1 it's taken as the position of the rule in the array on the server side. Note that this value shouldn't be greater than the size of all rules
Response body: An integer for the id of the new created rule.
Delete a mail filter rule
PUT /ajax/mailfilter?action=delete
Parameters:
- username This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed
Request body: An object with the field id.
Reorder mail filter rules
PUT /ajax/mailfilter?action=reorder
Parameters:
- username This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed
Request body: An array of unique ids which represents how the rule with the corresponding unique ids are ordered
Update a mail filter rule
PUT /ajax/mailfilter?action=update
Parameters:
- username This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed
Request body: Rule object as described in Table 1 with the id set (which identifies the rule to change). Only modified fields are present.
Delete the whole script
PUT /ajax/mailfilter?action=deletescript
Parameters:
- username This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed
Note that this call is only used as workaround for parsing errors in the backend, so that the user is able to kick a whole script if it contains errors in the grammar.
Get the whole script
PUT /ajax/mailfilter?action=getscript
Parameters:
- username This parameter must contain the user name for admin mode. So the normal credentials are taken for authentication but the mail filter of the user with this username is being changed
Response body: A text of the complete sieve script
Note that this call is only used as workaround for parsing errors in the backend, so that the user is able to get the plaintext of a complete script.