Blog : HTTP API
HTTP API
Introduction
This document defines the Open-Xchange HTTP API which is used by the new AJAX GUI. The first chapter describes general definitions and conventions which apply to all server modules. All other chapters describe individual server modules.
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 o 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. E.g.
"USER_INPUT" An error resulting from wrong or missing input from front-end (e.g. mandatory field missing).
"CONFIGURATION" An error related to user/system configuration which denies requested operation.
"PERMISSION_DENIED" An error related to insufficient permission settings.
"TRY_AGAIN" A requested operation could not be accomplished because a needed resource is temporary down or missing (e.g. imap server rejects connection because of too many established connections).
"SERVICE_DOWN" A subsystem or third party service is down and therefore does not respond (e.g. database is down).
"CONNECTIVITY" The underlying socket connection is corrupt, empty or closed. Only a temporary error that does not affect the whole system.
"ERROR" A programming error which was caused by incorrect program code.
"CONFLICT" A concurrent modification.
"CAPACITY" The requested operation could not be performed cause an underlying resource is full or busy (e.g. IMAP folder exceeds quota).
"TRUNCATED" The given data could not be stored into the database because an attribute contains a too long value.
"WARNING" Action was at least partially successful, but a condition occurred that merited a warning
category Number Maintained for legacy reasons: The numeric representation of the first category:
1 An error resulting from wrong or missing input from front-end (e.g. mandatory field missing).
2 An error strictly related to user configuration which denies requested operation.
3 An error related to insufficient permission settings.
4 A requested operation could not be accomplished because a needed resource is temporary down or missing (e.g. imap server rejects connection because of too many established connections).
5 A subsystem or third party service is down and therefore does not respond (e.g. database is down).
6 The underlying socket connection is corrupt, empty or closed. Only a temporary error that does not affect the whole system.
8 A programming error which was caused by incorrect programm code.
9 A concurrent modification.
11 The requested operation could not be performed cause an underlying resource is full or busy (e.g. IMAP folder exceeds quota).
12 The given data could not be stored into the database because an attribute contains a too long value.
13 Action was at least partially successful, but a condition occurred that merited a warning
Response body
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 nth 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 in Data size parameters
Error code Parameter indices
CON-0101 2, 3
FLS-0003 1, 2, 3
MSG-0065 1, 3
MSG-0066 1
NON-0005 1, 2
Data size parameters
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. The types are described in Date and time 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.
Date and time types
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 bodyincludes 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.
Documentation conventions
The rest of this document describes all available requests for each module. A module usually supports several different requests, which are differentiated by the used HTTP method, URI path and supplied URI parameters. The description of each method generally contains the following elements:
• the HTTP method followed by the request URI, inclusing the URI parameter action, which is used to differentiate methods,
• a list of URI parameters which can or must be supplied by the client,
• for PUT requests, content of the request body,
• "Response with timestamp:"if the timestamp field is required in the response body or simply "Response:" if not,
• content of the response payload, unless it is supposed to be empty.
Common object data
This table contains common fields which apply for any module's data type and is referenced throughout this document whenever a module's data type is described.
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.
Common object data
Module "login"
The login module is used to obtain a session from the user's login credentials. To understand the details of the different login methods, see the article titled "Login variations".
Login
POST /ajax/login?action=login
Parameters:
• name – The login name.
• password – The password.
• authId (optional) – Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.
• client (optional) – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.
• version (optional) – Used version of the HTTP/JSON interface client.
• clientIP (optional) – IP address of the client host for that the session is created. If this parameter is not specified the IP address of theHTTP client doing this request is used.
• clientUserAgent (optional) – Value of the User-Agent header of the client host for that the session is created. If this parameter is not specified the User-Agent of the current HTTP client doing this request is used.
Response: A JSON object containing the session ID used for all subsequent requests. Additionally a random token is contained to be used for the Easy Login method.
Form Login (since 6.20)
POST /ajax/login?action=formlogin
This request implements a possible login to the web frontend by only using a simple HTML form. An example for such a form can be found in the backend's documentation folder (/usr/share/doc/open-xchange-core) under examples/login.html.
Parameters:
• login – The login name.
• password – The password.
• authId – Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.
• client – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange. If the autologin request should work the client must be the same as the client sent by the UI in the normal login request.
• version – Used version of the HTTP/JSON interface client.
• autologin – True or false. True tells the UI to issue a store request for the session cookie. This store request is necessary if you want the autologin request not to fail.
• uiWebPath (optional) – Defines another path on the web server where the UI is located. If this parameter is not defined the configured default of the backend is used.
• clientIP (optional) – IP address of the client host for that the session is created. If this parameter is not specified the IP address of theHTTP client doing this request is used.
• clientUserAgent (optional) – Value of the User-Agent header of the client host for that the session is created. If this parameter is not specified the User-Agent of the current HTTP client doing this request is used.
Response: A redirect to the web UI. The URL of the web UI is either taken from the given parameter or from the configured default of the backend.
For a complete description of the FormLogin-Process please see this documentation
Token Login (since 7.0.1)
POST /ajax/login?action=tokenLogin
This request allows every possible client to create a very short living session. This session can then be transferred to any other client preferably a browser entering then the normal web interface. Then the sessions life time will be extended equally to every other session.
Compared to the login mechanism using the random token, this request is more secure because two tokens are used. One of these tokens is only known to the client and one is generated by the server. Only the combination of both tokens allows to use the session. The combination of both tokens must be done by the client creating the session.
Parameters:
• login – The login information.
• password – The password.
• clientToken – Client side identifier for accessing the session later. The value should be some token that is unique for every login request.
• authId – Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.
• client – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange. If the autologin request should work the client should be the same as the client sent by the UI in the normal login request. For security considerations it can become necessary to define here the correct client that will use the session.
• version – Version of the HTTP/JSON interface client. Only for statistic evaluations.
• autologin – True or false. True tells the UI to issue a store request for the session cookie. This store request is necessary if you want the autologin request not to fail. This must be enabled on the server and a client can test with the autologin request if it is enabled or not.
• uiWebPath (optional) – Defines another path on the web server where the UI is located. If this parameter is not defined the configured default of the backend is used.
• clientIP (optional) – IP address of the client host for that the session is created. If this parameter is not specified the IP address of theHTTP client doing this request is used. Currently the IP address may change when using the session with both tokens. This can be disabled in future releases for security considerations.
• clientUserAgent (optional) – Value of the User-Agent header of the client host for that the session is created. If this parameter is not specified the User-Agent of the current HTTP client doing this request is used. Currently the User-Agent may change when using the session. This can be disabled in future releases for security considerations.
Response: A redirect to the web UI. The URL of the web UI is either taken from the given parameter or from the configured default of the backend. This redirect will only contain the server side token. The client side token sent in the request must be appended by the client creating the session. The final URL must have the form redirect_URL&clientToken=token. Both tokens are necessary to use the session and both tokens must match. Otherwise the session is terminated.
Tokens (since 7.0.1)
POST /ajax/login?action=tokens
This request allows clients to access a session created with the tokenLogin request. When accessing the session its life time is extended equally to every other session.
Parameters:
• serverToken – Server side identifier for accessing the session. This identifier was created by the server and is contained in the tokenLogin response.
• clientToken – Client side identifier for accessing the session. This identifier was created by the client and passed within the POST data of the tokenLogin request.
• client – Identifier of the client using the HTTP/JSON interface. Currently this request allows to change the client identifier for the session. This eases creating the session because the identifier of the client using the session must not be known. For security considerations it can become necessary to drop this parameter.
Response: A JSON object conform to the normal response body contrary to the JSON object of the normal login request. This JSON object contains the session identifier, the login, the identifier and the locale of the user.
Logout
GET /ajax/login?action=logout
Parameters:
• session – A session ID previously obtained from the login module.
Refresh secret cookie (since 6.18.2)
GET /ajax/login?action=refreshSecret
Parameters:
• session – A session ID previously obtained from the login module.
Refresh auto-login cookie
GET /ajax/login?action=store
Parameters:
• session – A session ID previously obtained from the login module.
Redirect
GET /ajax/login;jsessionid=1157370816112.OX1?action=redirect
SECURITY WARNING! Utilizing this request is INSECURE! This request allows to access a session with a single one time token. This one time token may be delivered to the wrong client if the protocol has an error or Apache or the load balancer make a mistake. This will cause a wrong user to be in a wrong session. IMMEDIATELY consider not to use this request anymore. You have been warned. Use instead the FormLogin that does not need to use the redirect request.
Parameters:
• random – A session random token to jump into the session. This random token is part of the login response. Only a very short configurable time after the login it is allowed to jump into the session with the random token.
• client (optional) – The client can be defined here newly if it is not correct on the login request itself.
• store (optional) – Tells the UI to do a store request after login to be able to use autologin request.
• uiWebPath (optional) – The optional path on the webserver to the UI. If this parameter is not given the configured uiWebPath is used.
Change IP
The following request is especially for integration with systems located in the providers infrastructure. If those systems create a session with the following request the client host IP address in the session can be changed. The IP check for following requests will be done using this newly set client host IP address.
POST /ajax/login?action=changeip
Parameters:
• session – A session ID previously obtained from the login module.
• clientIP – New IP address of the client host for the current session.
Response: A JSON object containing the string "1" as data attribute.
Redeem Token (since 7.4.0)
POST /ajax/login?action=redeemToken
Parameters:
• token – The token created with acquireToken.
• authId – Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.
• client – Identifier of the client using the HTTP/JSON interface. The client must identifier must be the same for each request after creating the login session.
• secret – The value of the secret string for token logins. This is configured through the tokenlogin-secrets configuration file.
Response: A JSON object containing the session ID used for all subsequent requests. Additionally a random token is contained to be used for the Easy Login method. If configured within tokenlogin-secrets configuration file even the user password will be returned.
Module "config"
The config module is used to retrieve and set user-specific configuration. The configuration is stored in a tree. Each node of the tree has a name and a value. The values of leaf nodes are strings which store the actual configuration data. The values of inner nodes are defined recursively as objects with one field for each child node. The name and the value of each field is the name and the value of the corresponding child node, respectively.
The namespace looks like the following:
• /ajax/config/
o gui – A string containing GUI-specific settings (currently, it is a huge JSON object).
o fastgui - A string containing GUI-specific settings. This is a JSON object that must be kept small for performance.
o context_id - the unique identifier of the context (read-only, added 2008-01-28).
o cookielifetime - the cookie life time in seconds or -1 for session cookie (read-only, added 2010-11-16).
o identifier – the unique identifier of the user (read-only).
o contact_id – the unique identifier of the contact data of the user (read-only).
o language – the configured language of the user.
o timezone – the configured timezone of the user.
o availableTimeZones – a JSON object containing all available time zones. The key is the time zone identifier and the value contains its name in users language. (read-only, added 2010-07-08/v6.18).
o calendarnotification - send a mail notification for appointments (deprecated since 2008-12-11)
o tasknotification - send a mail notification for tasks (deprecated since 2008-12-11)
o reloadTimes - Selectable times for GUI reload
o serverVersion - Version string of the server.
o currentTime - User timezone specific long of the current server time.
o maxUploadIdleTimeout - Timeout after that idle uploads are deleted.
o folder/ – the standard folder of the user
 tasks – the standard task folder (read-only)
 calendar – the standard calendar folder (read-only)
 contacts – the standard contacts folder (read-only)
 infostore – the private infostore folder (read-only, since v6.20.1)
 eas – whether EAS folder selection is enabled (read-only)
