HTTP API MailFilter: Difference between revisions
(29 intermediate revisions by 3 users not shown) | |||
Line 17: | Line 17: | ||
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. | 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. | 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|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. | 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. | 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|Table 3]]. | ||
= The core = | = 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 [[#Tests| | 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|Table 1]]). The dynamical parts are the test, which are represented by different options, see [[#Tests|4.1. Tests]], and the actions, also represented in [[#Actions|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. | ||
{| cellspacing="0" border="1" class="prettytable" | {| id="Table 1" cellspacing="0" border="1" class="prettytable" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 60: | Line 60: | ||
| Array | | 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 | | 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. | ||
|- | |- | ||
Line 66: | Line 66: | ||
| Object | | Object | ||
| | | | ||
| The structure of the different test objects can be found in section [[#Tests| | | The structure of the different test objects can be found in section [[#Tests|4.1. Tests]]. The valid tests in the current setup can be found in the configuration object | ||
|- | |- | ||
Line 72: | Line 72: | ||
| Array | | Array | ||
| | | | ||
| An array of action objects whose different structures can be found in section [[#Actions| | | An array of action objects whose different structures can be found in section [[#Actions|4.2. Actions]]. The action commands which are valid here can be determined through the config object see Table 24 | ||
|- | |- | ||
Line 94: | Line 94: | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 2" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Description</center> | ! <center>Description</center> | ||
Line 117: | Line 117: | ||
| size | | size | ||
| Deals with the size of the mail'''.''' | | Deals with the size of the mail'''.''' | ||
|- | |||
| currentdate | |||
| Compares a given date with the current date ('''available with 6.20''') | |||
|- | |- | ||
Line 138: | Line 142: | ||
{| cellspacing="0" border="1" class="prettytable" | {| id="Table 3" cellspacing="0" border="1" class="prettytable" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Description</center> | ! <center>Description</center> | ||
Line 167: | Line 171: | ||
| detail | | detail | ||
| Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann. | | 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 [mailto:herbert.mustermann@example.com 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 [mailto:herbert.mustermann@example.com 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 [mailto:herbert.mustermann@example.com 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 | '''Attention: '''This comparison can only be used in conjunction with the address test | ||
Line 175: | Line 197: | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 4" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 191: | Line 213: | ||
| String | | String | ||
| | | | ||
| Available types can be found in the config object. (see Table | | Available types can be found in the config object. (see [[#Table 26|Table 26]]). | ||
|- | |- | ||
Line 203: | Line 225: | ||
| Array | | Array | ||
| | | | ||
| A string array containing the value for the header fields | | A string array containing the value for the header fields. The test will be true if any of the strings matches | ||
|} | |} | ||
Line 209: | Line 231: | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 5" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 225: | Line 247: | ||
| String | | String | ||
| | | | ||
| Available types can be found in the config object. (see Table | | Available types can be found in the config object. (see [[#Table 26|Table 26]]). | ||
|- | |- | ||
Line 237: | Line 259: | ||
| Array | | Array | ||
| | | | ||
| A string array containing the value for the header fields | | A string array containing the value for the header fields. The test will be true if any of the strings matches | ||
|} | |} | ||
Line 243: | Line 265: | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 6" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 259: | Line 281: | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 7" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 281: | Line 303: | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 8" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 297: | Line 319: | ||
| String | | String | ||
| | | | ||
| Only two types are valid here. A description can be found in . | | Only two types are valid here. A description can be found in [[#Table 9|Table 9]]. | ||
|- | |- | ||
Line 309: | Line 331: | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 9" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Description</center> | ! <center>Description</center> | ||
Line 325: | Line 347: | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | |||
{| id="currentdate" cellspacing="0" border="1" class="prettytable" width="100%" | |||
! <center>Name</center> | |||
! <center>Type</center> | |||
! <center>Value</center> | |||
! <center>Description</center> | |||
|- | |||
| 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|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 | |||
|} | |||
<center>''Table 10: Structure of currentdate-test''</center> | |||
{| id="Table 11" cellspacing="0" border="1" class="prettytable" width="100%" | |||
! <center>Name</center> | |||
! <center>Description</center> | |||
|- | |||
| 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 | |||
|} | |||
<center>''Table 11: Types of comparison for currentdate''</center> | |||
{| id="Table 12" cellspacing="0" border="1" class="prettytable" width="100%" | |||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 341: | Line 420: | ||
| String | | String | ||
| | | | ||
| Available types can be found in the config object. (see Table | | Available types can be found in the config object. (see [[#Table 26|Table 26]]) | ||
|- | |- | ||
Line 353: | Line 432: | ||
| Array | | Array | ||
| | | | ||
| A string array containing the | | A string array containing the values for the header fields. The test will be true if any of the strings matches | ||
|} | |} | ||
<center>''Table | <center>''Table 12: Structure of header-test''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 13" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 375: | Line 454: | ||
| String | | String | ||
| | | | ||
| Available types can be found in the config object. (see Table | | Available types can be found in the config object. (see [[#Table 26|Table 26]]). | ||
|- | |- | ||
Line 381: | Line 460: | ||
| String | | String | ||
| | | | ||
| The extension key can be one of the value found in Table 12 | | The extension key can be one of the value found in [[#Table 12|Table 12]] | ||
|- | |- | ||
Line 387: | Line 466: | ||
| String | | 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 | | A value for the given key. If the key has no value (see [[#Table 12|Table 12]] for this information) the value given here is ignored | ||
|- | |- | ||
Line 393: | Line 472: | ||
| Array | | Array | ||
| | | | ||
| A string array containing the values for the body | | A string array containing the values for the body. The test will be true if any of the strings matches | ||
|} | |} | ||
<center>''Table | <center>''Table 13: Structure of body-test''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 14" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Description</center> | ! <center>Description</center> | ||
Line 412: | Line 491: | ||
|} | |} | ||
<center>''Table | <center>''Table 14: List of possible extensions''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 15" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 434: | Line 513: | ||
|} | |} | ||
<center>''Table | <center>''Table 15: Structure of allof-test''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 16" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 456: | Line 535: | ||
|} | |} | ||
<center>''Table | <center>''Table 16: Structure of anyof-test''</center> | ||
== Actions == | == Actions == | ||
Line 462: | Line 541: | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 17" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Description</center> | ! <center>Description</center> | ||
Line 497: | Line 576: | ||
| addflags | | addflags | ||
| Adds flags to a mail | | Adds flags to a mail | ||
|- | |||
| notify | |||
| adds a notification | |||
|- | |||
| pgp | |||
| encrypts a mail via pgp | |||
|} | |} | ||
<center>''Table | <center>''Table 17: List of possible action commands''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 18" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 515: | Line 602: | ||
|} | |} | ||
<center>''Table | <center>''Table 18: Structure of keep-command''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 19" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 531: | Line 618: | ||
|} | |} | ||
<center>''Table | <center>''Table 19: Structure of discard-command''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 20" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 551: | Line 638: | ||
| | | | ||
| A string containing where the mail should be redirected to | | 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) | |||
|} | |} | ||
<center>''Table | <center>''Table 20: Structure of redirect-command''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 21" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 575: | Line 668: | ||
|} | |} | ||
<center>''Table | <center>''Table 21: Structure of move-command''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 22" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 597: | Line 690: | ||
|} | |} | ||
<center>''Table | <center>''Table 22: Structure of reject-command''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 23" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 613: | Line 706: | ||
|} | |} | ||
<center>''Table | <center>''Table 23: Structure of stop-command''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 24" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 639: | Line 732: | ||
| | | | ||
| 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. | | 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. | |||
|- | |- | ||
Line 653: | Line 752: | ||
|} | |} | ||
<center>''Table | <center>''Table 24: Structure of vacation-command''</center> | ||
{| cellspacing="0" border="1" class="prettytable" width="100%" | {| id="Table 25" cellspacing="0" border="1" class="prettytable" width="100%" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 687: | Line 786: | ||
See RFC 3501 for further details on IMAP flags and their meanings. | See RFC 3501 for further details on IMAP flags and their meanings. | ||
|} | |} | ||
<center>''Table | <center>''Table 25: Structure of addflags-command''</center> | ||
{| id="Table 26" cellspacing="0" border="1" class="prettytable" width="100%" | |||
! <center>Name</center> | |||
! <center>Type</center> | |||
! <center>Value</center> | |||
! <center>Description</center> | |||
|- | |||
| 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. <pre>"mailto:012345678@sms.gateway"</pre> | |||
|} | |||
<center>''Table 26: Structure of notify-command''</center> | |||
{| id="Table 27" cellspacing="0" border="1" class="prettytable" width="100%" | |||
! <center>Name</center> | |||
! <center>Type</center> | |||
! <center>Value</center> | |||
! <center>Description</center> | |||
|- | |||
| id | |||
| String | |||
| pgp | |||
| A string defining the object itself | |||
|- | |||
| keys | |||
| Array | |||
| | |||
| The public keys as string which should be used for encryption | |||
|} | |||
<center>''Table 27: Structure of pgp-command''</center> | |||
= Requests = | = Requests = | ||
Line 697: | Line 844: | ||
* <tt>username</tt> 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 | * <tt>username</tt> 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 | Response body: An object describing the configuration like described in [[#Table 28|Table 28]]. | ||
{| cellspacing="0" border="1" class="prettytable" | {| id="Table 28" cellspacing="0" border="1" class="prettytable" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 710: | Line 857: | ||
| Array | | Array | ||
| | | | ||
| An array containing test-objects like described in Table | | An array containing test-objects like described in [[#Table 29|Table 29]] | ||
|- | |- | ||
Line 716: | Line 863: | ||
| Array | | Array | ||
| | | | ||
| An array containing the valid action commands as strings. A list of all possible values can be found in Table | | An array containing the valid action commands as strings. A list of all possible values can be found in [[#Table 17|Table 17]]. | ||
|} | |} | ||
<center>''Table | <center>''Table 28: Config object''</center> | ||
{| cellspacing="0" border="1" class="prettytable" | {| id="Table 29" cellspacing="0" border="1" class="prettytable" | ||
! <center>Name</center> | ! <center>Name</center> | ||
! <center>Type</center> | ! <center>Type</center> | ||
Line 732: | Line 879: | ||
| String | | 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. | | A name for the test. A list of all possible tests can be found in [[#Table 2|Table 2]]. The corresponding objects can be used in the test field in [[#Table 1|Table 1]]. | ||
|- | |- | ||
Line 738: | Line 885: | ||
| Array | | 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 | | A string array containing the valid comparison types for this test. Possible values are given in [[#Table 3|Table 3]]. Values given in this array can be used in the comparison field in | ||
|} | |} | ||
<center>''Table | <center>''Table 29: Test object''</center> | ||
== Get all mail filter rules == | == Get all mail filter rules == | ||
Line 751: | Line 898: | ||
* <tt>username</tt> 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 | * <tt>username</tt> 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. | Response body: An array of rule objects like described in [[#Table 1|Table 1]]. | ||
== Create a mail filter rule == | == Create a mail filter rule == | ||
Line 760: | Line 907: | ||
* <tt>username</tt> 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 | * <tt>username</tt> 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 <tt>position</tt> 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 | Request body: Rule object as described in [[#Table 1|Table 1]]. If the field <tt>position</tt> is included in [[#Table 1|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. | Response body: An integer for the id of the new created rule. | ||
Line 789: | Line 936: | ||
* <tt>username</tt> 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 | * <tt>username</tt> 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 <tt>id</tt> set (which identifies the rule to change). Only modified fields are present. | Request body: Rule object as described in [[#Table 1|Table 1]] with the <tt>id</tt> set (which identifies the rule to change). Only modified fields are present. | ||
== Delete the whole script == | == Delete the whole script == |
Latest revision as of 11:02, 11 October 2016
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 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 |
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. |
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. |
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 |
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 |
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 |
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 Table 9. | |
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 | 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 |
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 |
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 |
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 |
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 |
notify | adds a notification |
pgp | encrypts a mail via pgp |
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 | |
keep | boolean | A boolean flag indicating whether a copy of the e-mail will be kept in the local INBOX (Since 7.8.3) |
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. | |
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 |
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. |
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" |
id | String | pgp | A string defining the object itself |
keys | Array | The public keys as string which should be used for encryption |
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.
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. |
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.