Introduction
This pages describes the HTTP API of the OX Middleware.
Low level protocol
The client accesses the server through HTTP GET, POST and PUT requests. HTTP cookies are used for authentication and must therefore be processed and sent back by the client as specified by RFC 6265. The HTTP API is accessible at URIs starting with /ajax
. Each server module has a unique name and its own sub-namespace with that name below /ajax
, e. g. all access to the module "tasks" is via URIs starting with /ajax/tasks
.
Text encoding is always UTF-8. Data is sent from the server to the client as text/javascript and interpreted by the client to obtain an ECMAScript object. The HTTP API uses only a small subset of the ECMAScript syntax. This subset is roughly described by the following BNF:
Value ::= "null" | Boolean | Number | String | Array | Object
Boolean ::= "true" | "false"
Number ::= see NumericLiteral in ECMA 262 3rd edition
String ::= \"([^"\n\\]|\\["\n\\])*\"
Array ::= "[]" | "[" Value ("," Value)* "]"
Object ::= "{}" | "{" Name ":" Value ("," Name ":" Value)* "}"
Name ::= [A-Fa-f][0-9A-Fa-f_]*
Numbers are the standard signed integer and floating point numbers. Strings can contain any character, except double quotes, newlines and backslashes, which must be escaped by a backslash. Control characters in strings (other than newline) are not supported. Whitespace is allowed between any two tokens. See JSON and ECMA 262, 3rd edition for the formal definition.
The response body consists of an object, which contains up to four fields as described in Response body. The field data contains the actual payload which is described in following chapters. The fields timestamp
, error
and error_params
are present when data objects are returned, if an error occurred and if the error message contains conversion specifiers, respectively. Following sections describe the contents of these fields in more detail.
data |
Value |
Payload of the response. |
timestamp |
Timestamp |
The latest timestamp of the returned data (see Updates). |
error |
String |
The translated error message. Present in case of errors. |
error_params |
Array |
As of 7.4.2: Empty JSON array. Before that: Parameters for the error message that would need to be replaced in the error string (in a printf-format style). |
error_id |
String |
Unique error identifier to help finding this error instance in the server logs. |
error_desc |
String |
The technical error message (always English) useful for debugging the problem. Might be the same as error message if there is no more information available |
code |
String |
Error code consisting of an upper-case module identifier and a four-digit message number, separated by a dash; e.g. "MSG-0012" |
error_stack |
Array |
If configured (see "com.openexchange.ajax.response.includeStackTraceOnError" in 'server.properties') this field provides the stack trace of associated Java exception represented as a JSON array |
categories |
String OR Array |
Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs. |
category |
Number |
Maintained for legacy reasons: The numeric representation of the first category. |
Data from the client to the server can be sent in several formats. Small amounts of data are sent as application/x-www-urlencoded
in query parameters in the request URI. For POST requests, some or all parameters may be sent in the request body instead of in the URI using any valid encoding for POST requests. Alternatively, some requests specify that data is sent as text/javascript
in the body of a PUT request. The format of the request body for PUT requests is the same as for sending data from the server to the client, except that the payload is sent directly, without being wrapped in another object.
When updating existing data, the client sends only fields that were modified. To explicitly delete a field, the field is sent with the value null. For fields of type String
, the empty string "" is equivalent to null
.
Error handling
If the session of the user times out, if the client doesn't send a session ID or if the session for the specified session ID can not be found then the server returns the above described response object, that contains an error code and an error message. If the request URI or the request body is malformed or incomplete then the server returns the reponse object with an error message, too. In case of internal server errors, especially Java exceptions, or if the server is down, it returns the HTTP status code 503, Service Unavailable. Other severe errors may return other HTTP status values.
Application errors, which can be caused by a user and are therefore expected during the operation of the groupware, are reported by setting the field error in the returned object, as described in Response body. Since the error messages are translated by the client, they can not be composed of multiple variable parts. Instead, the error message can contain simplified printf()-style conversion specifications, which are replaced by elements from the array in the field error_params
. If error_params
is not present, no replacement occurs, even if parts of the error message match the syntax of a conversion specification.
A simplified conversion specification, as used for error messages, is either of the form %s or %n$s_, where _n_ is a 1-based decimal parameter index. The conversion specifications are replaced from left to right by elements from `error_params`, starting at the first element. _%s_ is replaced by the current element and the current index is incremented. _%n$s is replaced by the n'th element and the current index is set to the (n + 1)'th element.
Some error message contain data sizes which must be expressed in Bytes or Kilobytes etc., depending on the actual value. Since the unit must be translated, this conversion is performed by the client. Unfortunately, standard printf()-style formatting does not have a specifier for this kind of translation. Therefore, the conversion specification for sizes is the same as for normal strings, and the client has to determine which parameters to translate based on the error code. The current error codes and the corresponding size parameters are listed below:
CON-0101 |
2, 3 |
FLS-0003 |
1, 2, 3 |
MSG-0065 |
1, 3 |
MSG-0066 |
1 |
NON-0005 |
1, 2 |
Date and time
Dates without time are transmitted as the number of milliseconds between 00:00 UTC on that date and 1970-01-01 00:00 UTC. Leap seconds are ignored, therefore this number is always an integer multiple of 8.64e7.
Because ECMAScript Date objects have no way to explicitly specify a timezone for calculations, timezone correction must be performed on the server. Dates with time are transmitted as the number of milliseconds since 1970-01-01 00:00 UTC (again, ignoring leap seconds) plus the offset between the user's timezone and UTC at the time in question. (See the Java method java.util.TimeZone.getOffset(long)). Unless optional URL parameter timezone
is present. Then dates with time are transmitted as the number of milliseconds since 1970-01-01 00:00 UTC (again, ignoring leap seconds) plus the offset between the specified timezone and UTC at the time in question.
For some date and time values, especially timestamps, monotonicity is more important than the actual value. Such values are transmitted as the number of milliseconds since 1970-01-01 00:00 UTC, ignoring leap seconds and without timezone correction. If possible, a unique strictly monotonic increasing value should be used instead, as it avoids some race conditions described below.
This specification refers to these three interpretations of the type Number as separate data types.
Date |
No |
UTC |
Date without time. |
Time |
Yes |
User |
Date and time. |
Timestamp |
Yes |
UTC |
Timestamp or unique sequence number. |
Updates
To allow efficient synchronization of a client with changes made by other clients and to detect conflicts, the server stores a timestamp of the last modification for each object. Whenever the server transmits data objects to the client, the response object described in Response body includes the field timestamp
. This field contains a timestamp value which is computed as the maximum of the timestamps of all transmitted objects.
When requesting updates to a previously retrieved set of objects, the client sends the last timestamp which belongs to that set of objects. The response contains all updates with timestamps greater than the one specified by the client. The field timestamp of the response contains the new maximum timestamp value.
If multiple different objects may have the same timestamp values, then a race condition exists when an update is processed between two such objects being modified. The first, already modified object will be included in the update response and its timestamp will be the maximum timestamp value sent in the timestamp field of the response. If the second object is modified later but gets the same timestamp, the client will never see the update to that object because the next update request from the client supplies the same timestamp value, but only modifications with greater timestamp values are returned.
If unique sequence numbers can't be used as timestamps, then the risk of the race condition can be at least minimized by storing timestamps in the most precise format and/or limiting update results to changes with timestamp values which are measurably smaller than the current timestamp value.
Editing
Editing objects is performed one object at a time. There may be multiple objects being edited by the same client simulataneously, but this is achieved by repeating the steps required for editing a single object. There is no batch edit or upload command.
To edit an object, a client first requests the entire object from the server. The server response contains the timestamp
field described in the previous section. For in-place editing inside a view of multiple objects, where only already retrieved fields can be changed, retrieving the entire object is not necessary, and the last timestamp of the view is used as the timestamp of each object in it.
When sending the modified object back to the server, only modified fields need to be included in the sent object. The request also includes the timestamp of the edited object. The timestamp is used by the server to ensure that the object was not edited by another client in the meantime. If the current timestamp of the object is greater than the timestamp supplied by the client, then a conflict is detected and the field error is set in the response. Otherwise, the object gets a new timestamp and the response to the client is empty.
If the client displays the edited object in a view together with other objects, then the client will need to perform an update of that view immediately after successfully uploading an edited object.
File uploads
File uploads are made by sending a POST request that submits both the file and the needed fields as parts of a request of content-type “multipart/form-data” or “multipart/mixed”. The file metadata are stored in a form field “file” (much like an <input type=”file” name=”file” />
would do). In general a call that allows file uploads via POST will have a corresponding call using PUT to send object data. The JSON-encoded object-data that is send as the body of a corresponding PUT call is, when performed as a POST with file uploads, put into the request parameter “json”.
Since the upload is performed directly by the browser and is not an Ajax call, the normal callback mechanism for asynchronous Javascript calls cannot be used to obtain the result. For this reason the server responds to these POST calls with a complete HTML page that performs the callback and should not be displayed to the user. The HTML response is functionally equivalent to:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<META http-equiv="Content-Type" content=\"text/html; charset=UTF-8\">
<script type="text/javascript">
(parent["callback_action"] || window.opener && window.opener["callback_action"])
({json})
</script>
</head>
</html>
The placeholders {json}
is replaced by the response with the timestamp that would be expected from the corresponding PUT method. The placeholder action
is replaced by the value of the parameter action
of the request (except for the import bundle, which is named "import" instead of the action name for legacy purposes). The content-type of the answer is text/html
.
Non-browser clients don't need to interpret HTML or JavaScript. The JSON data can be recognized by the outermost ({
and })
, where the inner braces are part of the JSON value. For example, the regular expression \((\{.*\})\)
captures the entire JSON value in its first capturing group.
Column identifiers
Below you find the identifiers for object fields of certain data objects (models) that can be used in the columns
parameter of a request to return specific field data of single or multiple objects.
Common object data
1 |
id |
String |
Object ID |
2 |
created_by |
String |
User ID of the user who created this object. |
3 |
modified_by |
String |
User ID of the user who last modified this object. |
4 |
creation_date |
Time |
Date and time of creation. |
5 |
last_modified |
Time |
Date and time of the last modification. |
20 |
folder_id |
String |
Object ID of the parent folder. |
100 |
categories |
String |
String containing comma separated the categories. Order is preserved. Changing the order counts as modification of the object. Not present in folder objects. |
101 |
private_flag |
Boolean |
Overrides folder permissions in shared private folders: When true, this object is not visible to anyone except the owner. Not present in folder objects. |
102 |
color_label |
Number |
Color number used by Outlook to label the object. The assignment of colors to numbers is arbitrary and specified by the client. The numbers are integer numbers between 0 and 10 (inclusive). Not present in folder objects. |
104 |
number_of_attachments |
Number |
Number of attachments |
105 |
lastModifiedOfNewestAttachmentUTC |
Time |
Date and time of the newest attachment written with UTC time zone. |
Permission object
bits |
Number |
For non-mail folders, a number as described in Permission flags. |
rights |
String |
For mail folders, the rights string as defined in RFC 2086. |
entity |
Number |
User ID of the user or group to which this permission applies (ignored for type "anonymous" or "guest"). |
group |
Boolean |
true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest"). |
type |
String |
The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined). |
password |
String |
An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) . |
email_address |
String |
The e-mail address of the recipient (for type "guest"). |
display_name |
String |
The display name of the recipient (for type "guest", optional). |
contact_id |
String |
The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional). |
contact_folder |
String |
The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set). |
expiry_date |
Time |
The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional). |
Extended permission object
entity |
Number |
Identifier of the permission entity (i.e. user-, group- or guest-ID). |
bits |
Number |
A number as described in Permission flags. |
type |
String |
"user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity. |
display_name |
String |
A display name for the permission entity. |
contact |
Object |
A (reduced) set of Detailed contact data for "user" and "guest" entities. |
share_url |
String |
The share link for "anonymous" entities. |
password |
String |
The optionally set password for "anonymous" entities. |
expiry_date |
Date |
The optionally set expiry date for "anonymous" entities. |
Common folder data
1 |
id |
String |
Object ID |
2 |
created_by |
String |
User ID of the user who created this object. |
3 |
modified_by |
String |
User ID of the user who last modified this object. |
4 |
creation_date |
Time |
Date and time of creation. |
5 |
last_modified |
Time |
Date and time of the last modification. |
6 |
last_modified_utc |
Timestamp |
Timestamp of the last modification. Note that the type is Timestamp, not Time. See Date and time for details. (added 2008-10-17, with SP5, temporary workaround) |
20 |
folder_id |
String |
Object ID of the parent folder. |
Detailed folder data
300 |
title |
String |
Name of this folder. |
301 |
module |
String |
Name of the module which implements this folder; e.g. "tasks", "calendar", "contacts", "infostore", or "mail" |
302 |
type |
Number |
See Type of folder |
304 |
subfolders |
Boolean |
true if this folder has subfolders. |
305 |
own_rights |
Number or String |
Permissions which apply to the current user, as described either in Permission flags or in RFC 2086. |
306 |
permissions |
Array |
Each element is an object described in Permission object. |
307 |
summary |
String |
Information about contained objects. |
308 |
standard_folder |
Boolean |
Indicates whether or not folder is marked as a default folder (only OX folder) |
309 |
total |
Number |
The number of objects in this Folder. |
310 |
new |
Number |
The number of new objects in this Folder. |
311 |
unread |
Number |
The number of unread objects in this Folder. |
312 |
deleted |
Number |
The number of deleted objects in this Folder. |
313 |
capabilities |
Number |
Bit mask containing information about mailing system capabilites, as described in capabilities. |
314 |
subscribed |
Boolean |
Indicates whether this folder should appear in folder tree or not. Note: Standard folders cannot be unsubscribed. |
315 |
subscr_subflds |
Boolean |
Indicates whether subfolders should appear in folder tree or not. |
316 |
standard_folder_type |
Number |
Indicates the default folder type. Zero for non-default folder. See Standard folder types |
317 |
supported_capabilities |
Array |
Each element is a String identifying a supported folder capability as described in supported capabilities. Only applicable for non-mail folders. Read Only, Since 7.4.0. |
318 |
account_id |
String |
Will be null if the folder does not belong to any account (i.e. if its module doesn't support multiple accounts), is a virtual folder or an account-agnostic system folder. Since 7.8.0. |
319 |
folder_name |
String |
The raw and therefore untranslated name of this folder |
3010 |
com.openexchange.publish.publicationFlag |
Boolean |
Indicates whether this folder is published. Read Only, provided by the com.openexchange.publish plugin, since 6.14. |
3020 |
com.openexchange.subscribe.subscriptionFlag |
Boolean |
Indicates whether this folder has subscriptions storing their content in this folder. Read Only, provided by the com.openexchange.subscribe plugin, since 6.14. |
3030 |
com.openexchange.folderstorage.displayName |
String |
Provides the display of the folder's owner. Read Only, Since 6.20. |
3060 |
com.openexchange.share.extendedPermissions |
Array |
Each element is an object described in Extended permission object. Read Only, Since 7.8.0. |
Type of folder
1 |
private |
2 |
public |
3 |
shared |
5 |
system folder |
7 |
This type is no more in use (legacy type). Will be removed with a future update! |
16 |
trash |
20 |
pictures |
21 |
documents |
22 |
music |
23 |
videos |
24 |
templates |
Detailed task and appointment data
200 |
title |
String |
Short description. |
201 |
start_date |
Date or Time |
Inclusive start of the event as Date for tasks and whole day appointments and Time for normal appointments. For sequencies, this date must be part of the sequence, i. e. sequencies always start at this date. (deprecated for tasks since v7.6.1, replaced by start_time and full_time) |
202 |
end_date |
Date or Time |
Exclusive end of the event as Date for tasks and whole day appointments and as Time for normal appointments. (deprecated for tasks since v7.6.1, replaced by end_time and full_time) |
203 |
note |
String |
Long description. |
204 |
alarm |
Number |
or Time Specifies when to notify the participants as the number of minutes before the start of the appointment (-1 for "no alarm"). For tasks, the Time value specifies the absolute time when the user should be notified.| |
209 |
recurrence_type |
Number |
Specifies the type of the recurrence for a task sequence. See Task sequence type |
212 |
days |
Number |
Specifies which days of the week are part of a sequence. The value is a bitfield with bit 0 indicating sunday, bit 1 indicating monday and so on. May be present if recurrence_type > 1. If allowed but not present, the value defaults to 127 (all 7 days). |
213 |
day_in_month |
Number |
Specifies which day of a month is part of the sequence. Counting starts with 1. If the field "days" is also present, only days selected by that field are counted. If the number is bigger than the number of available days, the last available day is selected. Present if and only if recurrence_type > 2. |
214 |
month |
Number |
Month of the year in yearly sequencies. 0 represents January, 1 represents February and so on. Present if and only if recurrence_type = 4. |
215 |
interval |
Number |
Specifies an integer multiplier to the interval specified by recurrence_type. Present if and only if recurrence_type > 0. Must be 1 if recurrence_type = 4. |
216 |
until |
Date |
Inclusive end date of a sequence. May be present only if recurrence_type > 0. The sequence has no end date if recurrence_type > 0 and this field is not present. Note: since this is a Date, the entire day after the midnight specified by the value is included. |
217 |
notification |
Boolean |
If true, all participants are notified of any changes to this object. This flag is valid for the current change only, i. e. it is not stored in the database and is never sent by the server to the client. |
220 |
participants |
Array |
Each element identifies a participant, user, group or booked resource as described in Participant identifier. |
221 |
users |
Array |
Each element represents a participant as described in User participant object. User groups are resolved and are represented by their members. Any user can occur only once. |
222 |
occurrences |
Number |
Specifies how often a recurrence should appear. May be present only if recurrence_type > 0. |
223 |
uid |
String |
Can only be written when the object is created. Internal and external globally unique identifier of the appointment or task. Is used to recognize appointments within iCal files. If this attribute is not written it contains an automatic generated UUID. |
224 |
organizer |
String |
Contains the email address of the appointment organizer which is not necessarily an internal user. Not implemented for tasks. |
225 |
sequence |
Number |
iCal sequence number. Not implemented for tasks. Must be incremented on update. Will be incremented by the server, if not set. |
226 |
confirmations |
Array |
Each element represents a confirming participant as described in Confirming participant. This can be internal and external user. Not implemented for tasks. |
227 |
organizerId |
Number |
Contains the userId of the appointment organizer if it is an internal user. Not implemented for tasks. (Introduced with 6.20.1) |
228 |
principal |
String |
Contains the email address of the appointment principal which is not necessarily an internal user. Not implemented for tasks. (Introduced with 6.20.1) |
229 |
principalId |
Number |
Contains the userId of the appointment principal if it is an internal user. Not implemented for tasks. (Introduced with 6.20.1) |
401 |
full_time |
Boolean |
True if the event is a whole day appointment or task, false otherwise. |
Task sequence type
0 |
none (single event) |
1 |
daily |
2 |
weekly |
3 |
monthly |
4 |
yearly |
Participant identifier
id |
Number |
User ID |
type |
Number |
See Participant types |
mail |
String |
mail address of an external participant |
Participant types
1 |
user |
2 |
user group |
3 |
resource |
4 |
resource group |
5 |
external user |
User participant object
id |
Number |
User ID. Confirming for other users only works for appointments and not for tasks. |
display_name |
String |
Displayable name of the participant. |
confirmation |
Number |
See Confirmation status |
confirmmessage |
String |
Confirm Message of the participant |
Confirmation status
0 |
none |
1 |
accepted |
2 |
declined |
3 |
tentative |
Confirming participant
type |
Number |
Either 1 = user or 5 = external user. |
mail |
String |
email address of external participant |
display_name |
String |
display name of external participant |
status |
Number |
See Confirmation status |
message |
String |
Confirm Message of the participant |
Detailed task data
300 |
status |
Number |
Status of the task. See Task status |
301 |
percent_completed |
Number |
How much of the task is completed. An integer number between 0 and 100. |
302 |
actual_costs |
Number |
A monetary attribute to store actual costs of a task. Allowed values must be in the range -9999999999.99 and 9999999999.99. |
303 |
actual_duration |
|
|
304 |
after_complete |
Date |
Deprecated. Only present in AJAX interface. Value will not be stored on OX server. |
305 |
billing_information |
|
|
307 |
target_costs |
Number |
A monetary attribute to store target costs of a task. Allowed values must be in the range -9999999999.99 and 9999999999.99. |
308 |
target_duration |
|
|
309 |
priority |
Number |
1 = LOW, 2 = MEDIUM, 3 = HIGH |
312 |
currency |
|
|
313 |
trip_meter |
|
|
314 |
companies |
|
|
315 |
date_completed |
|
|
316 |
start_time |
Date or Time |
Inclusive start as Date for whole day tasks and Time for normal tasks. |
317 |
end_time |
Date or Time |
Exclusive end as Date for whole day tasks and as Time for normal tasks. |
Task status
1 |
not started |
2 |
in progress |
3 |
done |
4 |
waiting |
5 |
deferred |
223 |
|
uid |
String |
Can only be written when the object is created. Internal and external globally unique identifier of the contact. Is used to recognize contacts within vCard files. If this attribute is not written it contains an automatic generated UUID. |
500 |
Display name |
display_name |
String |
|
501 |
Given name |
first_name |
String |
First name. |
502 |
Sur name |
last_name |
String |
Last name. |
503 |
Middle name |
second_name |
String |
|
504 |
Suffix |
suffix |
String |
|
505 |
Title |
title |
String |
|
506 |
Street home |
street_home |
String |
|
507 |
Postal code home |
postal_code_home |
String |
|
508 |
City home |
city_home |
String |
|
509 |
State home |
state_home |
String |
|
510 |
Country home |
country_home |
String |
|
511 |
Birthday |
birthday |
Date |
|
512 |
Marital status |
marital_status |
String |
|
513 |
Number of children |
number_of_children |
String |
|
514 |
Profession |
profession |
String |
|
515 |
Nickname |
nickname |
String |
|
516 |
Spouse name |
spouse_name |
String |
|
517 |
Anniversary |
anniversary |
Date |
|
518 |
Note |
note |
String |
|
519 |
Department |
department |
String |
|
520 |
Position |
position |
String |
|
521 |
Employee type |
employee_type |
String |
|
522 |
Room number |
room_number |
String |
|
523 |
Street business |
street_business |
String |
|
524 |
Internal user id |
user_id |
Number |
|
525 |
Postal code business |
postal_code_business |
String |
|
526 |
City business |
city_business |
String |
|
527 |
State business |
state_business |
String |
|
528 |
Country business |
country_business |
String |
|
529 |
Number of employee |
number_of_employees |
String |
|
530 |
Sales volume |
sales_volume |
String |
|
531 |
Tax id |
tax_id |
String |
|
532 |
Commercial register |
commercial_register |
String |
|
533 |
Branches |
branches |
String |
|
534 |
Business category |
business_category |
String |
|
535 |
Info |
info |
String |
|
536 |
Manager's name |
manager_name |
String |
|
537 |
Assistant's name |
assistant_name |
String |
|
538 |
Street other |
street_other |
String |
|
539 |
City other |
city_other |
String |
|
540 |
Postal code other |
postal_code_other |
String |
|
541 |
Country other |
country_other |
String |
|
542 |
Telephone business 1 |
telephone_business1 |
String |
|
543 |
Telephone business 2 |
telephone_business2 |
String |
|
544 |
FAX business |
fax_business |
String |
|
545 |
Telephone callback |
telephone_callback |
String |
|
546 |
Telephone car |
telephone_car |
String |
|
547 |
Telephone company |
telephone_company |
String |
|
548 |
Telephone home 1 |
telephone_home1 |
String |
|
549 |
Telephone home 2 |
telephone_home2 |
String |
|
550 |
FAX home |
fax_home |
String |
|
551 |
Cellular telephone 1 |
cellular_telephone1 |
String |
|
552 |
Cellular telephone 2 |
cellular_telephone2 |
String |
|
553 |
Telephone other |
telephone_other |
String |
|
554 |
FAX other |
fax_other |
String |
|
555 |
Email 1 |
email1 |
String |
|
556 |
Email 2 |
email2 |
String |
|
557 |
Email 3 |
email3 |
String |
|
558 |
URL |
url |
String |
|
559 |
Telephone ISDN |
telephone_isdn |
String |
|
560 |
Telephone pager |
telephone_pager |
String |
|
561 |
Telephone primary |
telephone_primary |
String |
|
562 |
Telephone radio |
telephone_radio |
String |
|
563 |
Telephone telex |
telephone_telex |
String |
|
564 |
Telephone TTY/TDD |
telephone_ttytdd |
String |
|
565 |
Instantmessenger 1 |
instant_messenger1 |
String |
|
566 |
Instantmessenger 2 |
instant_messenger2 |
String |
|
567 |
Telephone IP |
telephone_ip |
String |
|
568 |
Telephone assistant |
telephone_assistant |
String |
|
569 |
Company |
company |
String |
|
570 |
|
image1 |
String |
|
571 |
Dynamic Field 1 |
userfield01 |
String |
|
572 |
Dynamic Field 2 |
userfield02 |
String |
|
573 |
Dynamic Field 3 |
userfield03 |
String |
|
574 |
Dynamic Field 4 |
userfield04 |
String |
|
575 |
Dynamic Field 5 |
userfield05 |
String |
|
576 |
Dynamic Field 6 |
userfield06 |
String |
|
577 |
Dynamic Field 7 |
userfield07 |
String |
|
578 |
Dynamic Field 8 |
userfield08 |
String |
|
579 |
Dynamic Field 9 |
userfield09 |
String |
|
580 |
Dynamic Field 10 |
userfield10 |
String |
|
581 |
Dynamic Field 11 |
userfield11 |
String |
|
582 |
Dynamic Field 12 |
userfield12 |
String |
|
583 |
Dynamic Field 13 |
userfield13 |
String |
|
584 |
Dynamic Field 14 |
userfield14 |
String |
|
585 |
Dynamic Field 15 |
userfield15 |
String |
|
586 |
Dynamic Field 16 |
userfield16 |
String |
|
587 |
Dynamic Field 17 |
userfield17 |
String |
|
588 |
Dynamic Field 18 |
userfield18 |
String |
|
589 |
Dynamic Field 19 |
userfield19 |
String |
|
590 |
Dynamic Field 20 |
userfield20 |
String |
Contains a UUID if one was assigned (after 6.18.2) |
592 |
|
distribution_list |
Array |
If this contact is a distribution list, then this field is an array of objects. Each object describes a member of the list as defined in Distribution list member. |
594 |
Number of distributionlists |
number_of_distribution_list |
Number |
|
596 |
|
number_of_images |
Number |
|
597 |
|
image_last_modified |
Timestamp |
|
598 |
State other |
state_other |
String |
|
599 |
|
file_as |
String |
|
601 |
|
image1_content_type |
String |
|
602 |
|
mark_as_distributionlist |
Boolean |
|
605 |
Default address |
default_address |
Number |
|
606 |
|
image1_url |
String |
|
608 |
|
useCount |
Number |
In case of sorting purposes the column 609 is also available, which places global address book contacts at the beginning of the result. If 609 is used, the order direction (ASC, DESC) is ignored. |
616 |
|
yomiFirstName |
String |
Kana based representation for the First Name. Commonly used in japanese environments for searchin/sorting issues. (since 6.20) |
617 |
|
yomiLastName |
String |
Kana based representation for the Last Name. Commonly used in japanese environments for searchin/sorting issues. (since 6.20) |
618 |
|
yomiCompany |
String |
Kana based representation for the Company. Commonly used in japanese environments for searchin/sorting issues. (since 6.20) |
619 |
|
addressHome |
String |
Support for Outlook 'home' address field. (since 6.20.1) |
620 |
|
addressBusiness |
String |
Support for Outlook 'business' address field. (since 6.20.1) |
621 |
|
addressOther |
String |
Support for Outlook 'other' address field. (since 6.20.1) |
Distribution list member
id |
String |
Object ID of the member's contact if the member is an existing contact. |
folder_id |
String |
Parent folder ID of the member's contact if the member is an existing contact (preliminary, from 6.22 on). |
display_name |
String |
Display name |
mail |
String |
Email address (mandatory before 6.22, afterwards optional if you are referring to an internal contact) |
mail_field |
Number |
Which email field of an existing contact (if any) is used for the mail field. See Mail fields. |
Mail fields
0 |
independent contact |
1 |
default email field (email1) |
2 |
second email field (email2) |
3 |
third email field (email3) |
Detailed appointment data
206 |
recurrence_id |
Number |
Object ID of the entire appointment sequence. Present on series and change exception appointments. Equals to object identifier on series appointment and is different to object identifier on change exceptions. |
207 |
recurrence_position |
Number |
1-based position of an individual appointment in a sequence. Present if and only if recurrence_type > 0. |
208 |
recurrence_date_position |
Date |
Date of an individual appointment in a sequence. Present if and only if recurrence_type > 0. |
210 |
change_exceptions |
Array |
An array of Dates, representing all change exceptions of a sequence. |
211 |
delete_exceptions |
Array |
An array of Dates, representing all delete exceptions of a sequence. |
400 |
location |
String |
Location |
402 |
shown_as |
Number |
Describes, how this appointment appears in availability queries. See Appointment availability |
408 |
timezone |
String |
Timezone |
410 |
recurrence_start |
Date |
Start of a sequence without time |
|
ignore_conflicts |
Boolean |
Ignore soft conflicts for the new or modified appointment. This flag is valid for the current change only, i. e. it is not stored in the database and is never sent by the server to the client. |
Appointment availability
1 |
reserved |
2 |
temporary |
3 |
absent |
4 |
free |
Detailed mail data
102 |
color_label |
Number |
Color number used by Outlook to label the object. The assignment of colors to numbers is arbitrary and specified by the client. The numbers are integer numbers between 0 and 10 (inclusive). |
600 |
id |
String |
Object ID |
601 |
folder_id |
String |
Object ID of the parent folder |
602 |
attachment |
Boolean |
Specifies whether this mail has attachments. |
603 |
from |
Array |
Each element is a two-element array specifying one sender. The first element of each address is the personal name, the second element is the email address. Missing address parts are represented by null values. |
604 |
to |
Array |
Each element is a two-element array (see the from field) specifying one receiver. |
605 |
cc |
Array |
Each element is a two-element array (see the from field) specifying one carbon-copy receiver. |
606 |
bcc |
Array |
Each element is a two-element array (see the from field) specifying one blind carbon-copy receiver. |
607 |
subject |
String |
Subject line. |
608 |
size |
Number |
Size of the mail in bytes. |
609 |
sent_date |
Time |
Date and time as specified in the mail by the sending client. |
610 |
received_date |
Time |
Date and time as measured by the receiving server. |
611 |
flags |
Number |
Various system flags. A sum of zero or more of values described in Mail system flags. See javax.mail.Flags.Flag for details. |
612 |
level |
Number |
Zero-based nesting level in a thread. |
613 |
disp_notification_to |
String |
Content of message's header “Disposition-Notification-To” |
614 |
priority |
Number |
Value of message's “X-Priority” header. See X-Priority header. |
615 |
msg_ref |
String |
Message reference on reply/forward. |
651 |
flag_seen |
String |
Special field to sort mails by seen status |
652 |
account_name |
String |
Message's account name. |
653 |
account_id |
int |
Message's account identifier. Since v6.20.2 |
|
user |
Array |
An array with user-defined flags as strings. |
|
headers |
Object |
An object with a field for every non-standard header. The header name is the field name. The header value is the value of the field as string. |
|
attachments |
Array |
Each element is an attachment as described in Attachment. The first element is the mail text. If the mail has multiple representations (multipart-alternative), then the alternatives are placed after the mail text and have the field disp set to alternative. |
|
nested_msgs |
Array |
Each element is a mail object as described in this table, except for fields id, folder_id and attachment. |
|
truncated |
boolean |
true/false if the mail content was trimmed. Since v7.6.1 |
|
source |
String |
RFC822 source of the mail. Only present for action=get&attach_src=true |
|
cid |
String |
The value of the "Content-ID" header, if the header is present. |
654 |
original_id |
String |
The original mail identifier (e.g. if fetched from "virtual/all" folder). |
655 |
original_folder_id |
String |
The original folder identifier (e.g. if fetched from "virtual/all" folder). |
656 |
content_type |
String |
The Content-Type of a mail; e.g. multipart/mixed; boundary="-0123456abcdefg--". |
657 |
answered |
String |
Special field to sort mails by answered status. |
658 |
forwarded |
String |
Special field to sort mails by forwarded status. Note that mail service needs either support a system flag or a $Forwarded user flag |
659 |
draft |
String |
Special field to sort mails by draft flag. |
660 |
flagged |
String |
Special field to sort mails by flagged status. |
661 |
date |
String |
The date of a mail message. As configured, either the internal received date or mail's sent date (as given by "Date" header). Supposed to be the replacement for sent_date (609) or received_date (610) to let the Open-Xchange Middleware decide based on configuration for com.openexchange.mail.preferSentDate property what to consider. Supported at both - columns parameter and sort parameter. |
Mail system flags
1 |
answered |
2 |
deleted |
4 |
draft |
8 |
flagged |
16 |
recent |
32 |
seen |
64 |
user |
128 |
spam |
256 |
forwarded |
0 |
No priority |
5 |
Very Low |
4 |
Low |
3 |
Normal |
2 |
High |
1 |
Very High |
Attachment
id |
String |
Object ID (unique only inside the same message) |
content_type |
String |
MIME type |
content |
String |
Content as text. Present only if easily convertible to text. |
filename |
String |
Displayed filename (mutually exclusive with content). |
size |
Number |
Size of the attachment in bytes. |
disp |
String |
Attachment's disposition: null, inline, attachment or alternative. |
Detailed infoitem data
108 |
object_permissions |
Array |
Each element is an object described in Object Permission object (preliminary, available with 7.8.0). |
109 |
shareable |
Boolean |
(read-only) Indicates if the item can be shared (preliminary, available with 7.8.0). |
700 |
title |
String |
Title |
701 |
url |
String |
Link/URL |
702 |
filename |
String |
Displayed filename of the document. |
703 |
file_mimetype |
String |
MIME type of the document. The client converts known types to more readable names before displaying them. |
704 |
file_size |
Number |
Size of the document in bytes. |
705 |
version |
Number |
Version number of the document. New documents start at 1. Every update increments the version by 1. |
706 |
description |
String |
Description |
707 |
locked_until |
Time |
The time until which this item will presumably be locked. Only set if the document is currently locked, 0 otherwise. |
708 |
file_md5sum |
String |
MD5Sum of the document. Not yet implemented, so this is currently always empty. |
709 |
version_comment |
String |
A version comment is used to file a changelog for the file. |
710 |
current_version |
Boolean |
“true” if this version is the current version “false” otherwise. Note: This is not writeable |
711 |
number_of_versions |
Number |
The number of all versions of the infoitem. Note: This is not writeable. |
7010 |
com.openexchange.share.extendedObjectPermissions |
Array |
Each element is an object described in Extended object permission object. Read Only, Since 7.8.0. |
7020 |
com.openexchange.realtime.resourceID |
String |
The resource identifier for the infoitem for usage within the realtime component. Read Only, Since 7.8.0. |
7030 |
com.openexchange.file.storage.mail.mailMetadata |
Object |
Additional metadata for items in the mail file storage. Read Only. |
7040 |
com.openexchange.file.sanitizedFilename |
String |
A sanitized version of the filename. Which prevents end users from being confused by special characters, e.g. RTLO (0x202E). Read Only. |
Object Permission object
bits |
Number |
A number as described in Object Permission flags. |
entity |
Number |
User ID of the user or group to which this permission applies. |
group |
Boolean |
true if entity refers to a group, false if it refers to a user. |
type |
String |
The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined). |
password |
String |
An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) . |
email_address |
String |
The e-mail address of the recipient (for type "guest"). |
display_name |
String |
The display name of the recipient (for type "guest", optional). |
contact_id |
String |
The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional). |
contact_folder |
String |
The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set). |
expiry_date |
Time |
The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional). |
Extended object permission object
entity |
Number |
Identifier of the permission entity (i.e. user-, group- or guest-ID). |
bits |
Number |
A number as described in Object Permission flags. |
type |
String |
"user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity. |
display_name |
String |
A display name for the permission entity. |
contact |
Object |
A (reduced) set of Detailed contact data for "user" and "guest" entities. |
share_url |
String |
The share link for "anonymous" entities. |
password |
String |
The optionally set password for "anonymous" entities. |
expiry_date |
Date |
The optionally set expiry date for "anonymous" entities. |
Attachment object
800 |
folder |
Number |
The ID of the first Folder in which the attached object resides. |
801 |
attached |
Number |
The object id of the object this attachement is attached to. |
802 |
module |
Number |
The Module of this Object. Possible values are described in Attachment module |
803 |
filename |
String |
The filename of the attached file. |
804 |
file_size |
Number |
The file size (in bytes) of the attached file. |
805 |
file_mimetype |
String |
The MIME-Type of the attached file |
806 |
rft_flag |
Boolean |
If the attachment is a RTF Attachment of Outlook. (Outlook descriptions can be stored as RTF Documents). |
Attachment module
1 |
Appointment |
4 |
Task |
7 |
Contact |
137 |
Infostore |
Mail account data
1001 |
id |
Number |
Account ID |
1002 |
login |
String |
The login. |
1003 |
password |
String |
The (optional) password. |
1004 |
mail_url |
String |
The mail server URL; e.g. "imap://imap.somewhere.com:143". URL is preferred over single fields (like mail_server, mail_port, etc.) |
1005 |
transport_url |
String |
The transport server URL; e.g. "smtp://smtp.somewhere.com:25". URL is preferred over single fields (like transport_server, transport_port, etc.) |
1006 |
name |
String |
Account's display name. |
1007 |
primary_address |
String |
User's primary address in account; e.g. "someone@somewhere.com" |
1008 |
spam_handler |
String |
The name of the spam handler used by account. |
1009 |
trash |
String |
The name of the default trash folder. |
1010 |
sent |
String |
The name of the default sent folder. |
1011 |
drafts |
String |
The name of the default drafts folder. |
1012 |
spam |
String |
The name of the default spam folder. |
1013 |
confirmed_spam |
String |
The name of the default confirmed-spam folder. |
1014 |
confirmed_ham |
String |
The name of the default confirmed-ham folder. |
1015 |
mail_server |
String |
The mail server's hostname or IP address. |
1016 |
mail_port |
Number |
The mail server's port. |
1017 |
mail_protocol |
String |
The mail server's protocol. Always use basic protocol name. E.g. use "imap" instead of "imaps" |
1018 |
mail_secure |
Boolean |
Whether to establish a secure connection to mail server (SSL, TLS). |
1019 |
transport_server |
String |
The transport server's hostname or IP address. |
1020 |
transport_port |
Number |
The transport server's port. |
1021 |
transport_protocol |
String |
The transport server's protocol. Always use basic protocol name. E.g. use "smtp" instead of "smtps" |
1022 |
transport_secure |
Boolean |
Whether to establish a secure connection to transport server (SSL, TLS). |
1023 |
transport_login |
String |
The transport login. Please see "transport_auth" for the handling of this field. |
1024 |
transport_password |
String |
The transport password. Please see "transport_auth" for the handling of this field. |
1025 |
unified_inbox_enabled |
Boolean |
If enabled for Unified INBOX |
1026 |
trash_fullname |
String |
Path to default trash folder. Preferred over "trash" |
1027 |
sent_fullname |
String |
Path to default sent folder. Preferred over "sent" |
1028 |
drafts_fullname |
String |
Path to default drafts folder. Preferred over "drafts" |
1029 |
spam_fullname |
String |
Path to default spam folder. Preferred over "spam" |
1030 |
confirmed_spam_fullname |
String |
Path to default confirmed-spam folder. Preferred over "confirmed_spam" |
1031 |
confirmed_ham_fullname |
String |
Path to default confirmed-ham folder. Preferred over "confirmed_ham" |
1032 |
pop3_refresh_rate |
Number |
The interval in minutes the POP3 account is refreshed |
1033 |
pop3_expunge_on_quit |
Boolean |
Whether POP3 messages shall be deleted on actual POP3 account after retrieval or not |
1034 |
pop3_delete_write_through |
Boolean |
If option "pop3_expunge_on_quit" is disabled, this property defines whether a delete in local INBOX also deletes affected message in actual POP3 account |
1035 |
pop3_storage |
String |
The name of POP3 storage provider, default is "mailaccount" |
1036 |
pop3_path |
String |
Path to POP3's virtual root folder in storage, default is name of the POP3 account beside default folders |
1037 |
personal |
String |
The customizable personal part of email address |
1038 |
reply_to |
String |
The customizable reply-to email address |
1039 |
addresses |
String |
The comma-separated list of available E-Mail addresses including aliases. !! Only available for primary mail account !! |
1040 |
meta |
JSON |
data Stores arbitrary JSON data as specified by client associated with the mail account |
1041 |
archive |
String |
The name of the archive folder. Currently not functional! |
1042 |
archive_fullname |
String |
The full name of the archive folder. Currently not functional! |
1043 |
transport_auth |
String |
Available since v7.6.1 Specifies the source for mail transport (SMTP) credentials. See Credential source. |
1044 |
mail_starttls |
Boolean |
Available since v7.8.2 Whether to establish a secure connection to mail server via STARTTLS. |
1045 |
transport_starttls |
Boolean |
Available since v7.8.2 Whether to establish a secure connection to transport server via STARTTLS. |
1046 |
root_folder |
String |
Available since v7.8.3 Specifies the identifier of an account's root folder |
1047 |
mail_oauth |
Integer |
Available since v7.8.3 Specifies the identifier of the associated OAuth account for mail access |
1048 |
transport_oauth |
Integer |
Available since v7.8.3 Specifies the identifier of the associated OAuth account for mail transport |
Credential source
mail |
Signals to use the same credentials as given in associated mail store (IMAP, POP3). |
custom |
Signals that individual credentials are supposed to be used (fields "transport_login" and "transport_password" are considered). |
none |
Means the mail transport does not support any authentication mechanism (rare case!) |
Detailed user data
610 |
Aliases |
aliases |
Array |
The user's aliases |
611 |
Time zone |
timezone |
String |
The time zone ID. |
612 |
Locale |
locale |
String |
The name of user's entire locale, with the language, country and variant separated by underbars. E.g. "en", "de_DE" |
613 |
Groups |
groups |
Array |
The IDs of user's groups |
614 |
Contact ID |
contact_id |
Number |
The contact ID of the user |
615 |
Login info |
login_info |
String |
The user's login information |
616 |
Guest Created By |
guest_created_by |
Number |
The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0) |
Messaging message columns
id |
The id attribute |
folderId |
The folder attribute |
contentType |
The "Content-Type" header |
from |
The "From" header |
to |
The "To" header |
cc |
The "Cc" header |
bcc |
The "Bcc" header |
subject |
The "Subject" header |
size |
The size attribute |
sentDate |
The "Date" header |
receivedDate |
The receivedDate attribute |
flags |
The flags attribute |
threadLevel |
The threadLevel attribute |
dispositionNotificationTo |
The "Disposition-Notification-To" header. |
priority |
The "X-Priority" header |
colorLabel |
The colorLabel attribute |
url |
The url attribute |
body |
The content attribute |
headers |
The headers attribute |
picture |
The url to the message picture. |
Group data
1 |
id |
String |
Object ID |
5 |
last_modified |
Time |
Date and time of the last modification. |
700 |
name |
String |
The name of the group. |
701 |
display_name |
String |
The display name of the group. |
702 |
members |
String |
A comma separated list of user ids. |
Flags and bitmasks
Permission flags
0-6 |
Folder permissions: |
|
0 (no permissions) |
|
1 (see the folder) |
|
2 (create objects in folder) |
|
4 (create subfolders) |
|
64 (all permissions) |
7-13 |
Read permissions for objects in folder: |
|
0 (no permissions) |
|
1 (read only own objects) |
|
2 (read all objects) |
|
64 (all permissions) |
14-20 |
Write permissions for objects in folder: |
|
0 (no permissions) |
|
1 (modify only own objects) |
|
2 (modify all objects) |
|
64 (all permissions) |
21-27 |
Delete permissions for objects in folder: |
|
0 (no permissions) |
|
1 (delete only own objects) |
|
2 (delete all objects) |
|
64 (all permissions) |
28 |
Admin flag: |
|
0 (no permissions) |
|
1 (every operation modifying the folder in some way requires this permission (e.g. changing the folder name) |
Capabilities
0 |
Mailing system supports permissions. |
1 |
Mailing system supports ordering mails by their thread reference. |
2 |
Mailing system supports quota restrictions. |
3 |
Mailing system supports sorting. |
4 |
Mailing system supports folder subscription. |
Note: Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.
Standard Folder Types
0 |
No default folder. |
1 |
Task. |
2 |
Calendar. |
3 |
Contact. |
7 |
Inbox. |
8 |
Infostore. |
9 |
Drafts. |
10 |
Sent. |
11 |
Spam. |
12 |
Trash. |
Supported Capabilities
permissions |
Folder storage supports permissions. |
publication |
Folder storage supports folder publication. |
quota |
Folder storage supports quota restrictions. |
sort |
Folder storage supports sorting. |
subscription |
Folder storage supports folder subscription. |
Mail filter
This chapter gives a detailed description of the mail filter module. It should be uses as a source of information in addition to the http api.
First of all the main structure of a mail filter script is, that it has different rules. Each of them contains one command. This command takes a test condition which executes the actions given in that command if the test condition is true.
The test condition consists of a test command and some arguments for this command depending on the command itself. Because the available tests depend on the mail filter server, these tests must be determined at runtime. So that no test field is transferred to the server which it isn't able to handle. Examples for tests are address, allof and anyof.
Each test has a special comparison. The list of available comparisons depends on the test given and the mail filter server configuration so they have to be determined at runtime too.
Each time you want to do some action on a mail you need a so called action command. This describes what to do with a mail. To action commands the same applies as to the test commands and their comparison types, they must be determined at runtime.
All those dynamical values can be fetched via a config object at startup. This object shows the capabilities of the server to the client. This allows the client to show only the capabilities the server actually has to the user and to send only objects to the server which produce no errors on the server side.
To deal with this high flexibility of mail filters this specification can be roughly divided into 2 parts. A non-changing core and dynamical extensions. The core specification is that each rule consists of a name, an ID, a value showing if this rule is active or not and a tag which can be set on a rule to mark that rule for a special purpose. Furthermore each rule takes a test object, specifying in what case the following actions are triggered, and one or many actioncommands, specifying the actions itself.
The objects for the tests and the actions are dynamical, so the set presented in this specification may be changed over the time, but only compatible changes are allowed to the objects, otherwise new test or action objects have to be introduced. Due to the fact that not every sieve implementation will offer all the capabilities written in this document, the server will sent his configuration if a special request is made. This configuration will show which of the tests and which of the actions are allowed. So for example if the server signals that it is capable of handling vacation, sending a vacation object as action is safe.
Furthermore some tests use a comparison field as stated above which specifies how the fields are compared. The values of this field must also be determined at runtime. So in the configuration object there is a special part which shows the comparisons which are available. Note that not all comparisons can be used with every test. Some of them are denoted to a special test, which is described in Possible comparisons.
Possible tests
address |
This test type applies to addresses only. So it may be used for all header fields which contain addresses. This test returns true if any combination of the header-list and values-list arguments match. |
envelope |
This test applies to the envelope of a mail. This test isn't used under normal circumstances as the envelope isn't accessible in all mail setups. This test returns true if any combination of the header-list and values-list arguments match. |
true |
A test for a true result (can be used if an action command should be executed every time). |
not |
Negates a given test. |
size |
Deals with the size of the mail. |
currentdate |
Compares a given date with the current date. |
header |
Tests against all headers of a mail. So with this test in contrast to the address test also fields such as subject can be handled. This test returns true if any combination of the header-list and values-list arguments match. |
body |
Tests against the content of a mail. |
allof |
Defines an AND condition between several tests. |
anyof |
Defines an OR condition between several tests. |
date |
Compares a given date with the given date header. |
exists |
Tests whether a list of headers exist or not. |
Simplified tests
The mailfilter v2 api suppports some simplified rules.
subject |
A convenience test to match against a mails subject. |
from |
A convenience test to match against a mails From header. |
to |
A convenience test to match against a mails To header. |
cc |
A convenience test to match against a mails Cc header. |
anyRecipient |
A convenience test to match against a mails To and Cc headers. |
mailingList |
Matches against common mailing list headers for simple filtering of mailing list mails. |
Possible comparisons
is |
If a field is equal to a given value. |
not is |
If a field is unequal to a given value. |
contains |
If a field contains a given value at any position. |
not contains |
If a field not contains a given value at any position. |
matches |
Tests if the value matches the value in the specified field ("*" matches zero or more characters, "?" matches a single character, to use these characters themselves they have to be escaped via backslash). |
not matches |
Tests if the value doesn't matches the value in the specified field ("*" matches zero or more characters, "?" matches a single character, to use these characters themselves they have to be escaped via backslash). |
regex |
Tests if a given regular expression matches with the value present in the specified field. |
not regex |
Tests if a given regular expression doesn't matches with the value present in the specified field. |
startswith |
Like matches but adds an additional wildcard character at the end of the value. |
not startswith |
Like 'not matches' but adds an additional wildcard character at the end of the value. |
endswith |
Like matches but adds an additional wildcard character at the beginning of the value. |
not endswith |
Like 'not matches' but adds an additional wildcard character at the beginning of the value. |
Possible currentdate comparisons
is |
Used in the date test to check for a value equal to the given one. |
not is |
Used in the date test to check for a value unequal to the given one. |
ge |
Used in the date test to check for a value greater or equal to the given one. |
not ge |
Used in the date test to check for a value smaller to the given one. |
le |
Used in the date test to check for a value less or equal to the given one. |
not le |
Used in the date test to check for a value greater to the given one. |
Possible address parts
all |
The hole mail address. This is also the default. |
localpart |
The local part of the mail address. |
domain |
The domain part of the mail address. |
Possible size comparisons
over |
Used in the size test to check for a value greater than the given one. |
not over |
Used in the size test to check for a value smaller or equal to the given one. |
under |
Used in the size test to check for a value less than the given one. |
not under |
Used in the size test to check for a value greater or equal to the given one. |
Possible extensions
content |
An extension used in conjunction with the body test to define the content which should be considered. This extension will need a parameter specifying the mime-type of the part of the message which will be searched. |
text |
An extension used in conjunction with the body test to define that only the text of the body should be considered in this test. This extension takes no parameter. |
Structure of tests
This section describes the structures of tests.
address-test
id |
String |
address |
A string describing the test command. |
comparison |
String |
|
Available types can be found in the config object. (see Possible comparisons). |
addresspart |
String |
|
The address part which should be tested, see Possible address parts. |
headers |
Array |
|
A string array containing the header fields.| |
values |
Array |
|
A string array containing the value for the header fields. The test will be true if any of the strings matches. |
envelope-test
id |
String |
envelope |
A string describing the test command. |
comparison |
String |
|
Available types can be found in the config object. (see Possible comparisons). |
addresspart |
String |
|
The address part which should be tested, see Possible address parts. |
headers |
Array |
|
A string array containing the header fields. |
values |
Array |
|
A string array containing the value for the header fields. The test will be true if any of the strings matches. |
true-test
id |
String |
true |
A string describing the test command. |
not-test
id |
String |
not |
A string describing the test command. |
test |
Object |
|
One of the test objects which result will be negated. |
size-test
id |
String |
size |
A string describing the test command. |
comparison |
String |
|
Only two types are valid here. A description can be found in Possible size comparisons. |
size |
Number |
|
A number specifying the size for this comparison, in bytes. |
currentdate-test
id |
String |
currentdate |
A string describing the test command. |
comparison |
String |
|
Only three types are valid here. A description can be found in Possible currentdate comparisons. |
datepart |
String |
|
A string containing the string "date", "weekday" or "time" as we only allow fix date, time and weekday comparisions for now. |
datevalue |
Array |
|
A value array containing the corresponding value to the datepart. For "date" and "time" this will be an array of "Date" (unix timestamp). For "weekday", it will be an array of integers ranging from 0 to 6, reflecting the equivalent weekday, starting from Sunday through Saturday, i.e. 0 - Sunday, ..., 6 - Saturday. The test will be true if any of the values matches |
zone |
String |
|
The optional timezone which should be used for the test. E.g. "+0100". If omitted the current timezone of the user is used. |
id |
String |
header |
A string describing the test command. |
comparison |
String |
|
Available types can be found in the config object. (see Possible comparisons). |
headers |
Array |
|
A string array containing the header fields. |
values |
Array |
|
A string array containing the values for the header fields. The test will be true if any of the strings matches. |
allof-test
id |
String |
allof |
A string describing the test command. |
tests |
Array |
|
A array of tests. |
anyof-test
id |
String |
anyof |
A string describing the test command. |
tests |
Array |
|
A array of tests. |
body-test
id |
String |
body |
A string describing the test command. |
comparison |
String |
|
Available types can be found in the config object. (see Possible comparisons). |
extensionskey |
String |
|
The extension key can be one of the value found in Possible extensions. |
extensionsvalue |
String |
|
A value for the given key. If the key has no value (see Possible extensions for this information) the value given here is ignored. |
values |
Array |
|
A string array containing the values for the body. The test will be true if any of the strings matches. |
date-test
id |
String |
date |
A string describing the test command. |
comparison |
String |
|
Only three types are valid here. A description can be found in Possible currentdate comparisons. |
header |
String |
|
The header field to test against. |
datepart |
String |
|
A string containing the string "date", "weekday" or "time" as we only allow fix date, time and weekday comparisions for now. |
datevalue |
Array |
|
A value array containing the corresponding value to the datepart. For "date" and "time" this will be an array of "Date" (unix timestamp). For "weekday", it will be an array of integers ranging from 0 to 6, reflecting the equivalent weekday, starting from Sunday through Saturday, i.e. 0 - Sunday, ..., 6 - Saturday. The test will be true if any of the values matches |
zone |
String |
|
The optional timezone which should be used for the test. E.g. "+0100". If omitted the current timezone of the user is used. |
exists-test
id |
String |
exists |
A string describing the test command. |
headers |
Array |
|
A string array containing the header fields. |
id |
String |
|
A string describing a simplified test command. |
comparison |
String |
|
Available types can be found in the config object (see Possible comparisons). Defaults to "contains". |
values |
Array |
|
A string array containing the values for the header fields. The test will be true if any of the strings matches. |
Possible action commands
keep |
Keeps a mail non-changed. |
discard |
Discards a mail without any processing. |
redirect |
Redirects a mail to a given e-mail address. |
move |
Moves a mail into a given subfolder (the syntax of the subfolder given here must be the correct syntax of the underlying IMAP-server and is up to the GUI to detect things such as altnamespace or unixhierarchysep). |
reject |
Rejects the mail with a given text. |
stop |
Stops any further progressing of a mail. |
vacation |
Creates a vacation mail. |
setflags |
Set flags of a mail. |
addflags |
Adds flags to a mail. |
notify |
Adds a notification. |
pgp |
Encrypts a mail via pgp. |
Structure of action commands
This section describes the structures of action commands.
keep-command
id |
String |
keep |
A string defining the object itself. |
discard-command
id |
String |
discard |
A string defining the object itself. |
redirect-command
id |
String |
redirect |
A string defining the object itself. |
to |
String |
|
A string containing where the mail should be redirected to. |
copy |
Boolean |
|
An optional boolean flag. If set the :copy argument will be added to the redirect command. See RFC 3894 for further details. |
move-command
id |
String |
move |
A string defining the object itself. |
into |
String |
|
This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware. |
copy |
Boolean |
|
An optional boolean flag. If set the :copy argument will be added to the fileinto command. See RFC 3894 for further details. |
reject-command
id |
String |
reject |
A string defining the object itself. |
text |
String |
|
A string containing the reason why the mail is rejected. |
stop-command
id |
String |
stop |
A string defining the object itself. |
vacation-command
id |
String |
vacation |
A string defining the object itself. |
days |
Integer |
|
The days for which a vacation text is returned. |
addresses |
Array |
|
The addresses for which this vacation is responsible. That means for which addresses out of the aliases array of the user defining this filter, vacations will be sent. |
from |
String or Array |
|
Support for the ':from' tag. Specifies the value of the from header for the auto-reply mail, e.g. Foo Bear foo.bear@ox.io (Since 7.8.1). The array of strings should be a simple JSONArray with length 2; the first element should include the personal part of the e-mail address and the second element the actual e-mail address. If only the e-mail address is available, that should be the only element of the array. |
subject |
String |
|
The new subject for the returned message (can be left empty, when only adding RE:). |
text |
String |
|
The vacation text itself. |
addflags-command
id |
String |
addflags |
A string defining the object itself. |
flags |
Array |
|
An array containing the flags which should be added to that mail. A flag can be either a system flag or a user flag. System flags begin with a backslash () and can be one of the ones describes in Flags.
System flags are case-insensitive.
User flags begin with a dollar sign ($) and can contain any ASCII characters between 0x21 (!) and 0x7E (~), inclusive, except for the characters 0x22, 0x25, 0x28, 0x29, 0x2A, 0x5C, 0x5D and 0x7B, which correspond to
"%()*]{
Mail color flags as used by OX are implemented by user flags of the form $cl_n, where n is a number between 1 and 10, inclusive.
See RFC 3501 for further details on IMAP flags and their meanings. |
setflags-command
id |
String |
setflags |
A string defining the object itself. |
flags |
Array |
|
An array containing the flags which should be set. A flag can be either a system flag or a user flag. System flags begin with a backslash () and can be one of the ones describes in Flags.
System flags are case-insensitive.
User flags begin with a dollar sign ($) and can contain any ASCII characters between 0x21 (!) and 0x7E (~), inclusive, except for the characters 0x22, 0x25, 0x28, 0x29, 0x2A, 0x5C, 0x5D and 0x7B, which correspond to
"%()*]{
Mail color flags as used by OX are implemented by user flags of the form $cl_n, where n is a number between 1 and 10, inclusive.
See RFC 3501 for further details on IMAP flags and their meanings. |
Flags
\seen |
\answered |
\flagged |
\deleted |
\draft |
\recent |
notify-command
id |
String |
notify |
A string defining the object itself. |
message |
String |
|
the content of the notification message. |
method |
String |
|
the method of the notification message, e.g. "mailto:012345678@sms.gateway". |
pgp-command
id |
String |
pgp |
A string defining the object itself. |
keys |
Array |
|
The public keys as string which should be used for encryption. |
Advanced Search
This chapter describes the search module in more detail. Each search request contains a JSON object representing the search term. The search term is embedded in a wrapping JSON object with the field filter
, like {"filter":[search term]}
. In general the structure of a search term is in prefix notation, meaning the operator is written before its operands: [">", 5, 2]
represents the condition "5 > 2".
There are two kinds of search operators, comparison operators and logic operators.
Comparison operators
Comparison operators have exactly two operands. Each operand can either be a field name or a constant. A field name is a JSON object with the member field
specifying the field name, e.g. {"field":"first_name"}
. The available field names depend on the module that implements the search. Primitive JSON types are interpreted as constants. Arrays are not valid operands for comparison operators!
">" |
greater |
"<" |
smaller |
"=" |
equal |
"<=" |
smaller or equal |
">=" |
greater or equal |
"<>" |
unequal |
Logic operators
The logic operator "not" has exactly one operand, the other logic operators can have any number of operands. Each operand must be an array representing a nested search expression.
Examples
{
"filter":[
"and",
[
"=",
{
"field":"field_name1"
},
"value1"
],
[
"not",
[
">",
{
"field":"field_name2"
},
"value2"
]
]
]
}
Represents the expression field_name1 = value1 AND NOT field_name2 > value2
.