o mail/ – settings for the email module (deprecated 2008-04-29)
 addresses – all email addresses of the user including the primary address (read-only, deprecated 2008-04-29)
 defaultaddress – primary email address of the user (read-only, deprecated 2008-04-29)
 sendaddress – one email address out of the addresses list that are email sent with. (deprecated 2008-04-29)
 folder/ – the standard email folders (read-only, deprecated 2008-04-29)
 inbox – identifier of the folder that gets all incoming mails (read-only, deprecated 2008-04-29)
 drafts – identifier of the folder with the mail drafts (read-only, deprecated 2008-04-29)
 trash – identifier of the folder with the deleted mails (read-only, deprecated 2008-04-29)
 spam – identifier of the folder with the spam mails (read-only, deprecated 2008-04-29)
 sent – identifier of the folder with the sent mails (read-only, deprecated 2008-04-29)
 htmlinline – activate inlining of HTML attachments. (deprecated 2008-04-29)
 colorquote – color quoted lines. (deprecated 2008-04-29)
 emoticons – display emoticons as graphics. (deprecated 2008-04-29)
 harddelete – delete emails at once. (deprecated 2008-04-29)
 inlineforward – forward messages as inline or attachment. (deprecated 2008-04-29)
 vcard – attach vcard when sending mails. (deprecated 2008-04-29)
 notifyonreadack – notify on read acknowledgement. (deprecated 2008-04-29)
 msgpreview – show a message preview. (deprecated 2008-04-29)
 ignorereplytext (deprecated 2008-04-29)
 nocopytosent – don't put a copy to the sent folder when sending mails. (deprecated 2008-04-29)
 spambutton - Spam Button should be displayed in GUI or not. (deprecated 2008-04-29)
