HTTP API MailFilter

From Open-Xchange
Open-Xchange Mail Filter HTTP API

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.

Name
Type
Value
Description
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 3 flags are reserved here: "spam" which marks the default spam rule, "vacation" which marks the vacation rules and "autoforward" which marks an autoforwarding rule.
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
Table 1: Structure of a rule

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.


Name
Description
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.
currentdate Compares a given date with the current date (available with 6.20)
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.
Table 2: List of all possible tests


Name
Description
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

all Tests if the e-mail address is the value given here. This means in herbert.mustermann@example.com, the all checks the entire e-mail address (Since 7.8.3)

Attention: This comparison can only be used in conjunction with the address test

localpart Tests if the local part of an e-mail address is the value given here. This means in herbert.mustermann@example.com, the localpart checks the part herbert.mustermann (Since 7.8.3).

Attention: This comparison can only be used in conjunction with the address test

domain Tests if the domain part of an e-mail address is the value given here. This means in herbert.mustermann@example.com, the domain checks the part example.com (Since 7.8.3).

Attention: This comparison can only be used in conjunction with the address test

Table 3: List of all possible comparisons


Name
Type
Value
Description
id String address A string describing the test command.
comparison String Available types can be found in the config object. (see Table 26).
headers Array A string array containing the header fields
values Array A string array containing the value for the header fields. The test will be true if any of the strings matches
Table 4: Structure of address-test


Name
Type
Value
Description
id String envelope A string describing the test command.
comparison String Available types can be found in the config object. (see Table 26).
headers Array A string array containing the header fields
values Array A string array containing the value for the header fields. The test will be true if any of the strings matches
Table 5: Structure of envelope-test


Name
Type
Value
Description
id String true A string describing the test command.
Table 6: Structure of true-test


Name
Type
Value
Description
id String not A string describing the test command.
test Object One of the test objects which result will be negated
Table 7: Structure of not-test


Name
Type
Value
Description
id String size A string describing the test command.
comparison String Only two types are valid here. A description can be found in Table 9.
size Number A number specifying the size for this comparison, in bytes.
Table 8: Structure of size-test


Name
Description
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
Table 9: Types of comparison for size


Name
Type
Value
Description
id String currentdate A string describing the test command.
comparison String Only three types are valid here. A description can be found in Table 11.
datepart String A string containing the string "date", "weekday" or "time" (available with 7.6.1) as we only allow fix date, time and weekday comparisions for now.
datevalue Array A value array containing the corresponding value to the datepart. For "date" and "time" this will be an array of "Date" (unix timestamp). For "weekday", it will be an array of integers ranging from 0 to 6, reflecting the equivalent weekday, starting from Sunday through Saturday, i.e. 0 - Sunday, ..., 6 - Saturday. The test will be true if any of the values matches
Table 10: Structure of currentdate-test


Name
Description
is Used in the date test to check for a value equal to the given one
ge Used in the date test to check for a value greater or equal to the given one
le Used in the date test to check for a value less or equal to the given one
Table 11: Types of comparison for currentdate


Name
Type
Value
Description
id String header A string describing the test command.
comparison String Available types can be found in the config object. (see Table 26)
headers Array A string array containing the header fields
values Array A string array containing the values for the header fields. The test will be true if any of the strings matches
Table 12: Structure of header-test


Name
Type
Value
Description
id String body A string describing the test command.
comparison String Available types can be found in the config object. (see Table 26).
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. The test will be true if any of the strings matches
Table 13: Structure of body-test


Name
Description
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
Table 14: List of possible extensions


Name
Type
Value
Description
id String allof A string describing the test command.
tests Array A array of tests
Table 15: Structure of allof-test


Name
Type
Value
Description
id String anyof A string describing the test command.
tests Array A array of tests
Table 16: Structure of anyof-test

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.


Name
Description
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
notify adds a notification
pgp encrypts a mail via pgp
Table 17: List of possible action commands


Name
Type
Value
Description
id String keep A string defining the object itself
Table 18: Structure of keep-command


Name
Type
Value
Description
id String discard A string defining the object itself
Table 19: Structure of discard-command


Name
Type
Value
Description
id String redirect A string defining the object itself
to String A string containing where the mail should be redirected to
keep boolean A boolean flag indicating whether a copy of the e-mail will be kept in the local INBOX (Since 7.8.3)
Table 20: Structure of redirect-command


Name
Type
Value
Description
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
Table 21: Structure of move-command


Name
Type
Value
Description
id String reject A string defining the object itself
text String A string containing the reason why the mail is rejected
Table 22: Structure of reject-command


Name
Type
Value
Description
id String stop A string defining the object itself
Table 23: Structure of stop-command


Name
Type
Value
Description
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.
from String or Array Support for the ':from' tag. Specifies the value of the from header for the auto-reply mail, e.g. Foo Bear <foo.bear@ox.io> (Since 7.8.1). The array of strings should be a simple JSONArray with length 2; the first element should include the personal part of the e-mail address and the second element the actual e-mail address. If only the e-mail address is available, that should be the only element of the array.
subject String The new subject for the returned message (can be left empty, when only adding RE:)
text String The vacation text itself
Table 24: Structure of vacation-command


Name
Type
Value
Description
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:
  • \seen
  • \answered
  • \flagged
  • \deleted
  • \draft
  • \recent

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.

Table 25: Structure of addflags-command
Name
Type
Value
Description
id String notify A string defining the object itself
message String the content of the notification message
method String the method of the notification message, e.g.
"mailto:012345678@sms.gateway"
Table 26: Structure of notify-command
Name
Type
Value
Description
id String pgp A string defining the object itself
keys Array The public keys as string which should be used for encryption
Table 27: Structure of pgp-command

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


Name
Type
Value
Description
tests Array An array containing test-objects like described in Table 29
actioncommands Array An array containing the valid action commands as strings. A list of all possible values can be found in Table 17.
Table 28: Config object


Name
Type
Value
Description
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
Table 29: Test object

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.