https://oxpedia.org/wiki/api.php?action=feedcontributions&user=Schwaiger&feedformat=atomOpen-Xchange - User contributions [en]2024-03-28T14:57:20ZUser contributionsMediaWiki 1.31.0https://oxpedia.org/wiki/index.php?title=My_Registrations&diff=10348My Registrations2012-05-03T10:09:19Z<p>Schwaiger: /* 5. Step: Contact Support */</p>
<hr />
<div>= My Registrations =<br />
<br />
Here is detailed information regarding software and support license keys. Please take a few minutes to read this, as you get started.<br />
<br />
= Email with purchase confirmation - What are the keys?=<br />
<br />
* '''Maintenance / licence Key''' - The Maintenance Key (MK) entitles you to use the purchased product and / or to optain updates for the purchased period for the number of licensed users.<br />
* '''Support Key''' - The Support Key (SUP) ensures that inquiries are handled in accordance with the purchased support contract, and thus with the underlying Service Level Agreement. For the use of advanced support services, valid maintenance for all activated users is required. Additional information can be found here, http://knowledgebase.open-xchange.com/index.php?id=339<br />
* '''Migration Key''' - The Migration Key (MIG) entitles you to use the Data Migration Tools, including updates for internal use.<br />
* '''Univention license key or license file''' - The Univention license key or license file authorizes the use of the respective Univention components of the purchased product (Open-Xchange Advanced Server or Open-Xchange Server for UCS) for the respective time period. Univention license file controls the number of users that can be created in the system.<br />
<br />
= 1. Step: Create LDB Account =<br />
<br />
* '''What is an LDB account?''' - For each customer, an account in the license database (LDB) is required. The LDB account summarizes almost all purchased products and services of a single customer.<br />
* '''What is the use of the LDB account?''' - An LDB account is used to access all protected areas for software and services, such as updates, OXtender, patch releases, and technical support<br />
* '''When do you need your LDB account?'''<br />
** Download via OXpedia administration front-end of Open-Xchange Appliance Edtion<br />
** update repositories of Open-Xchange Server Edition<br />
** update repositories of Open-Xchange Hosting Edition<br />
** For more details, please visit the documentation of the respective product<br />
<br />
= 2. Step: Key activation in the LDB =<br />
<br />
By activating the Keys, a product or service is assigned to a specific LDB account. To acitvate a key, visit http://sdb.open-xchange.com/create-ldb-account-en#activate<br />
<br />
= 3. Step: Confirmation of the EULA / Terms (optional) =<br />
<br />
Depending on the purchased product, acceptance of the End User License Agreements or the terms and conditions is required. For more details, please visit http://sdb.open-xchange.com/create-ldb-account-en#EULA<br />
<br />
= 4. Step: Download and installation documentation (OXpedia) =<br />
<br />
All installation and product documentation, as well as all Open-Xchange software is available at http://knowledgebase.open-xchange.com/index.php?id=171<br />
<br />
= 5. Step: Contact Support =<br />
<br />
Details for contacting Support can be found at [mailto:support@open-xchange.com contact-support].</div>Schwaigerhttps://oxpedia.org/wiki/index.php?title=My_Registrations&diff=10347My Registrations2012-05-03T10:08:54Z<p>Schwaiger: /* 5. Step: Contact Support */</p>
<hr />
<div>= My Registrations =<br />
<br />
Here is detailed information regarding software and support license keys. Please take a few minutes to read this, as you get started.<br />
<br />
= Email with purchase confirmation - What are the keys?=<br />
<br />
* '''Maintenance / licence Key''' - The Maintenance Key (MK) entitles you to use the purchased product and / or to optain updates for the purchased period for the number of licensed users.<br />
* '''Support Key''' - The Support Key (SUP) ensures that inquiries are handled in accordance with the purchased support contract, and thus with the underlying Service Level Agreement. For the use of advanced support services, valid maintenance for all activated users is required. Additional information can be found here, http://knowledgebase.open-xchange.com/index.php?id=339<br />
* '''Migration Key''' - The Migration Key (MIG) entitles you to use the Data Migration Tools, including updates for internal use.<br />
* '''Univention license key or license file''' - The Univention license key or license file authorizes the use of the respective Univention components of the purchased product (Open-Xchange Advanced Server or Open-Xchange Server for UCS) for the respective time period. Univention license file controls the number of users that can be created in the system.<br />
<br />
= 1. Step: Create LDB Account =<br />
<br />
* '''What is an LDB account?''' - For each customer, an account in the license database (LDB) is required. The LDB account summarizes almost all purchased products and services of a single customer.<br />
* '''What is the use of the LDB account?''' - An LDB account is used to access all protected areas for software and services, such as updates, OXtender, patch releases, and technical support<br />
* '''When do you need your LDB account?'''<br />
** Download via OXpedia administration front-end of Open-Xchange Appliance Edtion<br />
** update repositories of Open-Xchange Server Edition<br />
** update repositories of Open-Xchange Hosting Edition<br />
** For more details, please visit the documentation of the respective product<br />
<br />
= 2. Step: Key activation in the LDB =<br />
<br />
By activating the Keys, a product or service is assigned to a specific LDB account. To acitvate a key, visit http://sdb.open-xchange.com/create-ldb-account-en#activate<br />
<br />
= 3. Step: Confirmation of the EULA / Terms (optional) =<br />
<br />
Depending on the purchased product, acceptance of the End User License Agreements or the terms and conditions is required. For more details, please visit http://sdb.open-xchange.com/create-ldb-account-en#EULA<br />
<br />
= 4. Step: Download and installation documentation (OXpedia) =<br />
<br />
All installation and product documentation, as well as all Open-Xchange software is available at http://knowledgebase.open-xchange.com/index.php?id=171<br />
<br />
= 5. Step: Contact Support =<br />
<br />
Details for contacting Support can be found at [mailto:support@open-xchange.com].</div>Schwaigerhttps://oxpedia.org/wiki/index.php?title=OX6:OX6-Upsell&diff=6724OX6:OX6-Upsell2010-12-15T14:55:57Z<p>Schwaiger: </p>
<hr />
<div>= Upsell Gui =<br />
<br />
=== Adding new feature (e.g. video, screenshot)===<br />
<br />
* Open register.js (located in gui folder)<br />
* Search for upsell.config.features<br />
* add the following code ( description inline )<br />
<br />
<pre><br />
featurename: {<br />
name: ["trigger element"],<br />
title: _("upsell window title"),<br />
product_name: _("feature headline"),<br />
intro: _("upsell description text"),<br />
list: {<br />
list_item_1: _("enumeration"),<br />
list_item_2: _("enumeration"),<br />
list_item_3: _("..."),<br />
},<br />
outro: _("upsell text that shows at end"),<br />
videos: {<br />
video_1: {<br />
thumb: "name_of_video_thumbnail.png",<br />
video: "name_of_video_file.swf"<br />
}<br />
},<br />
images: {<br />
image_1: {<br />
thumb: "name_of_image_thumbnail.png",<br />
image: "name_of_lightbox_image.png"<br />
}<br />
},<br />
buttons: {<br />
trial: {<br />
content: _("buttonlabel"),<br />
action: "put javascript actions here if any"<br />
},<br />
},<br />
checkboxes: {<br />
invite:{<br />
content: _("checkboxlabel"),<br />
action: "put javascript actions here if any"<br />
}<br />
}<br />
},<br />
</pre><br />
<br />
* after the feature is implemented you should create the nessacarry files and place them as follow<br />
<br />
<pre><br />
-templates<br />
--_featurename<br />
---- language ( for example de_DE )<br />
-------- flash ( for videos )<br />
-------- img ( for images )<br />
</pre><br />
<br />
<br />
=== Load required js/cs files ===<br />
<br />
* to load additional files open register.js and add the following code<br />
<br />
<pre><br />
upsell = {<br />
files: {<br />
jss: {<br />
name: {<br />
script: "name.js",<br />
},<br />
},<br />
css: {<br />
name: "name.css",<br />
},<br />
},<br />
}<br />
</pre><br />
<br />
* add name.js to jss/name.js<br />
* add name.css to css/name.css<br />
<br />
=== change look and feel (e.g. branding, colors and sizes) ===<br />
<br />
* you should edit the existing css located in /var/www/ox6/plugins/com.openexchange.upsell.multiple.gui/css/upsell.css<br />
* you can add / edit background in /var/www/ox6/plugins/com.openexchange.upsell.multiple.gui//img<br />
<br />
<br />
=== possible triggers ===<br />
<pre><br />
modules/calendar/freebusy<br />
modules/calendar/team<br />
modules/calendar/mini_calender<br />
modules/calendar/new/add_participants<br />
modules/calendar/new/remove_participants<br />
modules/calendar/new/add_attachment<br />
modules/calendar/new/delete_attachment<br />
modules/contacts/new/add_attachment<br />
modules/contacts/new/delete_attachment<br />
modules/mail/save_to_infostore<br />
modules/infostore/send_as_attachment<br />
modules/infostore/send_as_link<br />
modules/infostore/mail/save_to_infostore<br />
modules/tasks/new/add_participants<br />
modules/tasks/new/remove_participants<br />
modules/tasks/new/add_attachment<br />
modules/tasks/new/delete_attachment<br />
configuration/mail/accounts/new<br />
modules/folders/users<br />
<br />
modules/infostore<br />
modules/calender<br />
modules/contacts<br />
modules/mail<br />
modules/portal<br />
modules/tasks<br />
modules/configuration<br />
<br />
modules/outlook<br />
modules/mobility<br />
</pre><br />
<br />
=== change the mail templates ===</div>Schwaigerhttps://oxpedia.org/wiki/index.php?title=OX6:OX6-Upsell&diff=6710OX6:OX6-Upsell2010-12-15T11:29:12Z<p>Schwaiger: Created page with "= Upsell Gui = === Adding new feature === * Open register.js (located in gui folder) * Search for upsell.config.features * add the following code ( description inline ) <pre> ..."</p>
<hr />
<div>= Upsell Gui =<br />
<br />
=== Adding new feature ===<br />
<br />
* Open register.js (located in gui folder)<br />
* Search for upsell.config.features<br />
* add the following code ( description inline )<br />
<br />
<pre><br />
featurename: {<br />
name: ["trigger element"],<br />
title: _("upsell window title"),<br />
product_name: _("feature headline"),<br />
intro: _("upsell description text"),<br />
list: {<br />
list_item_1: _("enumeration"),<br />
list_item_2: _("enumeration"),<br />
list_item_3: _("..."),<br />
},<br />
outro: _("upsell text that shows at end"),<br />
videos: {<br />
video_1: {<br />
thumb: "name_of_video_thumbnail.png",<br />
video: "name_of_video_file.swf"<br />
}<br />
},<br />
images: {<br />
image_1: {<br />
thumb: "name_of_image_thumbnail.png",<br />
image: "name_of_lightbox_image.png"<br />
}<br />
},<br />
buttons: {<br />
trial: {<br />
content: _("buttonlabel"),<br />
action: "put javascript actions here if any"<br />
},<br />
},<br />
checkboxes: {<br />
invite:{<br />
content: _("checkboxlabel"),<br />
action: "put javascript actions here if any"<br />
}<br />
}<br />
},<br />
</pre><br />
<br />
* after the feature is implemented you should create the nessacarry files and place them as follow<br />
<br />
<pre><br />
-templates<br />
--_featurename<br />
---- language ( for example de_DE )<br />
-------- flash ( for videos )<br />
-------- img ( for images )<br />
</pre><br />
<br />
<br />
=== Load required js/cs files ===<br />
<br />
* to load additional files open register.js and add the following code<br />
<br />
<pre><br />
upsell = {<br />
files: {<br />
jss: {<br />
name: {<br />
script: "name.js",<br />
},<br />
},<br />
css: {<br />
name: "name.css",<br />
},<br />
},<br />
}<br />
</pre><br />
<br />
* add name.js to jss/name.js<br />
* add name.css to css/name.css<br />
<br />
=== change look and feel ===<br />
<br />
* to change the look in feel you should edit the existing css located in css/upsell.css<br />
* you can add / edit background in img<br />
<br />
=== possible triggers ===<br />
<pre><br />
modules/calendar/freebusy<br />
modules/calendar/team<br />
modules/calendar/mini_calender<br />
modules/calendar/new/add_participants<br />
modules/calendar/new/remove_participants<br />
modules/calendar/new/add_attachment<br />
modules/calendar/new/delete_attachment<br />
modules/contacts/new/add_attachment<br />
modules/contacts/new/delete_attachment<br />
modules/mail/save_to_infostore<br />
modules/infostore/send_as_attachment<br />
modules/infostore/send_as_link<br />
modules/infostore/mail/save_to_infostore<br />
modules/tasks/new/add_participants<br />
modules/tasks/new/remove_participants<br />
modules/tasks/new/add_attachment<br />
modules/tasks/new/delete_attachment<br />
configuration/mail/accounts/new<br />
modules/folders/users<br />
<br />
modules/infostore<br />
modules/calender<br />
modules/contacts<br />
modules/mail<br />
modules/portal<br />
modules/tasks<br />
modules/configuration<br />
<br />
modules/outlook<br />
modules/mobility<br />
</pre></div>Schwaigerhttps://oxpedia.org/wiki/index.php?title=HTTP_API_MailFilter&diff=5359HTTP API MailFilter2010-02-11T12:08:53Z<p>Schwaiger: /* The core */</p>
<hr />
<div><center>'''Open-Xchange Mail Filter HTTP API'''</center><br />
<br />
= Introduction =<br />
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.<br />
<br />
= Module mailfilter =<br />
This module is used to access all mail filter related options.<br />
<br />
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.<br />
<br />
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 <tt>address</tt>, <tt>allof</tt> and <tt>anyof</tt>.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
= The core =<br />
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|outline #4.1.Tests]], and the actions, also represented in [[#Actions|outline 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.<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| Integer<br />
| <br />
| A unique identifier (once created must not be changed)<br />
<br />
|-<br />
| position<br />
| Integer<br />
| <br />
| The position inside the mail filter list. Starts with 0<br />
<br />
|-<br />
| rulename<br />
| String<br />
| <br />
| A name describing the rule, can be empty but must not contain a line break<br />
<br />
|-<br />
| active<br />
| Boolean<br />
| <br />
| If this rule is active or not<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| 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.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| The structure of the different test objects can be found in section [[#Tests|outline 4.1.Tests]]. The valid tests in the current setup can be found in the configuration object <br />
<br />
|-<br />
| actioncmds<br />
| Array<br />
| <br />
| An array of action objects whose different structures can be found in section [[#Actions|outline 4.2.Actions]]. The action commands which are valid here can be determined through the config object see Table 24<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing the whole lines of this command.<br />
<br />
|-<br />
| errormsg<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing a message why, or what part of the rule isn't known<br />
<br />
|}<br />
<center>''Table 1: Structure of a rule''</center><br />
<br />
= The dynamical part =<br />
== Tests ==<br />
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.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| address<br />
| 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.<br />
<br />
|-<br />
| envelope<br />
| 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'''.'''<br />
<br />
|-<br />
| true<br />
| A test for a true result (can be used if an action command should be executed every time)'''.'''<br />
<br />
|-<br />
| not<br />
| Negates a given test'''.'''<br />
<br />
|-<br />
| size<br />
| Deals with the size of the mail'''.'''<br />
<br />
|-<br />
| header<br />
| 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.<br />
<br />
|-<br />
| body<br />
| Tests against the content of a mail.<br />
<br />
|-<br />
| allof<br />
| Defines an AND condition between several tests'''.'''<br />
<br />
|-<br />
| anyof<br />
| Defines an OR condition between several tests'''.'''<br />
<br />
|}<br />
<center>''Table 2: List of all possible tests''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| If a field is equal to a given value<br />
<br />
|-<br />
| contains<br />
| If a field contains a given value at any position<br />
<br />
|-<br />
| matches<br />
| 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.<br />
<br />
|-<br />
| regex<br />
| Tests if a given regular expression matches with the value present in the specified field.<br />
<br />
|-<br />
| user<br />
| Tests if the user part of an e-mail address is the value given here. This means in [mailto:herbert+mustermann@example.com herbert+mustermann@example.com]. The user checks the part herbert.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|-<br />
| detail<br />
| Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|}<br />
<center>''Table 3: List of all possible comparisons''</center><br />
<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| address<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 4: Structure of address-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| envelope<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 5: Structure of envelope-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| true<br />
| A string describing the test command.<br />
<br />
|}<br />
<center>''Table 6: Structure of true-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| not<br />
| A string describing the test command.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| One of the test objects which result will be negated<br />
<br />
|}<br />
<center>''Table 7: Structure of not-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| size<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only two types are valid here. A description can be found in .<br />
<br />
|-<br />
| size<br />
| Number<br />
| <br />
| A number specifying the size for this comparison, in bytes.<br />
<br />
|}<br />
<center>''Table 8: Structure of size-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| over<br />
| Used in the size test to check for a value greater than the given one<br />
<br />
|-<br />
| under<br />
| Used in the size test to check for a value less than the given one<br />
<br />
|}<br />
<center>''Table 9: Types of comparison for size''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| header<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25)<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 10: Structure of header-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| body<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| extensionskey<br />
| String<br />
| <br />
| The extension key can be one of the value found in Table 12<br />
<br />
|-<br />
| extensionsvalue<br />
| String<br />
| <br />
| A value for the given key. If the key has no value (see Table 12 for this information) the value given here is ignored<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the body<br />
<br />
|}<br />
<center>''Table 11: Structure of body-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| content<br />
| 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.<br />
<br />
|-<br />
| text<br />
| 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<br />
<br />
|}<br />
<center>''Table 12: List of possible extensions''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| allof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 13: Structure of allof-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| anyof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 14: Structure of anyof-test''</center><br />
<br />
== Actions ==<br />
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.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| keep<br />
| Keeps a mail non changed<br />
<br />
|-<br />
| discard<br />
| Discards a mail without any processing<br />
<br />
|-<br />
| redirect<br />
| Redirects a mail to a given e-mail address<br />
<br />
|-<br />
| move<br />
| 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.<br />
<br />
|-<br />
| reject<br />
| Rejects the mail with a given text<br />
<br />
|-<br />
| stop<br />
| Stops any further progressing of a mail<br />
<br />
|-<br />
| vacation<br />
| Creates a vacation mail<br />
<br />
|-<br />
| addflags<br />
| Adds flags to a mail<br />
<br />
|}<br />
<center>''Table 15: List of possible action commands''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| keep<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 16: Structure of keep-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| discard<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 17: Structure of discard-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| redirect<br />
| A string defining the object itself<br />
<br />
|-<br />
| to<br />
| String<br />
| <br />
| A string containing where the mail should be redirected to<br />
<br />
|}<br />
<center>''Table 18: Structure of redirect-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| move<br />
| A string defining the object itself<br />
<br />
|-<br />
| into<br />
| String<br />
| <br />
| This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware<br />
<br />
|}<br />
<center>''Table 19: Structure of move-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| reject<br />
| A string defining the object itself<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| A string containing the reason why the mail is rejected<br />
<br />
|}<br />
<center>''Table 20: Structure of reject-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| stop<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 21: Structure of stop-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| vacation<br />
| A string defining the object itself<br />
<br />
|-<br />
| days<br />
| Integer<br />
| <br />
| The days for which a vacation text is returned<br />
<br />
|-<br />
| addresses<br />
| Array<br />
| <br />
| 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.<br />
<br />
|-<br />
| subject<br />
| String<br />
| <br />
| The new subject for the returned message (can be left empty, when only adding RE:)<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| The vacation text itself<br />
<br />
|}<br />
<center>''Table 22: Structure of vacation-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| addflags<br />
| A string defining the object itself<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| 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:<br />
* \seen<br />
* \answered<br />
* \flagged<br />
* \deleted<br />
* \draft<br />
* \recent<br />
System flags are case-insensitive.<br />
<br />
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<br />
"%()*\]{<br />
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.<br />
<br />
See RFC 3501 for further details on IMAP flags and their meanings.<br />
|}<br />
<center>''Table 23: Structure of addflags-command''</center><br />
<br />
= Requests =<br />
== Get the configuration of the mail filter backend ==<br />
<tt>GET /ajax/mailfilter?action=config</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Response body: An object describing the configuration like described in Table 24.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| An array containing test-objects like described in Table 25<br />
<br />
|-<br />
| actioncommands<br />
| Array<br />
| <br />
| An array containing the valid action commands as strings. A list of all possible values can be found in Table 15.<br />
<br />
|}<br />
<center>''Table 24: Config object''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| test<br />
| String<br />
| <br />
| 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.<br />
<br />
|-<br />
| comparison<br />
| Array<br />
| <br />
| 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 <br />
<br />
|}<br />
<center>''Table 25: Test object''</center><br />
<br />
== Get all mail filter rules ==<br />
<tt>GET /ajax/mailfilter?action=list</tt><br />
<br />
Parameters:<br />
<br />
* <tt>flag</tt> If given, only rules with this flag are returned<br />
* <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<br />
<br />
Response body: An array of rule objects like described in Table 1.<br />
<br />
== Create a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=new</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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<br />
<br />
Response body: An integer for the id of the new created rule.<br />
<br />
== Delete a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=delete</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Request body: An object with the field <tt>id</tt>.<br />
<br />
== Reorder mail filter rules ==<br />
PUT <tt>/ajax/mailfilter?action=reorder</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Request body: An array of unique ids which represents how the rule with the corresponding unique ids are ordered<br />
<br />
== Update a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=update</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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.<br />
<br />
== Delete the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=deletescript</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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.<br />
<br />
== Get the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=getscript</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Response body: A text of the complete sieve script<br />
<br />
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.</div>Schwaigerhttps://oxpedia.org/wiki/index.php?title=HTTP_API_MailFilter&diff=5358HTTP API MailFilter2010-02-11T12:03:03Z<p>Schwaiger: /* The core */</p>
<hr />
<div><center>'''Open-Xchange Mail Filter HTTP API'''</center><br />
<br />
= Introduction =<br />
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.<br />
<br />
= Module mailfilter =<br />
This module is used to access all mail filter related options.<br />
<br />
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.<br />
<br />
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 <tt>address</tt>, <tt>allof</tt> and <tt>anyof</tt>.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
= The core =<br />
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|outline #4.1.Tests]], and the actions, also represented in [[#Actions|outline 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.<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| Integer<br />
| <br />
| A unique identifier (once created must not be changed)<br />
<br />
|-<br />
| position<br />
| Integer<br />
| <br />
| The position inside the mail filter list. Starts with 0<br />
<br />
|-<br />
| rulename<br />
| String<br />
| <br />
| A name describing the rule, can be empty but must not contain a line break<br />
<br />
|-<br />
| active<br />
| Boolean<br />
| <br />
| If this rule is active or not<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| 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.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| The structure of the different test objects can be found in section [#4.1.Tests|outline 4.1.Tests]. The valid tests in the current setup can be found in the configuration object <br />
<br />
|-<br />
| actioncmds<br />
| Array<br />
| <br />
| An array of action objects whose different structures can be found in section [#4.2.Actions|outline 4.2.Actions]. The action commands which are valid here can be determined through the config object see Table 24<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing the whole lines of this command.<br />
<br />
|-<br />
| errormsg<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing a message why, or what part of the rule isn't known<br />
<br />
|}<br />
<center>''Table 1: Structure of a rule''</center><br />
<br />
= The dynamical part =<br />
== Tests ==<br />
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.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| address<br />
| 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.<br />
<br />
|-<br />
| envelope<br />
| 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'''.'''<br />
<br />
|-<br />
| true<br />
| A test for a true result (can be used if an action command should be executed every time)'''.'''<br />
<br />
|-<br />
| not<br />
| Negates a given test'''.'''<br />
<br />
|-<br />
| size<br />
| Deals with the size of the mail'''.'''<br />
<br />
|-<br />
| header<br />
| 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.<br />
<br />
|-<br />
| body<br />
| Tests against the content of a mail.<br />
<br />
|-<br />
| allof<br />
| Defines an AND condition between several tests'''.'''<br />
<br />
|-<br />
| anyof<br />
| Defines an OR condition between several tests'''.'''<br />
<br />
|}<br />
<center>''Table 2: List of all possible tests''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| If a field is equal to a given value<br />
<br />
|-<br />
| contains<br />
| If a field contains a given value at any position<br />
<br />
|-<br />
| matches<br />
| 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.<br />
<br />
|-<br />
| regex<br />
| Tests if a given regular expression matches with the value present in the specified field.<br />
<br />
|-<br />
| user<br />
| Tests if the user part of an e-mail address is the value given here. This means in [mailto:herbert+mustermann@example.com herbert+mustermann@example.com]. The user checks the part herbert.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|-<br />
| detail<br />
| Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|}<br />
<center>''Table 3: List of all possible comparisons''</center><br />
<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| address<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 4: Structure of address-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| envelope<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 5: Structure of envelope-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| true<br />
| A string describing the test command.<br />
<br />
|}<br />
<center>''Table 6: Structure of true-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| not<br />
| A string describing the test command.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| One of the test objects which result will be negated<br />
<br />
|}<br />
<center>''Table 7: Structure of not-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| size<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only two types are valid here. A description can be found in .<br />
<br />
|-<br />
| size<br />
| Number<br />
| <br />
| A number specifying the size for this comparison, in bytes.<br />
<br />
|}<br />
<center>''Table 8: Structure of size-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| over<br />
| Used in the size test to check for a value greater than the given one<br />
<br />
|-<br />
| under<br />
| Used in the size test to check for a value less than the given one<br />
<br />
|}<br />
<center>''Table 9: Types of comparison for size''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| header<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25)<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 10: Structure of header-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| body<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| extensionskey<br />
| String<br />
| <br />
| The extension key can be one of the value found in Table 12<br />
<br />
|-<br />
| extensionsvalue<br />
| String<br />
| <br />
| A value for the given key. If the key has no value (see Table 12 for this information) the value given here is ignored<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the body<br />
<br />
|}<br />
<center>''Table 11: Structure of body-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| content<br />
| 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.<br />
<br />
|-<br />
| text<br />
| 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<br />
<br />
|}<br />
<center>''Table 12: List of possible extensions''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| allof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 13: Structure of allof-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| anyof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 14: Structure of anyof-test''</center><br />
<br />
== Actions ==<br />
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.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| keep<br />
| Keeps a mail non changed<br />
<br />
|-<br />
| discard<br />
| Discards a mail without any processing<br />
<br />
|-<br />
| redirect<br />
| Redirects a mail to a given e-mail address<br />
<br />
|-<br />
| move<br />
| 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.<br />
<br />
|-<br />
| reject<br />
| Rejects the mail with a given text<br />
<br />
|-<br />
| stop<br />
| Stops any further progressing of a mail<br />
<br />
|-<br />
| vacation<br />
| Creates a vacation mail<br />
<br />
|-<br />
| addflags<br />
| Adds flags to a mail<br />
<br />
|}<br />
<center>''Table 15: List of possible action commands''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| keep<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 16: Structure of keep-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| discard<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 17: Structure of discard-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| redirect<br />
| A string defining the object itself<br />
<br />
|-<br />
| to<br />
| String<br />
| <br />
| A string containing where the mail should be redirected to<br />
<br />
|}<br />
<center>''Table 18: Structure of redirect-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| move<br />
| A string defining the object itself<br />
<br />
|-<br />
| into<br />
| String<br />
| <br />
| This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware<br />
<br />
|}<br />
<center>''Table 19: Structure of move-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| reject<br />
| A string defining the object itself<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| A string containing the reason why the mail is rejected<br />
<br />
|}<br />
<center>''Table 20: Structure of reject-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| stop<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 21: Structure of stop-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| vacation<br />
| A string defining the object itself<br />
<br />
|-<br />
| days<br />
| Integer<br />
| <br />
| The days for which a vacation text is returned<br />
<br />
|-<br />
| addresses<br />
| Array<br />
| <br />
| 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.<br />
<br />
|-<br />
| subject<br />
| String<br />
| <br />
| The new subject for the returned message (can be left empty, when only adding RE:)<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| The vacation text itself<br />
<br />
|}<br />
<center>''Table 22: Structure of vacation-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| addflags<br />
| A string defining the object itself<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| 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:<br />
* \seen<br />
* \answered<br />
* \flagged<br />
* \deleted<br />
* \draft<br />
* \recent<br />
System flags are case-insensitive.<br />
<br />
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<br />
"%()*\]{<br />
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.<br />
<br />
See RFC 3501 for further details on IMAP flags and their meanings.<br />
|}<br />
<center>''Table 23: Structure of addflags-command''</center><br />
<br />
= Requests =<br />
== Get the configuration of the mail filter backend ==<br />
<tt>GET /ajax/mailfilter?action=config</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Response body: An object describing the configuration like described in Table 24.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| An array containing test-objects like described in Table 25<br />
<br />
|-<br />
| actioncommands<br />
| Array<br />
| <br />
| An array containing the valid action commands as strings. A list of all possible values can be found in Table 15.<br />
<br />
|}<br />
<center>''Table 24: Config object''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| test<br />
| String<br />
| <br />
| 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.<br />
<br />
|-<br />
| comparison<br />
| Array<br />
| <br />
| 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 <br />
<br />
|}<br />
<center>''Table 25: Test object''</center><br />
<br />
== Get all mail filter rules ==<br />
<tt>GET /ajax/mailfilter?action=list</tt><br />
<br />
Parameters:<br />
<br />
* <tt>flag</tt> If given, only rules with this flag are returned<br />
* <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<br />
<br />
Response body: An array of rule objects like described in Table 1.<br />
<br />
== Create a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=new</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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<br />
<br />
Response body: An integer for the id of the new created rule.<br />
<br />
== Delete a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=delete</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Request body: An object with the field <tt>id</tt>.<br />
<br />
== Reorder mail filter rules ==<br />
PUT <tt>/ajax/mailfilter?action=reorder</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Request body: An array of unique ids which represents how the rule with the corresponding unique ids are ordered<br />
<br />
== Update a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=update</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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.<br />
<br />
== Delete the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=deletescript</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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.<br />
<br />
== Get the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=getscript</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Response body: A text of the complete sieve script<br />
<br />
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.</div>Schwaigerhttps://oxpedia.org/wiki/index.php?title=HTTP_API_MailFilter&diff=5357HTTP API MailFilter2010-02-11T12:01:51Z<p>Schwaiger: /* The core */</p>
<hr />
<div><center>'''Open-Xchange Mail Filter HTTP API'''</center><br />
<br />
= Introduction =<br />
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.<br />
<br />
= Module mailfilter =<br />
This module is used to access all mail filter related options.<br />
<br />
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.<br />
<br />
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 <tt>address</tt>, <tt>allof</tt> and <tt>anyof</tt>.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
= The core =<br />
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|outline #4.1.Tests]], and the actions, also represented in [[#4.2.Actions|outline 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.<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| Integer<br />
| <br />
| A unique identifier (once created must not be changed)<br />
<br />
|-<br />
| position<br />
| Integer<br />
| <br />
| The position inside the mail filter list. Starts with 0<br />
<br />
|-<br />
| rulename<br />
| String<br />
| <br />
| A name describing the rule, can be empty but must not contain a line break<br />
<br />
|-<br />
| active<br />
| Boolean<br />
| <br />
| If this rule is active or not<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| 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.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| The structure of the different test objects can be found in section [#4.1.Tests|outline 4.1.Tests]. The valid tests in the current setup can be found in the configuration object <br />
<br />
|-<br />
| actioncmds<br />
| Array<br />
| <br />
| An array of action objects whose different structures can be found in section [#4.2.Actions|outline 4.2.Actions]. The action commands which are valid here can be determined through the config object see Table 24<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing the whole lines of this command.<br />
<br />
|-<br />
| errormsg<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing a message why, or what part of the rule isn't known<br />
<br />
|}<br />
<center>''Table 1: Structure of a rule''</center><br />
<br />
= The dynamical part =<br />
== Tests ==<br />
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.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| address<br />
| 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.<br />
<br />
|-<br />
| envelope<br />
| 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'''.'''<br />
<br />
|-<br />
| true<br />
| A test for a true result (can be used if an action command should be executed every time)'''.'''<br />
<br />
|-<br />
| not<br />
| Negates a given test'''.'''<br />
<br />
|-<br />
| size<br />
| Deals with the size of the mail'''.'''<br />
<br />
|-<br />
| header<br />
| 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.<br />
<br />
|-<br />
| body<br />
| Tests against the content of a mail.<br />
<br />
|-<br />
| allof<br />
| Defines an AND condition between several tests'''.'''<br />
<br />
|-<br />
| anyof<br />
| Defines an OR condition between several tests'''.'''<br />
<br />
|}<br />
<center>''Table 2: List of all possible tests''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| If a field is equal to a given value<br />
<br />
|-<br />
| contains<br />
| If a field contains a given value at any position<br />
<br />
|-<br />
| matches<br />
| 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.<br />
<br />
|-<br />
| regex<br />
| Tests if a given regular expression matches with the value present in the specified field.<br />
<br />
|-<br />
| user<br />
| Tests if the user part of an e-mail address is the value given here. This means in [mailto:herbert+mustermann@example.com herbert+mustermann@example.com]. The user checks the part herbert.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|-<br />
| detail<br />
| Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|}<br />
<center>''Table 3: List of all possible comparisons''</center><br />
<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| address<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 4: Structure of address-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| envelope<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 5: Structure of envelope-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| true<br />
| A string describing the test command.<br />
<br />
|}<br />
<center>''Table 6: Structure of true-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| not<br />
| A string describing the test command.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| One of the test objects which result will be negated<br />
<br />
|}<br />
<center>''Table 7: Structure of not-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| size<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only two types are valid here. A description can be found in .<br />
<br />
|-<br />
| size<br />
| Number<br />
| <br />
| A number specifying the size for this comparison, in bytes.<br />
<br />
|}<br />
<center>''Table 8: Structure of size-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| over<br />
| Used in the size test to check for a value greater than the given one<br />
<br />
|-<br />
| under<br />
| Used in the size test to check for a value less than the given one<br />
<br />
|}<br />
<center>''Table 9: Types of comparison for size''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| header<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25)<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 10: Structure of header-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| body<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| extensionskey<br />
| String<br />
| <br />
| The extension key can be one of the value found in Table 12<br />
<br />
|-<br />
| extensionsvalue<br />
| String<br />
| <br />
| A value for the given key. If the key has no value (see Table 12 for this information) the value given here is ignored<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the body<br />
<br />
|}<br />
<center>''Table 11: Structure of body-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| content<br />
| 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.<br />
<br />
|-<br />
| text<br />
| 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<br />
<br />
|}<br />
<center>''Table 12: List of possible extensions''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| allof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 13: Structure of allof-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| anyof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 14: Structure of anyof-test''</center><br />
<br />
== Actions ==<br />
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.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| keep<br />
| Keeps a mail non changed<br />
<br />
|-<br />
| discard<br />
| Discards a mail without any processing<br />
<br />
|-<br />
| redirect<br />
| Redirects a mail to a given e-mail address<br />
<br />
|-<br />
| move<br />
| 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.<br />
<br />
|-<br />
| reject<br />
| Rejects the mail with a given text<br />
<br />
|-<br />
| stop<br />
| Stops any further progressing of a mail<br />
<br />
|-<br />
| vacation<br />
| Creates a vacation mail<br />
<br />
|-<br />
| addflags<br />
| Adds flags to a mail<br />
<br />
|}<br />
<center>''Table 15: List of possible action commands''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| keep<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 16: Structure of keep-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| discard<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 17: Structure of discard-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| redirect<br />
| A string defining the object itself<br />
<br />
|-<br />
| to<br />
| String<br />
| <br />
| A string containing where the mail should be redirected to<br />
<br />
|}<br />
<center>''Table 18: Structure of redirect-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| move<br />
| A string defining the object itself<br />
<br />
|-<br />
| into<br />
| String<br />
| <br />
| This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware<br />
<br />
|}<br />
<center>''Table 19: Structure of move-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| reject<br />
| A string defining the object itself<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| A string containing the reason why the mail is rejected<br />
<br />
|}<br />
<center>''Table 20: Structure of reject-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| stop<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 21: Structure of stop-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| vacation<br />
| A string defining the object itself<br />
<br />
|-<br />
| days<br />
| Integer<br />
| <br />
| The days for which a vacation text is returned<br />
<br />
|-<br />
| addresses<br />
| Array<br />
| <br />
| 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.<br />
<br />
|-<br />
| subject<br />
| String<br />
| <br />
| The new subject for the returned message (can be left empty, when only adding RE:)<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| The vacation text itself<br />
<br />
|}<br />
<center>''Table 22: Structure of vacation-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| addflags<br />
| A string defining the object itself<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| 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:<br />
* \seen<br />
* \answered<br />
* \flagged<br />
* \deleted<br />
* \draft<br />
* \recent<br />
System flags are case-insensitive.<br />
<br />
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<br />
"%()*\]{<br />
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.<br />
<br />
See RFC 3501 for further details on IMAP flags and their meanings.<br />
|}<br />
<center>''Table 23: Structure of addflags-command''</center><br />
<br />
= Requests =<br />
== Get the configuration of the mail filter backend ==<br />
<tt>GET /ajax/mailfilter?action=config</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Response body: An object describing the configuration like described in Table 24.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| An array containing test-objects like described in Table 25<br />
<br />
|-<br />
| actioncommands<br />
| Array<br />
| <br />
| An array containing the valid action commands as strings. A list of all possible values can be found in Table 15.<br />
<br />
|}<br />
<center>''Table 24: Config object''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| test<br />
| String<br />
| <br />
| 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.<br />
<br />
|-<br />
| comparison<br />
| Array<br />
| <br />
| 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 <br />
<br />
|}<br />
<center>''Table 25: Test object''</center><br />
<br />
== Get all mail filter rules ==<br />
<tt>GET /ajax/mailfilter?action=list</tt><br />
<br />
Parameters:<br />
<br />
* <tt>flag</tt> If given, only rules with this flag are returned<br />
* <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<br />
<br />
Response body: An array of rule objects like described in Table 1.<br />
<br />
== Create a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=new</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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<br />
<br />
Response body: An integer for the id of the new created rule.<br />
<br />
== Delete a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=delete</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Request body: An object with the field <tt>id</tt>.<br />
<br />
== Reorder mail filter rules ==<br />
PUT <tt>/ajax/mailfilter?action=reorder</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Request body: An array of unique ids which represents how the rule with the corresponding unique ids are ordered<br />
<br />
== Update a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=update</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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.<br />
<br />
== Delete the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=deletescript</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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.<br />
<br />
== Get the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=getscript</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Response body: A text of the complete sieve script<br />
<br />
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.</div>Schwaigerhttps://oxpedia.org/wiki/index.php?title=HTTP_API_MailFilter&diff=5356HTTP API MailFilter2010-02-11T12:00:38Z<p>Schwaiger: /* The core */</p>
<hr />
<div><center>'''Open-Xchange Mail Filter HTTP API'''</center><br />
<br />
= Introduction =<br />
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.<br />
<br />
= Module mailfilter =<br />
This module is used to access all mail filter related options.<br />
<br />
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.<br />
<br />
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 <tt>address</tt>, <tt>allof</tt> and <tt>anyof</tt>.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
= The core =<br />
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|outline #4.1.Tests]], and the actions, also represented in [#4.2.Actions|outline 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.<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| Integer<br />
| <br />
| A unique identifier (once created must not be changed)<br />
<br />
|-<br />
| position<br />
| Integer<br />
| <br />
| The position inside the mail filter list. Starts with 0<br />
<br />
|-<br />
| rulename<br />
| String<br />
| <br />
| A name describing the rule, can be empty but must not contain a line break<br />
<br />
|-<br />
| active<br />
| Boolean<br />
| <br />
| If this rule is active or not<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| 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.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| The structure of the different test objects can be found in section [#4.1.Tests|outline 4.1.Tests]. The valid tests in the current setup can be found in the configuration object <br />
<br />
|-<br />
| actioncmds<br />
| Array<br />
| <br />
| An array of action objects whose different structures can be found in section [#4.2.Actions|outline 4.2.Actions]. The action commands which are valid here can be determined through the config object see Table 24<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing the whole lines of this command.<br />
<br />
|-<br />
| errormsg<br />
| String<br />
| <br />
| If this rule cannot be read in this string is filled containing a message why, or what part of the rule isn't known<br />
<br />
|}<br />
<center>''Table 1: Structure of a rule''</center><br />
<br />
= The dynamical part =<br />
== Tests ==<br />
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.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| address<br />
| 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.<br />
<br />
|-<br />
| envelope<br />
| 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'''.'''<br />
<br />
|-<br />
| true<br />
| A test for a true result (can be used if an action command should be executed every time)'''.'''<br />
<br />
|-<br />
| not<br />
| Negates a given test'''.'''<br />
<br />
|-<br />
| size<br />
| Deals with the size of the mail'''.'''<br />
<br />
|-<br />
| header<br />
| 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.<br />
<br />
|-<br />
| body<br />
| Tests against the content of a mail.<br />
<br />
|-<br />
| allof<br />
| Defines an AND condition between several tests'''.'''<br />
<br />
|-<br />
| anyof<br />
| Defines an OR condition between several tests'''.'''<br />
<br />
|}<br />
<center>''Table 2: List of all possible tests''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| is<br />
| If a field is equal to a given value<br />
<br />
|-<br />
| contains<br />
| If a field contains a given value at any position<br />
<br />
|-<br />
| matches<br />
| 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.<br />
<br />
|-<br />
| regex<br />
| Tests if a given regular expression matches with the value present in the specified field.<br />
<br />
|-<br />
| user<br />
| Tests if the user part of an e-mail address is the value given here. This means in [mailto:herbert+mustermann@example.com herbert+mustermann@example.com]. The user checks the part herbert.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|-<br />
| detail<br />
| Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann.<br />
<br />
'''Attention: '''This comparison can only be used in conjunction with the address test<br />
<br />
|}<br />
<center>''Table 3: List of all possible comparisons''</center><br />
<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| address<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 4: Structure of address-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| envelope<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 5: Structure of envelope-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| true<br />
| A string describing the test command.<br />
<br />
|}<br />
<center>''Table 6: Structure of true-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| not<br />
| A string describing the test command.<br />
<br />
|-<br />
| test<br />
| Object<br />
| <br />
| One of the test objects which result will be negated<br />
<br />
|}<br />
<center>''Table 7: Structure of not-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| size<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Only two types are valid here. A description can be found in .<br />
<br />
|-<br />
| size<br />
| Number<br />
| <br />
| A number specifying the size for this comparison, in bytes.<br />
<br />
|}<br />
<center>''Table 8: Structure of size-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| over<br />
| Used in the size test to check for a value greater than the given one<br />
<br />
|-<br />
| under<br />
| Used in the size test to check for a value less than the given one<br />
<br />
|}<br />
<center>''Table 9: Types of comparison for size''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| header<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25)<br />
<br />
|-<br />
| headers<br />
| Array<br />
| <br />
| A string array containing the header fields<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the value for the header fields<br />
<br />
|}<br />
<center>''Table 10: Structure of header-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| body<br />
| A string describing the test command.<br />
<br />
|-<br />
| comparison<br />
| String<br />
| <br />
| Available types can be found in the config object. (see Table 25).<br />
<br />
|-<br />
| extensionskey<br />
| String<br />
| <br />
| The extension key can be one of the value found in Table 12<br />
<br />
|-<br />
| extensionsvalue<br />
| String<br />
| <br />
| A value for the given key. If the key has no value (see Table 12 for this information) the value given here is ignored<br />
<br />
|-<br />
| values<br />
| Array<br />
| <br />
| A string array containing the values for the body<br />
<br />
|}<br />
<center>''Table 11: Structure of body-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| content<br />
| 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.<br />
<br />
|-<br />
| text<br />
| 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<br />
<br />
|}<br />
<center>''Table 12: List of possible extensions''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| allof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 13: Structure of allof-test''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| anyof<br />
| A string describing the test command.<br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| A array of tests<br />
<br />
|}<br />
<center>''Table 14: Structure of anyof-test''</center><br />
<br />
== Actions ==<br />
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.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Description</center><br />
<br />
|-<br />
| keep<br />
| Keeps a mail non changed<br />
<br />
|-<br />
| discard<br />
| Discards a mail without any processing<br />
<br />
|-<br />
| redirect<br />
| Redirects a mail to a given e-mail address<br />
<br />
|-<br />
| move<br />
| 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.<br />
<br />
|-<br />
| reject<br />
| Rejects the mail with a given text<br />
<br />
|-<br />
| stop<br />
| Stops any further progressing of a mail<br />
<br />
|-<br />
| vacation<br />
| Creates a vacation mail<br />
<br />
|-<br />
| addflags<br />
| Adds flags to a mail<br />
<br />
|}<br />
<center>''Table 15: List of possible action commands''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| keep<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 16: Structure of keep-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| discard<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 17: Structure of discard-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| redirect<br />
| A string defining the object itself<br />
<br />
|-<br />
| to<br />
| String<br />
| <br />
| A string containing where the mail should be redirected to<br />
<br />
|}<br />
<center>''Table 18: Structure of redirect-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| move<br />
| A string defining the object itself<br />
<br />
|-<br />
| into<br />
| String<br />
| <br />
| This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware<br />
<br />
|}<br />
<center>''Table 19: Structure of move-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| reject<br />
| A string defining the object itself<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| A string containing the reason why the mail is rejected<br />
<br />
|}<br />
<center>''Table 20: Structure of reject-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| stop<br />
| A string defining the object itself<br />
<br />
|}<br />
<center>''Table 21: Structure of stop-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| vacation<br />
| A string defining the object itself<br />
<br />
|-<br />
| days<br />
| Integer<br />
| <br />
| The days for which a vacation text is returned<br />
<br />
|-<br />
| addresses<br />
| Array<br />
| <br />
| 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.<br />
<br />
|-<br />
| subject<br />
| String<br />
| <br />
| The new subject for the returned message (can be left empty, when only adding RE:)<br />
<br />
|-<br />
| text<br />
| String<br />
| <br />
| The vacation text itself<br />
<br />
|}<br />
<center>''Table 22: Structure of vacation-command''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable" width="100%"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| id<br />
| String<br />
| addflags<br />
| A string defining the object itself<br />
<br />
|-<br />
| flags<br />
| Array<br />
| <br />
| 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:<br />
* \seen<br />
* \answered<br />
* \flagged<br />
* \deleted<br />
* \draft<br />
* \recent<br />
System flags are case-insensitive.<br />
<br />
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<br />
"%()*\]{<br />
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.<br />
<br />
See RFC 3501 for further details on IMAP flags and their meanings.<br />
|}<br />
<center>''Table 23: Structure of addflags-command''</center><br />
<br />
= Requests =<br />
== Get the configuration of the mail filter backend ==<br />
<tt>GET /ajax/mailfilter?action=config</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Response body: An object describing the configuration like described in Table 24.<br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| tests<br />
| Array<br />
| <br />
| An array containing test-objects like described in Table 25<br />
<br />
|-<br />
| actioncommands<br />
| Array<br />
| <br />
| An array containing the valid action commands as strings. A list of all possible values can be found in Table 15.<br />
<br />
|}<br />
<center>''Table 24: Config object''</center><br />
<br />
<br />
{| cellspacing="0" border="1" class="prettytable"<br />
! <center>Name</center><br />
! <center>Type</center><br />
! <center>Value</center><br />
! <center>Description</center><br />
<br />
|-<br />
| test<br />
| String<br />
| <br />
| 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.<br />
<br />
|-<br />
| comparison<br />
| Array<br />
| <br />
| 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 <br />
<br />
|}<br />
<center>''Table 25: Test object''</center><br />
<br />
== Get all mail filter rules ==<br />
<tt>GET /ajax/mailfilter?action=list</tt><br />
<br />
Parameters:<br />
<br />
* <tt>flag</tt> If given, only rules with this flag are returned<br />
* <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<br />
<br />
Response body: An array of rule objects like described in Table 1.<br />
<br />
== Create a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=new</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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<br />
<br />
Response body: An integer for the id of the new created rule.<br />
<br />
== Delete a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=delete</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Request body: An object with the field <tt>id</tt>.<br />
<br />
== Reorder mail filter rules ==<br />
PUT <tt>/ajax/mailfilter?action=reorder</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Request body: An array of unique ids which represents how the rule with the corresponding unique ids are ordered<br />
<br />
== Update a mail filter rule ==<br />
PUT <tt>/ajax/mailfilter?action=update</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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.<br />
<br />
== Delete the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=deletescript</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
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.<br />
<br />
== Get the whole script ==<br />
PUT <tt>/ajax/mailfilter?action=getscript</tt><br />
<br />
Parameters:<br />
<br />
* <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<br />
<br />
Response body: A text of the complete sieve script<br />
<br />
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.</div>Schwaiger