Table of Contents

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.

Name Type Value
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:

Error code Parameter indices
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.

Type Time Timezone Comment
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

ID Name Type Value
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

Name Type Value
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

Name Type Value
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

ID Name Type Value
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

ID Name Type Value
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.
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

Number Type
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

ID Name Type Value
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 userIId 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 userIId 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

Number Description
0 none (single event)
1 daily
2 weekly
3 monthly
4 yearly

Participant identifier

Name Type Value
id Number User ID
type Number See Participant types
mail String mail address of an external participant

Participant types

Number Type
1 user
2 user group
3 resource
4 resource group
5 external user

User participant object

Name Type Value
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

Number Status
0 none
1 accepted
2 declined
3 tentative

Confirming participant

Name Type Value
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

ID Name Type Value
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

Number Status
1 not started
2 in progress
3 done
4 waiting
5 deferred

Detailed contact data

ID Displayed name Name Type Description
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.
610 yomiFirstName String Kana based representation for the First Name. Commonly used in japanese environments for searchin/sorting issues. (since 6.20)
611 yomiLastName String Kana based representation for the Last Name. Commonly used in japanese environments for searchin/sorting issues. (since 6.20)
612 yomiCompany String Kana based representation for the Company. Commonly used in japanese environments for searchin/sorting issues. (since 6.20)
613 addressHome String Support for Outlook 'home' address field. (since 6.20.1)
614 addressBusiness String Support for Outlook 'business' address field. (since 6.20.1)
615 addressOther String Support for Outlook 'other' address field. (since 6.20.1)

Distribution list member

Name Type Value
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

Number Field
0 independent contact
1 default email field (email1)
2 second email field (email2)
3 third email field (email3)

Detailed appointment data

ID Name Type Value
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

Number Value
1 reserved
2 temporary
3 absent
4 free

Detailed mail data

ID Name Type Value
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

Number Description
1 answered
2 deleted
4 draft
8 flagged
16 recent
32 seen
64 user
128 spam
256 forwarded

X-Priority header

Number Description
0 No priority
5 Very Low
4 Low
3 Normal
2 High
1 Very High

Attachment

Name Type Value
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

ID Name Type Value
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 docment 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.

Object Permission object

Name Type Value
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

Name Type Value
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

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

Number Name
1 Appointment
4 Task
7 Contact
137 Infostore

Mail account data

ID Name Type Value
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

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

ID Displayed name Name Type Value
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

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

Flags and bitmasks

Permission flags

Bits Value
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

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

Bit Description
0 No default folder.
1 Task.
2 Calendar.
3 Contact.
7 Inbox.
8 Infostore.
9 Drafts.
10 Sent.
11 Spam.
12 Trash.

Supported Capabilities

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

Name Description
address This test type applies to addresses only. So it may be used for all header fields which contain addresses. This test returns true if any combination of the header-list and values-list arguments match.
envelope This test applies to the envelope of a mail. This test isn't used under normal circumstances as the envelope isn't accessible in all mail setups. This test returns true if any combination of the header-list and values-list arguments match.
true A test for a true result (can be used if an action command should be executed every time).
not Negates a given test.
size Deals with the size of the mail.
currentdate Compares a given date with the current date (available since v6.20)
header Tests against all headers of a mail. So with this test in contrast to the address test also fields such as subject can be handled. This test returns true if any combination of the header-list and values-list arguments match.
body Tests against the content of a mail.
allof Defines an AND condition between several tests.
anyof Defines an OR condition between several tests.

Possible comparisons