o participants
 autoSearch - If a search for all users, groups and resources when participant selection dialog is opened. (read-only, added 2008-10-09/SP5)
 maximumNumberParticipants – Defines the maximum number of participants for appointments and tasks. (read-only, added 2008-10-20/SP5)
 showWithoutEmail - If external participants without email should be shown.
 showDialog – Enables participant selection dialog for appointments and tasks. (read-only, added 2008-04-30/SP4)
o availableModules – Contains a JSON array listing all enabled modules for a user. GUI loads Plugins through this list. To get your plugin listed here, create a subtree below modules/ without a module subelement or with a subelement containing true (read-only, added 2008-02-25)
o minimumSearchCharacters – Minimum number of characters a search pattern must have to prevent large responses and slow queries. (read-only, added 2008-10-20/SP5)
o modules
 portal
 gui GUI settings for portal module
 module
 mail
 addresses – all email addresses of the user including the primary address (read-only, added 2008-02-25)
 appendmailtext – (added 2008-02-25)
 allowhtmlimages – Alters default setting whether external images contained in HTML content are allowed or not (added 2008-05-27)
 colorquoted – color quoted lines (added 2008-02-25)
 contactCollectFolder – contact folder id to save mail addresses from sent mails (added 2008-10-16)
 contactCollectEnabled – switch contact collection on/off (added 2008-10-16)
 contactCollectOnMailAccess – enables/disables contact collection for incoming mails. Default is true. (added 2009-09-24)
 contactCollectOnMailTransport – enables/disables contact collection for outgoing mails. Default is true. (added 2009-09-24)
 defaultaddress – primary email address of the user (read-only, added 2008-02-25)
 deletemail – delete emails or move to trash (added 2008-02-25)
 emoticons – display emoticons as graphics (added 2008-02-25)
 defaultFolder
 drafts – identifier of the folder with the mail drafts (read-only, added 2008-02-25)
 inbox – identifier of the folder that gets all incoming mails (read-only, added 2008-02-25)
 sent – identifier of the folder with the sent mails (read-only, added 2008-02-25)
 spam – identifier of the folder with the spam mails (read-only, added 2008-02-25)
 trash – identifier of the folder with the deleted mails (read-only, added 2008-02-25)
 forwardmessage – forward messages as inline or attachment (added 2008-02-25)
 gui GUI settings for mail module
 inlineattachments – activate inlining of HTML attachments (added 2008-02-25)
 linewrap – (added 2008-02-25)
 module – if mail module is enabled or not (added 2008-02-25)
 phishingheaders – header(s) identifying phishing headers (added 2008-05-27)
 replyallcc – put all recipients on reply all into CC (added 2008-12-16/SP5)
 sendaddress – one email address out of the addresses list that are email sent with (added 2008-02-25)
 spambutton – Spam Button should be displayed in GUI or not (added 2008-02-25)
 vcard – attach vcard when sending mails (added 2008-02-25)
 calendar
 calendar_conflict
 calendar_freebusy
 calendar_teamview
 gui GUI settings for the calendar module
 module
 notifyNewModifiedDeleted receive mail notification for new, modified or deleted appointments (added 2008-12-11/SP5)
 notifyAcceptedDeclinedAsCreator receive mail notification for accepted or declined appointments created by the user (added 2008-12-11/SP5)
 notifyAcceptedDeclinedAsParticipant receive mail notification for accepted or declined appointments that the user participates (added 2008-12-11/SP5)
 defaultStatusPrivate Default status for new appointments in private folders, where the user is participant. This does not affect appointments created by this user, which always have the status "accepted". The status are described in User participant object. Default is 0:none (added 2009-07-20/6.12)
 defaultStatusPublic Default status for new appointments in public folders, where the user is participant. This does not affect appointments created by this user, which always have the status "accepted". The status are described in User participant object. Default is 0:none (added 2009-07-20/6.12)
 contacts
 gui GUI settings for the contacts module
 mailAddressAutoSearch – Define if a search is triggered when the recipient selection dialog is opened or the folder is changed. (read-only, added 2008-10-20/SP5)
 module True if the contact module is enabled for the current user, false otherwise.
 singleFolderSearch – True if the current user is allowed to search for contacts only in a single folder. False if contact searches across all folders are allowed. (read-only, added 2009-02-04/SP5 U1)
 characterSearch – True if the side bar for searching for contacts by a start letter should be displayed. False if the side bar should be hidden. (read-only, added 2009-05-29/6.10)
 allFoldersForAutoComplete – true if an auto complete search may omit the folder identifier array and search for contacts in all readable folders. This is configured through the contact.properties configuration file. (read-only, added 2010-07-22/v6.18.0)
 tasks
 gui GUI settings for the tasks module
 module
 delegate_tasks
 notifyNewModifiedDeleted receive mail notification for new, modified or deleted tasks (added 2008-12-11/SP5)
 notifyAcceptedDeclinedAsCreator receive mail notification for accepted or declined tasks created by the user (added 2008-12-11/SP5)
 notifyAcceptedDeclinedAsParticipant receive mail notification for accepted or declined taks that the user participates (added 2008-12-11/SP5)
 infostore
 gui GUI settings for the infostore module
 folder – the standard infostore folders (read-only, since 7.6.0)
 trash – identifier of the default infostore trash folder (read-only, since 7.6.0)
 module
 interfaces
 ical
 vcard
 syncml
 folder
 gui UI settings for the folder tree
 public_folders
 read_create_shared_folders
 tree – Selected folder tree, the user wants to use. Currents trees are 0 for the known OX folder tree and 1 for the new virtual folder tree. (added 2010-04-09/6.18)
 com.openexchange.extras
 module – Extras link in the configuration (read only, added 2008-04-29)
 com.openexchange.user.passwordchange
 module – Will load Plug-In which allows to change the Password within the users configuration (read only, added 2008-07-09)
 com.openexchange.user.personaldata
 module – Will load Plug-In which allows to edit personal contact information within the users configuration (read only, added 2008-07-09)
 com.openexchange.group
 enabled – Specifies whether the user is allowed to edit groups and loads the corresponding Plug-In. (read only, added 2008-08-08)
 com.openexchange.resource
 enabled – Specifies whether the user is allowed to edit resources and loads the corresponding Plug-In. (read only, added 2008-08-08)
 com.openexchange.publish
 enabled – Specifies whether the user is allowed to publish items. (read only, added 2009-05-27)
 com.openexchange.subscribe
 enabled – Specifies whether the user is allowed to subscribe sources. (read only, added 2009-05-27)
 olox20
 active – Tells the UI if the user is allowed to use the OXtender for Microsoft Outlook 2. (read only, added 2011-03-15/6.20)
 module – Is set to false to prevent the UI from trying to load a plugin. (read only, added 2011-03-15/6.20)
 com.openexchange.oxupdater
 module – Is true if the OXUpdater package is installed and started. (read only, added 2011-06-01/6.20)
 active – Is true if the user is allowed to download the OXUpdater. Otherwise it's false. (read only, added 2011-06-01/6.20)
 com.openexchange.passwordchange
 showStrength – Show a widget, which displays the current passwort Strength while entering. (default: false)
 minLength – The minimum length of an entered password. (default: 4)
 maxLength – The maximum length of an entered password. 0 for unlimited. (default: 0)
 regexp – Defines the class of allowed special characters as Regular Expression. (default: [^a-z0-9])
 special – Shows an example of allowed special characters to the user. Should be a subset of "regexp" in a human readable format. (default: $, _, or %)
Get configuration data
GET /ajax/config/path
Parameters:
• session – A session ID previously obtained from the login module.
Response: Value of the node specified by path.
Set configuration data
PUT /ajax/config/path
Parameters:
• session – A session ID previously obtained from the login module.
Request body: The new value of the node specified by path.
Module "folders"
The folders module is used to access the OX folder structure.
Special System Folders
Folders with some kind of special.
ID Type Description
6 contacts System Users
Get root folders
GET /ajax/folders?action=root
Parameters:
• session – A session ID previously obtained from the login module.
• columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in Common folder data and Detailed folder data.
• tree – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
• allowed_modules – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.
Response: An array with data for all folders at the root level of the folder structure. Each array element describes one folder and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
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.
Common 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 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
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 inPermission 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 mail folder capabilites, as described in capabilities.
314 subscribed Boolean Indicates whether this folder should appear in folder tree or not.
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.
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.
Detailed folder data
Bits Value
0-6 Folder permissions:
0 No permissions.
1 See the folder.
2 Create objects in the folder. Note: Does not apply to folders of module system.
4 Create subfolders.
64 All permissions. This is currently the same as "Create subfolders" but in the future additional permissions may be added that will be given to the user when using this value.
The values are scalars and not bit sets. Any other than the described values should not be used. If they are used expect an exception from the backend. Every value automatically contains the access rights covered by lower values.
NOTE: Create objects in the folder is not covered by Create subfolders if folder's module is system.
7-13 Read permissions for objects in the folder:
0 No permissions.
1 Read only own objects.
2 Read all objects.
64 All permissions. This is currently the same as "Read all objects" but in the future additional permissions may be added that will be given to the user when using this value.
The values are scalars and not bit sets. Any other than the described values should not be used. If they are used expect an exception from the backend. Every value automatically contains the access rights covered by lower values.
14-20 Write permissions for objects in the folder:
0 No permissions.
1 Modify only own objects.
2 Modify all objects.
64 All permissions. This is currently the same as "Modify all objects" but in the future additional permissions may be added that will be given to the user when using this value.
The values are scalars and not bit sets. Any other than the described values should not be used. If they are used expect an exception from the backend. Every value automatically contains the access rights covered by lower values.
21-27 Delete permissions for objects in the folder:
0 No permissions.
1 Delete only own objects.
2 Delete all objects.
64 All permissions. This is currently the same as "Delete all objects" but in the future additional permissions may be added that will be given to the user when using this value.
The values are scalars and not bit sets. Any other than the described values should not be used. If they are used expect an exception from the backend. Every value automatically contains the access rights covered by lower values.
28 Admin flag:
0 No permissions.
1 Every operation modifying the folder in some way requires this permission. This are e.g. changing the folder name, modifying the permissions, deleting or moving the folder.
Permission flags
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.
group Boolean true if entity refers to a group, false if it refers to a user.
Permission object
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.
Capabilities
Bit Description
0 No default folder.
1 Task.
2 Calendar.
3 Contact.
7 Inbox.
8 Infostore.
9 Drafts.
10 Sent.
11 Spam.
12 Trash.
Standard Folder Types
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.
Supported Capabilities
Get subfolders
GET /ajax/folders?action=list
Parameters:
• session – A session ID previously obtained from the login module.
• parent – Object ID of a folder, which is the parent folder of the requested folders.
• columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in Common folder data and Detailed folder data.
• all – Set to 1 to list even not subscribed folders.
• tree – The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
• allowed_modules – An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.
• errorOnDuplicateName – An optional flag to enable or disable (default) check for duplicate folder names within returned folder response (since v6.20.1). If a duplicate folder name is detected, an appropriate error is returned as response.
Response with timestamp: An array with data for all folders, which have the folder with the requested object ID as parent. Each array element describes one folder and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
Get path
GET /ajax/folders?action=path
Parameters:
• session – A session ID previously obtained from the login module.
• id – Object ID of a folder.
• columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in Common folder data and Detailed folder data.
• tree – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
• allowed_modules – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.
Response with timestamp: An array with data for all parent nodes until root folder. Each array element describes one folder and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
Get updated folders
GET /ajax/folders?action=updates
Parameters:
• session – A session ID previously obtained from the login module.
• parent – Object ID of a folder, which is the parent folder of the requested folders.
• timestamp – Timestamp of the last update of the requested folders.
• ignore (optional) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.
• columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in Common folder data and Detailed folder data.
• tree – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
• allowed_modules – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.
Response with timestamp: An array with data for new, modified and deleted folders. New and modified folders are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted folders (should the ignore parameter be ever implemented) would be identified by their object IDs as plain strings, without being part of a nested array.
Get a folder
GET /ajax/folders?action=get
Parameters:
• session – A session ID previously obtained from the login module.
• id – Object ID of the requested folder.
• tree – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
• allowed_modules – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.
Response with timestamp: An object containing all data of the requested folder. The fields of the object are listed in Common folder data andDetailed folder data. The field id is not present. Since OX access controls are folder-based, the folder object also defines the permissions for the objects it contains. The permissions for a given user or group are defined by the object described in Permission object. The format of the actual permissions depends on the type of the folder. The permissions of mail folders are transmitted as a rights string as defined in section 3 of RFC 2086. Permissions of all other folders are transmitted as a single nonnegative integer number. The permissions for any given action on the folder or on contained objects is defined by a group of bits in the binary representation of this number. Each group of bits is interpreted as a separate number. Zero always means "no permissions". Any other values add new permissions and always include the permissions of all lower values. The individual values are described in Permission flags.
Update a folder
PUT /ajax/folders?action=update
Parameters:
• session – A session ID previously obtained from the login module.
• id – Object ID of the updated folder.
• timestamp – Timestamp of the updated folder. If the folder was modified after the specified timestamp, then the update must fail.
• tree – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
• allowed_modules – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.
Request body: Folder object as described in Common folder data and Detailed folder data. Only modified fields are present.
Create a folder
PUT /ajax/folders?action=new
Parameters:
• folder_id – The parent folder of the newly created folder
• session – A session ID previously obtained from the login module.
• tree – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
• allowed_modules – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.
Request body: Folder object as described in Common folder data and Detailed folder data. The field id should not be present.
Provided that permission is granted to create a folder, its module is bound to the limitation, that the new folder's module must be equal to parent folder's module except that:
• Parent folder is one of the system folders private, public, or shared. Below these folders task, calendar, and contact modules are permitted.
• Parent folder's module is one of task, calendar, or contact. Below this kind of folders task, calendar, and contact modules are permitted.
Response: Object ID of the newly created folder.
Delete folders
PUT /ajax/folders?action=delete
Parameters:
• session – A session ID previously obtained from the login module.
• timestamp – Timestamp of the last update of the deleted folders.
• tree – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
• allowed_modules – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.
• hardDelete - Optional, defaults to \"false\". If set to \"true\", the folders are deleted permanently. Otherwise, and if the underlying storage supports a trash folder and the folders are not yet located below the trash folder, they are moved to the trash folder.
Request body: An array with object IDs of the folders that shall be deleted.
Response: An array with object IDs of folders that were NOT deleted. There may be a lot of different causes for a not deleted folder: A folder has been modified in the mean time, the user does not have the permission to delete it or those permissions have just been removed, the folder does not exist, etc.
Clearing a folder's content
PUT /ajax/folders?action=clear
Parameters:
• session – A session ID previously obtained from the login module.
• tree – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
• allowed_modules – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.
Request body: A JSON array containing the folder ID(s) whose content should be cleared. NOTE: Although the requests offers to clear multiple folders at once it is recommended to clear only one folder per request since if any exception occurs (e.g. missing permissions) the complete request is going to be aborted.
Response: A JSON array containing the IDs of folders that could not be cleared due to a concurre