Name Description
is If a field is equal to a given value.
contains If a field contains a given value at any position.
matches Tests if the value matches the value in the specified field ("*" 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. | | user | Tests if the user part of an e-mail address is the value given here. This means in herbert+mustermann@example.com. The user checks the part herbert (only possible in conjunction with the address test). | | detail | Tests if the detail part of an e-mail address is the value given here. In the example above this evaluates to mustermann (only possible in conjunction with the address test). |

Possible currentdate comparisons

Name Description
is Used in the date test to check for a value equal to the given one.
ge Used in the date test to check for a value greater or equal to the given one.
le Used in the date test to check for a value less or equal to the given one.

Possible size comparisons

Name Description
over Used in the size test to check for a value greater than the given one.
under Used in the size test to check for a value less than the given one.

Possible extensions

Name Description
content An extension used in conjunction with the body test to define the content which should be considered. This extension will need a parameter specifying the mime-type of the part of the message which will be searched.
text An extension used in conjunction with the body test to define that only the text of the body should be considered in this test. This extension takes no parameter.

Structure of tests

This section describes the structures of tests.

address-test

Name Type Value Description
id String address A string describing the test command.
comparison String Available types can be found in the config object. (see Possible comparisons).
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

Name Type Value Description
id String envelope A string describing the test command.
comparison String Available types can be found in the config object. (see Possible comparisons).
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

Name Type Value Description
id String true A string describing the test command.

not-test

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

size-test

Name Type Value Description
id String size A string describing the test command.
comparison String Only two types are valid here. A description can be found in Possible size comparisons.
size Number A number specifying the size for this comparison, in bytes.

currentdate-test

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

header-test

Name Type Value Description
id String header A string describing the test command.
comparison String Available types can be found in the config object. (see 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

Name Type Value Description
id String allof A string describing the test command.
tests Array A array of tests.

anyof-test

Name Type Value Description
id String anyof A string describing the test command.
tests Array A array of tests.

body-test

Name Type Value Description
id String body A string describing the test command.
comparison String Available types can be found in the config object. (see 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.

Possible action commands

Name Description
keep Keeps a mail non-changed.
discard Discards a mail without any processing.
redirect Redirects a mail to a given e-mail address.
move Moves a mail into a given subfolder (the syntax 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.
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

Name Type Value Description
id String keep A string defining the object itself.

discard-command

Name Type Value Description
id String discard A string defining the object itself.

redirect-command

Name Type Value Description
id String redirect A string defining the object itself.
to String A string containing where the mail should be redirected to.

move-command

Name Type Value Description
id String move A string defining the object itself.
into String This string takes the object id of the destination mail folder as specified in the HTTP API of the groupware.

reject-command

Name Type Value Description
id String reject A string defining the object itself.
text String A string containing the reason why the mail is rejected.

stop-command

Name Type Value Description
id String stop A string defining the object itself.

vacation-command

Name Type Value Description
id String vacation A string defining the object itself.
days Integer The days for which a vacation text is returned.
addresses Array The addresses for which this vacation is responsible. That means for which addresses out of the aliases array of the user defining this filter, vacations will be sent.
from String or Array Support for the ':from' tag. Specifies the value of the from header for the auto-reply mail, e.g. Foo Bear (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

Name Type Value Description
id String addflags A string defining the object itself.
flags Array An array containing the flags which should be added to that mail. A flag can be either a system flag or a user flag. System flags begin with a backslash () and can be one of the 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, includive.

See RFC 3501 for further details on IMAP flags and their meanings.|

Flags

Name
\seen
\answered
\flagged
\deleted
\draft
\recent

notify-command

Name Type Value Description
id String notify A string defining the object itself.
message String the content of the notification message.
method String the method of the notification message, e.g. "mailto:012345678@sms.gateway".

pgp-command

Name Type Value Description
id String pgp A string defining the object itself.
keys Array The public keys as string which should be used for encryption.

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!

Operator Description
">" 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.

Operator
"not"
"and"
"or"

Examples

{
  "filter":[
    "and",
    [
      "=",
      {
        "field":"field_name1"
      },
      "value1"
    ],
    [
      "not",
      [
        ">",
        {
          "field":"field_name2"
        },
        "value2"
      ]
    ]
  ]
}

Represents the expression field_name1 = value1 AND NOT field_name2 > value2.