Difference between revisions of "HTTP API"

(Delete Reminder)
(Corrected 'valid until')
(238 intermediate revisions by 19 users not shown)
Line 1: Line 1:
 +
{{Version_until|7.8.2}}
 +
 +
'''The latest content on this page has moved to https://documentation.open-xchange.com/components/middleware/http/latest/index.html.'''
 +
 +
Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.
 +
 
== Introduction ==
 
== Introduction ==
  
Line 29: Line 35:
 
| timestamp    || Timestamp || The latest timestamp of the returned data (see [[HTTP_API#Updates|Updates]]).
 
| timestamp    || Timestamp || The latest timestamp of the returned data (see [[HTTP_API#Updates|Updates]]).
 
|-
 
|-
| error        || String    || English error message. Present in case of errors.
+
| error        || String    || The translated error message. Present in case of errors.
 
|-
 
|-
| error_params || Array    || Replacement parameters for the error message.
+
| 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_id    || String    || Unique error identifier to help finding this error instance in the server logs.
 
|-
 
|-
| code        || String    || Error code consisting of a three-letter category and a four-digit message number, separated by a dash.
+
| 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.
 +
{| cellspacing="0" border="1"
 +
| "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).
 
|-
 
|-
| category    || Number    || Category to which the error message belongs:
+
| "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:
 
{| cellspacing="0" border="1"
 
{| cellspacing="0" border="1"
 
| 1  || An error resulting from wrong or missing input from front-end (e.g. mandatory field missing).
 
| 1  || An error resulting from wrong or missing input from front-end (e.g. mandatory field missing).
Line 50: Line 85:
 
|-
 
|-
 
| 6  || The underlying socket connection is corrupt, empty or closed. Only a temporary error that does not affect the whole system.
 
| 6  || The underlying socket connection is corrupt, empty or closed. Only a temporary error that does not affect the whole system.
|-
 
| 7  || An internal java-related (runtime) exception.
 
 
|-
 
|-
 
| 8  || A programming error which was caused by incorrect programm code.
 
| 8  || A programming error which was caused by incorrect programm code.
 
|-
 
|-
 
| 9  || A concurrent modification.
 
| 9  || A concurrent modification.
|-
 
| 10 || Error in system setup detected.
 
 
|-
 
|-
 
| 11 || The requested operation could not be performed cause an underlying resource is full or busy (e.g. IMAP folder exceeds quota).
 
| 11 || The requested operation could not be performed cause an underlying resource is full or busy (e.g. IMAP folder exceeds quota).
Line 84: Line 115:
 
|+ align="bottom" | Data size parameters
 
|+ align="bottom" | Data size parameters
 
! Error code !! Parameter indices
 
! Error code !! Parameter indices
|-
 
| AJP-0006  || 1
 
|-
 
| AJP-0020  || 1, 2
 
 
|-
 
|-
 
| CON-0101  || 2, 3
 
| CON-0101  || 2, 3
Line 102: Line 129:
  
  
==== Detailed Exception Data (Preliminary) ====
+
=== Date and time ===
Starting with some upcoming version application errors will be returned in the field "exception" in a response. The exception field will contain a JSON array containing objects that have the format specified in the following table:
+
 
 +
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 <code>'''timezone'''</code> 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.
  
{| id="ResponseBody" cellspacing="0" border="1"
+
This specification refers to these three interpretations of the type Number as separate data types. The types are described in [[#DateAndTimeTypes | Date and time types]].
|+ align="bottom" | Exception Object
+
 
! Name        !! Type      !! Value
+
{| id="DateAndTimeTypes" cellspacing="0" border="1"
 +
|+ align="bottom" | Date and time types
 +
! Type      !! Time !! Timezone !! Comment
 
|-
 
|-
| code        || String    || Error code consisting of a three-letter category and a four-digit message number, separated by a dash.
+
| Date      || No  || UTC      || Date without time.
 
|-
 
|-
| category    || Number    || Category to which the error message belongs:
+
| Time      || Yes  || User    || Date and time.
{| cellspacing="0" border="1"
 
| 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.
+
| Timestamp || Yes || UTC      || Timestamp or unique sequence number.
 
|-
 
|-
| 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).
+
=== Updates ===
|-
+
 
| 5  || A subsystem or third party service is down and therefore does not respond (e.g. database is down).
+
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 [[#ResponseBody | 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.
|-
+
 
| 6  || The underlying socket connection is corrupt, empty or closed. Only a temporary error that does not affect the whole system.
+
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.
|-
 
| 7  || An internal java-related (runtime) exception.
 
|-
 
| 8  || A programming error which was caused by incorrect programm code.
 
|-
 
| 9  || A concurrent modification.
 
|-
 
| 10 || Error in system setup detected.
 
|-
 
| 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
 
|}
 
|-
 
| message      || String    || Localized error message.
 
|-
 
| parameters  || Array    || Replacement parameters for the message. ''What are they good for if the message is already localized? -- Viktor Pracht - 2009-04-24''
 
|-
 
| logMessage  || String    || Technical error message useful for debugging the problem.  
 
|-
 
| exceptionId  || String    || Unique error identifier to help finding this error instance in the server logs.
 
|-
 
| help        || String    || Localized help text, telling the user how he may resolve the problem.
 
|-
 
| session      || String    || The session id of the session in which this exception was caused. ''When can this be '''not''' the current session? -- Viktor Pracht - 2009-04-24''
 
|-
 
| user        || Number    || The id of the user having caused the exception. ''When can this be '''not''' the current user? -- Viktor Pracht - 2009-04-24''
 
|-
 
| context      || Number    || The context id of the context in which the exception happened. ''When can this be '''not''' the current context? -- Viktor Pracht - 2009-04-24''
 
|-
 
| details      || Object    || A JSON Object containing extra information for debugging purposes.
 
|-
 
| application  || String    || Application ID of the subsystem having thrown this exception.
 
|-
 
| stacktrace  || Array    || An array of Strings containing the error trace. Note: This can be turned off in the backend, in which case an empty array will be returned.  
 
|}
 
  
=== Date and time ===
+
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.
  
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.
+
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.
  
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 <code>'''timezone'''</code> 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.
+
=== Editing ===
  
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.
+
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.
  
This specification refers to these three interpretations of the type Number as separate data types. The types are described in [[#DateAndTimeTypes | Date and time types]].
+
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.
 
 
{| id="DateAndTimeTypes" cellspacing="0" border="1"
 
|+ align="bottom" | 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.
 
|-
 
|}
 
 
 
=== 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 [[#ResponseBody | 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.
 
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.
Line 211: Line 177:
 
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:
 
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>
 
  <html>
 
     <head>
 
     <head>
 +
        <META http-equiv="Content-Type" content=\"text/html; charset=UTF-8\">
 
         <script type="text/javascript">
 
         <script type="text/javascript">
             (owner || parent).callback_<b>action</b>(<b>{json}</b>);
+
             (parent["callback_<b>action</b>"] || window.opener && window.opener["callback_<b>action</b>"])
 +
            (<b>{json}</b>)
 
         </script>
 
         </script>
 
     </head>
 
     </head>
 
  </html>
 
  </html>
  
The placeholders <code>{json}</code> is replaced by the response with the timestamp that would be expected from the corresponding PUT method. The placeholder <code>action</code> is replaced by the value of the parameter <code>action</code> of the request. The content-type of the answer is <code>text/html</code>.
+
The placeholders <code>{json}</code> is replaced by the response with the timestamp that would be expected from the corresponding PUT method. The placeholder <code>action</code> is replaced by the value of the parameter <code>action</code> 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 <code>text/html</code>.
  
 
Non-browser clients don't need to interpret HTML or JavaScript. The JSON data can be recognized by the outermost <code>({</code> and <code>})</code>, where the inner braces are part of the JSON value. For example, the regular expression <code>\((\{.*\})\)</code> captures the entire JSON value in its first capturing group.
 
Non-browser clients don't need to interpret HTML or JavaScript. The JSON data can be recognized by the outermost <code>({</code> and <code>})</code>, where the inner braces are part of the JSON value. For example, the regular expression <code>\((\{.*\})\)</code> captures the entire JSON value in its first capturing group.
Line 229: Line 198:
 
* a list of URI parameters which can or must be supplied by the client,
 
* a list of URI parameters which can or must be supplied by the client,
 
* for PUT requests, content of the request body,
 
* for PUT requests, content of the request body,
 +
* for POST requests all described parameters are normally expected in the request body, exceptions are documented,
 
* "Response with timestamp:"if the timestamp field is required in the response body or simply "Response:" if not,
 
* "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.
 
* content of the response payload, unless it is supposed to be empty.
Line 256: Line 226:
 
| 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.
 
| 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 1 and 10 (inclusive). 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.
|-
 
| 103  || number_of_links    || Number  || Number of links. '''deprecated'''
 
 
|-
 
|-
 
| 104  || number_of_attachments    || Number  || Number of attachments  
 
| 104  || number_of_attachments    || Number  || Number of attachments  
Line 267: Line 235:
 
== Module "login" ==
 
== Module "login" ==
  
The login module is used to obtain a session from the user's login credentials.
+
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]]".
 +
 
 +
Because of security reasons each login variation will reject requests containing the parameter "password" within the URL query (starting with 7.8.0).
  
 
=== Login ===
 
=== Login ===
Line 273: Line 243:
 
POST <code>/ajax/login?action=login</code>
 
POST <code>/ajax/login?action=login</code>
  
Parameters:
+
Parameters are normally expected in the POST request body:
 
* <code>name</code> – The login name.
 
* <code>name</code> – The login name.
* <code>password</code> – The password.
+
* <code>password</code> – The password MUST be placed in the request body, otherwise the login request will be denied.
 
* <code>authId</code> (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.
 
* <code>authId</code> (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.
 
* <code>client</code> (optional) – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.
 
* <code>client</code> (optional) – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.
Line 288: Line 258:
 
POST <code>/ajax/login?action=formlogin</code>
 
POST <code>/ajax/login?action=formlogin</code>
  
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 (<code>/usr/share/doc/open-xchange</code>) under <code>examples/login.html</code>.
+
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 (<code>/usr/share/doc/open-xchange-core</code>) under <code>examples/login.html</code>.
  
 
Parameters:
 
Parameters:
Line 305: Line 275:
 
For a complete description of the FormLogin-Process please see [[FormLogin|this documentation]]
 
For a complete description of the FormLogin-Process please see [[FormLogin|this documentation]]
  
=== Logout ===
+
=== Token Login (since 7.0.1) ===
  
GET <code>/ajax/login?action=logout</code>
+
POST <code>/ajax/login?action=tokenLogin</code>
  
Parameters:
+
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.
* <code>session</code> – A session ID previously obtained from the login module.
 
  
=== Refresh secret cookie (since 6.18.2) ===
+
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.
  
GET <code>/ajax/login?action=refreshSecret</code>
+
DISCLAIMER: This request MUST NOT be used by some server side instance. If some server side instance uses this request to create a session for a browser on some client machine, then you have to transfer the full URL with server and client token over some connection to the client. This creates a VULNERABILITY if this is done. The token login method is only secure if this request is already sent from the same machine that later runs the browser using the created session.
  
 
Parameters:
 
Parameters:
* <code>session</code> – A session ID previously obtained from the login module.
+
* <code>login</code> – The login information.
 +
* <code>password</code> – The password.
 +
* <code>clientToken</code> – Client side identifier for accessing the session later. The value should be some token that is unique for every login request.
 +
* <code>authId</code> – 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.
 +
* <code>client</code> – 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.
 +
* <code>version</code> – Version of the HTTP/JSON interface client. Only for statistic evaluations.
 +
* <code>autologin</code> – 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.
 +
* <code>uiWebPath</code> (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.
 +
* <code>clientIP</code> (optional) IP address of the client host for that the session is created. If this parameter is not specified the IP address of the HTTP 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.
 +
* <code>clientUserAgent</code> (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.
 +
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect.  
  
=== Refresh auto-login cookie ===
 
  
GET <code>/ajax/login?action=store</code>
+
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 <code style="white-space: nowrap"><var>redirect_URL</var>&amp;clientToken=<var>token</var></code>. Both tokens are necessary to use the session and both tokens must match. Otherwise the session is terminated.
  
Parameters:
+
=== Tokens (since 7.0.1) ===
* <code>session</code> – A session ID previously obtained from the login module.
 
  
=== Redirect ===
+
POST <code>/ajax/login?action=tokens</code>
  
GET <code>/ajax/login;jsessionid=1157370816112.OX1?action=redirect</code>
+
This request allows clients to access a session created with the [[#Token_Login_.28since_7.0.1.29 | tokenLogin]] request. When accessing the session its life time is extended equally to every other session.
  
'''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 AJP 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:
 +
* <code>serverToken</code> – Server side identifier for accessing the session. This identifier was created by the server and is contained in the tokenLogin response.
 +
* <code>clientToken</code> – Client side identifier for accessing the session. This identifier was created by the client and passed within the POST data of the tokenLogin request.
 +
* <code>client</code> – 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 [[#ResponseBody | 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 <code>/ajax/login?action=logout</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 
 +
=== Refresh secret cookie (since 6.18.2) ===
 +
 
 +
GET <code>/ajax/login?action=refreshSecret</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 
 +
=== Refresh auto-login cookie ===
 +
 
 +
GET <code>/ajax/login?action=store</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 
 +
=== Autologin ===
 +
 
 +
If the session ID was stored in a cookie before via the [[#Refresh_auto-login_cookie | store request]], the user can reuse his old session by using the autologin request.
 +
 
 +
GET <code>/ajax/login?action=autologin</code>
 +
 
 +
Parameters:
 +
 
 +
* <code>authId</code> – 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.
 +
* <code>client</code> (optional) – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.
 +
 
 +
Response: A JSON object containing the session ID used for all subsequent requests.
 +
 
 +
=== Redirect ===
 +
 
 +
GET <code>/ajax/login;jsessionid=1157370816112.OX1?action=redirect</code>
 +
 
 +
'''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:
 
Parameters:
Line 349: Line 372:
  
 
Response: A JSON object containing the string "1" as data attribute.
 
Response: A JSON object containing the string "1" as data attribute.
 +
 +
=== Redeem Token (since 7.4.0)===
 +
 +
POST <code>/ajax/login?action=redeemToken</code>
 +
 +
Parameters:
 +
* <code>token</code> – The token created with [[#Get_a_login_token | acquireToken]].
 +
* <code>authId</code> – 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.
 +
* <code>client</code> – 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.
 +
* <code>secret</code> – 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" ==
 
== Module "config" ==
Line 401: Line 436:
 
** <code>participants</code>
 
** <code>participants</code>
 
*** <code>autoSearch</code> - If a search for all users, groups and resources when participant selection dialog is opened. (read-only, added 2008-10-09/SP5)
 
*** <code>autoSearch</code> - If a search for all users, groups and resources when participant selection dialog is opened. (read-only, added 2008-10-09/SP5)
*** <code>maximumNumberParticipants</code> – Defines the maximum number of participants for appointments and tasks. (read-only, added 2008-10-20/SP5)
 
 
*** <code>showWithoutEmail</code> - If external participants without email should be shown.
 
*** <code>showWithoutEmail</code> - If external participants without email should be shown.
 
*** <code>showDialog</code> – Enables participant selection dialog for appointments and tasks. (read-only, added 2008-04-30/SP4)
 
*** <code>showDialog</code> – Enables participant selection dialog for appointments and tasks. (read-only, added 2008-04-30/SP4)
Line 465: Line 499:
 
*** <code>infostore</code>
 
*** <code>infostore</code>
 
**** <code>gui</code> GUI settings for the infostore module
 
**** <code>gui</code> GUI settings for the infostore module
 +
**** <code>folder</code> – the standard infostore folders (read-only, since 7.6.0)
 +
***** <code>trash</code> – identifier of the default infostore trash folder (read-only, since 7.6.0)
 +
***** <code>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)
 +
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)
 +
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)
 +
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)
 +
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.0)
 
**** <code>module</code>
 
**** <code>module</code>
 
*** <code>interfaces</code>
 
*** <code>interfaces</code>
Line 520: Line 561:
 
Request body: The new value of the node specified by path.
 
Request body: The new value of the node specified by path.
  
== Module "folders" ==
 
  
The folders module is used to access the OX folder structure.
+
=== Get a property (since 7.6.2) ===
 +
 
 +
GET <code>/ajax/config?action=get_property</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>name</code> – The name of the property to return.
 +
 
 +
Response: A JSON response providing the property's name and its value; e.g.
 +
<code>
 +
  {
 +
    "data": {
 +
        "name": "com.openexchange.dummy.prop001",
 +
        "value": "test1234"
 +
    }
 +
  }
 +
</code>
 +
 
 +
=== Set a property (since 7.6.2) ===
 +
 
 +
Note: Only allowed for context administrator!
 +
 
 +
PUT <code>/ajax/config?action=set_property</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>name</code> – The name of the property to set.
 +
 
 +
Request body: A JSON object providing the value to set; e.g
 +
<code>
 +
  {"value":"test1237"}
 +
</code>
 +
 
 +
 
 +
Response: A JSON response providing the property's name and its new value; e.g.
 +
<code>
 +
  {
 +
    "data": {
 +
        "name": "com.openexchange.dummy.prop001",
 +
        "value": "test1237"
 +
    }
 +
  }
 +
</code>
 +
 
 +
== Module "folders" ==
 +
 
 +
The folders module is used to access the OX folder structure.
  
 
=== Special System Folders ===
 
=== Special System Folders ===
Line 582: Line 668:
 
|-
 
|-
 
| 5 || system folder
 
| 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
 
|}
 
|}
 
|-
 
|-
Line 602: Line 702:
 
| 312 || deleted        || Number          || The number of deleted 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 | capabilities]].
+
| 313 || capabilities || Number || Bit mask containing information about mailing system capabilites, as described in [[#Capabilities | capabilities]].
 
|-
 
|-
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not.
+
| 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.
 
| 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 [[#DefaultTypes | Standard folder types]]
 
| 316 || standard_folder_type || Number || Indicates the default folder type. Zero for non-default folder. See [[#DefaultTypes | Standard folder types]]
 +
|-
 +
| 317 || supported_capabilities || Array || Each element is a String identifying a supported folder capability as described in [[#SupportedCapabilities | supported capabilities]]. Only applicable for non-mail folders. Read Only, Since 7.4.0.
 +
|-
 +
| 318 || account_id || String || Will be <code>null</code> 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.
 
| 3010 || com.openexchange.publish.publicationFlag || Boolean || Indicates whether this folder is published. Read Only, provided by the com.openexchange.publish plugin, since 6.14.
Line 615: Line 720:
 
|-
 
|-
 
| 3030 || com.openexchange.folderstorage.displayName || String || Provides the display of the folder's owner. Read Only, Since 6.20.
 
| 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 [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.
 
|}
 
|}
 
 
  
  
Line 690: Line 795:
 
| rights || String  || For mail folders, the rights string as defined in RFC 2086.
 
| 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.
+
| 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").
 
|-
 
|-
| 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).
 +
|}
 +
 
 +
{| id="ExtendedPermissionObject" cellspacing="0" border="1"
 +
|+ align="bottom" | 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 [[#PermissionFlags | 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 [[#DetailedContactData | 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.
 
|}
 
|}
  
Line 709: Line 849:
 
| 4 || Mailing system supports folder subscription.
 
| 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.
  
 
{| id="DefaultTypes" cellspacing="0" border="1"
 
{| id="DefaultTypes" cellspacing="0" border="1"
Line 733: Line 875:
 
|-
 
|-
 
| 12 || Trash.
 
| 12 || Trash.
 +
|}
 +
 +
{| id="SupportedCapabilities" cellspacing="0" border="1"
 +
|+ align="bottom" | 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.
 
|}
 
|}
  
Line 800: Line 957:
 
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
 
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
 
* <code>allowed_modules</code> – (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.
 
* <code>allowed_modules</code> – (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.
 +
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)
  
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present.
+
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders for all modules except mail. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:
 +
 
 +
<pre>
 +
{
 +
  "folder":{
 +
    "permissions":[
 +
      {
 +
        "bits":403710016,
 +
        "entity":84,
 +
        "group":false
 +
      },
 +
      {
 +
        "type":"guest",
 +
        "email_address":"john.doe@example.com",
 +
        "display_name":"John Doe",
 +
        "bits":257
 +
      }
 +
    ]
 +
  },
 +
  "notification":{
 +
    "transport":"mail",
 +
    "message":"Hi!\nHave a look at this!"
 +
  }
 +
}
 +
</pre>
  
 
=== Create a folder ===
 
=== Create a folder ===
Line 813: Line 995:
 
* <code>allowed_modules</code> – (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.
 
* <code>allowed_modules</code> – (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 [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. The field id should not be present.
+
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. The field id should not be present. It is possible to let added permission entities be notified about newly shared folders for all modules except mail. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:
 +
 
 +
<pre>
 +
{
 +
  "folder":{
 +
    "permissions":[
 +
      {
 +
        "bits":403710016,
 +
        "entity":84,
 +
        "group":false
 +
      },
 +
      {
 +
        "type":"guest",
 +
        "email_address":"john.doe@example.com",
 +
        "display_name":"John Doe",
 +
        "bits":257
 +
      }
 +
    ]
 +
  },
 +
  "notification":{
 +
    "transport":"mail",
 +
    "message":"Hi!\nHave a look at this!"
 +
  }
 +
}
 +
</pre>
  
 
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:
 
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:
Line 827: Line 1,033:
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>timestamp</code> – Timestamp of the last update of the deleted folders.
+
* <code>timestamp</code> – The optional timestamp of the last update of the deleted folders.
 
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
 
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
 
* <code>allowed_modules</code> – (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.  
 
* <code>allowed_modules</code> – (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.  
 +
* <code>hardDelete</code> - 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.
 
Request body: An array with object IDs of the folders that shall be deleted.
Line 849: Line 1,056:
  
 
=== Get all visible folder of a certain module  (since v6.18.2)  ===
 
=== Get all visible folder of a certain module  (since v6.18.2)  ===
PUT <code>/ajax/folders?action=allVisible</code>  
+
GET <code>/ajax/folders?action=allVisible</code>  
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>tree</code> – The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
 
* <code>tree</code> – The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
* <code>content_type</code> – The desired content type (either numbers or strings; e.g. "tasks", "calendar", "contacts", "mail")
+
* <code>content_type</code> – The desired content type (either numbers or strings; e.g. "tasks", "calendar", "contacts", "mail", "infostore")
 
* <code>columns</code> –  A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]].
 
* <code>columns</code> –  A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]].
 
Request body: None
 
  
 
Response with timestamp: A JSON object containing three fields: "private", "public, and "shared". Each field is a JSON array with data for all folders. Each folder is itself described by an array.
 
Response with timestamp: A JSON object containing three fields: "private", "public, and "shared". Each field is a JSON array with data for all folders. Each folder is itself described by an array.
  
== Module "tasks" ==
+
=== Get shared folders (Since 7.8.0, Preliminary) ===
  
The tasks module is used to access task information.
+
GET <code>/ajax/folders?action=shares</code>
  
=== Get all tasks ===
+
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]].
 +
* <code>all</code> – Set to <code>1</code> to list even not subscribed folders.
 +
* <code>tree</code> – The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
 +
* <code>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".
 +
 
 +
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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.
 +
 
 +
=== Notify about shared folder (Since 7.8.0, Preliminary) ===
 +
 
 +
PUT <code>/ajax/folders?action=notify</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>tree</code> – The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
 +
* <code>id</code> – Object ID of the shared folder to notify about.
 +
 
 +
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).
 +
 
 +
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.
 +
 
 +
== Module "tasks" ==
 +
 
 +
The tasks module is used to access task information.
 +
 
 +
=== Get all tasks ===
  
 
GET <code>/ajax/tasks?action=all</code>
 
GET <code>/ajax/tasks?action=all</code>
Line 884: Line 1,115:
 
| 200 || title                    || String      || Short description.
 
| 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.
+
| 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.
+
| 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.
 
| 203 || note                    || String      || Long description.
Line 936: Line 1,167:
 
|-
 
|-
 
| 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)
 
| 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.
 
|}
 
|}
  
Line 1,030: Line 1,263:
 
| 301 || percent_completed || Number || How much of the task is completed. An integer number between 0 and 100.
 
| 301 || percent_completed || Number || How much of the task is completed. An integer number between 0 and 100.
 
|-
 
|-
| 302 || actual_costs
+
| 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
 
| 303 || actual_duration
Line 1,038: Line 1,271:
 
| 305 || billing_information
 
| 305 || billing_information
 
|-
 
|-
| 307 || target_costs
+
| 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
 
| 308 || target_duration
Line 1,051: Line 1,284:
 
|-
 
|-
 
| 315 || date_completed
 
| 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.
 
|}
 
|}
  
Line 1,076: Line 1,313:
 
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
 
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
 
* <code>timestamp</code> – Timestamp of the last update of the requested tasks.
 
* <code>timestamp</code> – Timestamp of the last update of the requested tasks.
* <code>ignore</code> (mandatory - should be set to "deleted") (deprecated) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.
+
* <code>ignore</code> – Which kinds of updates should be ignored. Omit this parameter or set it to "deleted" to not have deleted tasks identifier in the response. Set this parameter to "false" and the response contains deleted tasks identifier.
  
Response with timestamp: An array with new, modified and deleted tasks. New and modified tasks are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted tasks (should the <code>ignore</code> parameter be ever implemented) would be identified by their object IDs as plain strings, without being part of a nested array.
+
Response with timestamp: An array with new, modified and deleted tasks. New and modified tasks are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted tasks would be identified by their object IDs as plain strings, without being part of a nested array.
  
 
=== Get a task ===
 
=== Get a task ===
Line 1,189: Line 1,426:
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>folder</code> – Object ID of the folder, whose contents are queried.
+
* <code>folder</code> – Object ID of the folder, whose contents are queried (optional from 6.22.2 on: If not set, the contents of all visible folders are used instead).
 
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for contacts are defined in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]].
 
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for contacts are defined in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]].
 
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
 
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
Line 1,200: Line 1,437:
 
|+ align="bottom" | Detailed contact data
 
|+ align="bottom" | Detailed contact data
 
! ID  !! Displayed name              !! Name                !! Type  !! Value
 
! ID  !! Displayed name              !! Name                !! Type  !! Value
 +
|-
 +
| 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
 
| 500 || Display name                || display_name        || String
Line 1,225: Line 1,464:
 
| 511 || Birthday                    || birthday            || Date
 
| 511 || Birthday                    || birthday            || Date
 
|-
 
|-
| 512 || Martial status              || marital_status || String
+
| 512 || Marital status              || marital_status || String
 
|-
 
|-
 
| 513 || Number of children          || number_of_children || String
 
| 513 || Number of children          || number_of_children || String
Line 1,235: Line 1,474:
 
| 516 || Spouse name                || spouse_name          || String
 
| 516 || Spouse name                || spouse_name          || String
 
|-
 
|-
| 517 || Anniversay                  || anniversary          || Date
+
| 517 || Anniversary                || anniversary          || Date
 
|-
 
|-
 
| 518 || Note                        || note                || String
 
| 518 || Note                        || note                || String
Line 1,249: Line 1,488:
 
| 523 || Street business            || street_business      || String
 
| 523 || Street business            || street_business      || String
 
|-
 
|-
| 524 ||                             || internal_userid || Number
+
| 524 || Internal user id            || user_id || Number
 
|-
 
|-
 
| 525 || Postal code business        || postal_code_business || String
 
| 525 || Postal code business        || postal_code_business || String
Line 1,337: Line 1,576:
 
| 567 || Telephone IP                || telephone_ip        || String
 
| 567 || Telephone IP                || telephone_ip        || String
 
|-
 
|-
| 568 || Telephone assostant         || telephone_assistant  || String
+
| 568 || Telephone assistant         || telephone_assistant  || String
 
|-
 
|-
 
| 569 || Company                    || company              || String
 
| 569 || Company                    || company              || String
Line 1,382: Line 1,621:
 
|-
 
|-
 
| 590 || Dynamic Field 20            || userfield20 || String || Contains a UUID if one was assigned (after 6.18.2)
 
| 590 || Dynamic Field 20            || userfield20 || String || Contains a UUID if one was assigned (after 6.18.2)
|-
 
| 591 ||                            || links                || Array  || An array of objects containing links to other contacts. Each contact is describes by an object as defined in [[#ContactLinkData | Contact link data]]. '''deprecated'''
 
 
|-
 
|-
 
| 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 [[#DistributionListMember | Distribution list member]].
 
| 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 [[#DistributionListMember | Distribution list member]].
 
|-
 
|-
 
| 594 || Number of distributionlists || number_of_distribution_list || Number
 
| 594 || Number of distributionlists || number_of_distribution_list || Number
|-
 
| 595 ||                            || number_of_links || Number || '''deprecated'''
 
 
|-
 
|-
 
| 596 ||                            || number_of_images || Number
 
| 596 ||                            || number_of_images || Number
Line 1,422: Line 1,657:
 
|}
 
|}
  
 
{| id="ContactLinkData" cellspacing="0" border="1"
 
|+ align="bottom" | Contact link data
 
! Name      !! Type  !! Value
 
|-
 
| id        || String || Object ID
 
|-
 
| first_name || String || First name
 
|-
 
| last_name  || String || Last name
 
|}
 
  
 
{| id="DistributionListMember" cellspacing="0" border="1"
 
{| id="DistributionListMember" cellspacing="0" border="1"
Line 1,620: Line 1,844:
 
|-
 
|-
 
| emailAutoComplete || Boolean || If set to true, results are guaranteed to contain at least one email adress and the search is performed as if orSearch were set to true. The actual value of orSearch is ignored.
 
| emailAutoComplete || Boolean || If set to true, results are guaranteed to contain at least one email adress and the search is performed as if orSearch were set to true. The actual value of orSearch is ignored.
 +
|-
 +
| exactMatch || Boolean || If set to true, contacts are returned where the specified patterns match the corresponding fields exactly. Otherwise, a 'startsWith' or 'substring' comparison is used based on the 'orSearch' parameter. (requires version > 6.22.1)
 
|}
 
|}
  
Line 1,639: Line 1,865:
 
Response: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
 
Response: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
  
=== Associate two contacts (Since 6.18.1, Preliminary) ===
+
=== Search contacts by anniversary (Since 6.22.1, Preliminary) ===
 +
 
 +
Find contacts whose anniversary falls into a timerange.
  
PUT <code>/ajax/contacts?action=associate</code>
+
GET <code>/ajax/contacts?action=anniversaries</code>
  
 
Parameters:
 
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>start</code> – The lower (inclusive) limit of the requested time-range.
 +
* <code>end</code> – The upper (exclusive) limit of the requested time-range.
 +
* <code>columns</code> – The requested fields.
 +
* <code>folder</code> (optional)  – Object ID of the parent folder that is searched. If not set, all visible folders are used.
 +
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If not specified, the results are sorted ascending by their anniversary in the supplied timerange. If this parameter is specified, then the parameter order must be also specified.
 +
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
 +
* <code>collation</code> (optional)  – Allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter <code>sort</code> should be set for this to work.
  
* uuid1: The UUID of the first contact (not needed if you use folder and id instead)
+
Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
* folder1: ID of the folder the first contact is in (not needed if you use UUID)
 
* id1: ID of the first contact (not needed if you use UUID)
 
* uuid2: The UUID of the second contact (not needed if you use folder and id instead)
 
* folder2: ID of the folder the second contact is in (not needed if you use UUID)
 
* id2: ID of the second contact (not needed if you use UUID)
 
  
Response: None.
+
=== Search contacts by birthday (Since 6.22.1, Preliminary) ===
  
=== Dissociate two contacts (Since 6.18.1, Preliminary) ===
+
Find contacts whose birthday falls into a timerange.
  
PUT <code>/ajax/contacts?action=dissociate</code>
+
GET <code>/ajax/contacts?action=birthdays</code>
  
 
Parameters:
 
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>start</code> – The lower (inclusive) limit of the requested time-range.
 +
* <code>end</code> – The upper (exclusive) limit of the requested time-range.
 +
* <code>columns</code> – The requested fields.
 +
* <code>folder</code> (optional)  – Object ID of the parent folder that is searched. If not set, all visible folders are used.
 +
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If not specified, the results are sorted ascending by their birthday in the supplied timerange. If this parameter is specified, then the parameter order must be also specified.
 +
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
 +
* <code>collation</code> (optional)  – Allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter <code>sort</code> should be set for this to work.
  
* uuid1: The UUID of the first contact (not needed if you use folder and id instead)
+
Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
* folder1: ID of the folder the first contact is in (not needed if you use UUID)
 
* id1: ID of the first contact (not needed if you use UUID)
 
* uuid2: The UUID of the second contact (not needed if you use folder and id instead)
 
* folder2: ID of the folder the second contact is in (not needed if you use UUID)
 
* id2: ID of the second contact (not needed if you use UUID)
 
  
Response: None.
+
=== Auto-complete contacts (Since 7.6.1, Preliminary) ===
  
=== Get associated contacts of a contact (Since 6.18.1, Preliminary) ===
+
Find contacts based on a prefix, usually used to auto-complete e-mail recipients while the user is typing.
  
GET <code>/ajax/contacts?action=getAssociated</code>
+
GET <code>/ajax/contacts?action=autocomplete</code>
  
 
Parameters:
 
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>query</code> – The query to search for.
 +
* <code>folder</code> (optional)  – Object ID of the parent folder that is searched. If not set, all visible folders are used.
 +
* <code>email</code> (optional)  – Whether to only include contacts with at least one e-mail address. Defaults to "true".
 +
* <code>columns</code> – The requested fields.
 +
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified. Since 7.8.1: If this parameter is missing, response is sorted by a user-specific use count of contacts, ID of contacts' parent folder and display name.
 +
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is
 +
* <code>collation</code> (optional)  – Allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter <code>sort</code> should be set for this to work.
 +
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.
 +
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.
  
* uuid: The UUID of this contact (not needed if you use folder and id instead)
+
Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
* folder: ID of the folder the contact is in (not needed if you use UUID)
 
* id: ID of the contact (not needed if you use UUID)
 
  
Response: A JSON response with the data field containing an array with the UUID of every associated contact.
+
== Module "calendar" ==
  
=== Get association status of two contacts (Since 6.18.1, Preliminary) ===
+
The calendar module is used to access calendar data.
 
 
GET <code>/ajax/contacts?action=getAssociation</code>
 
 
 
* uuid1: The UUID of the first contact (not needed if you use folder and id instead)
 
* folder1: ID of the folder the first contact is in (not needed if you use UUID)
 
* id1: ID of the first contact (not needed if you use UUID)
 
* uuid2: The UUID of the second contact (not needed if you use folder and id instead)
 
* folder2: ID of the folder the second contact is in (not needed if you use UUID)
 
* id2: ID of the second contact (not needed if you use UUID)
 
 
 
Response: A JSON response with the data field containing the status as integer meaning the following:
 
* 1: not referring to the same person
 
* 2: the two contacts represent the same person
 
* 3: contacts have never been explicitly associated or dissociated
 
 
 
=== Get contact by uuid (Since 6.18.1, Preliminary) ===
 
 
 
GET <code>/ajax/contacts?action=getByUuid</code>
 
 
 
* uuid: The UUID of this contact (not needed if you use folder and id instead)
 
* folder: ID of the folder the contact is in (not needed if you use UUID)
 
* id: ID of the contact (not needed if you use UUID)
 
 
 
Response: A JSON response with the data field containing the full contact data of every single associated contact.
 
 
 
== Module "calendar" ==
 
 
 
The calendar module is used to access calendar data.
 
  
 
=== Get all appointments ===
 
=== Get all appointments ===
Line 1,741: Line 1,955:
 
|-
 
|-
 
| 400 || location    || String  || Location
 
| 400 || location    || String  || Location
|-
 
| 401 || full_time  || Boolean || True if the appointment is a whole day appointment, false otherwise.
 
 
|-
 
|-
 
| 402 || shown_as    || Number  || Describes, how this appointment appears in availability queries:
 
| 402 || shown_as    || Number  || Describes, how this appointment appears in availability queries:
Line 1,801: Line 2,013:
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>folder</code> – Object ID of the folder, whose contents are queried.
+
* <code>folder</code> – Object ID of the folder, whose contents are queried. That parameter may be absent in case <code>ignore</code> is set to "deleted", which means all accessible calendar folders are considered. If  <code>ignore</code> is not set to "deleted", that parameter is mandatory.
 
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[#DetailedAppointmentData | Detailed appointment data]].
 
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[#DetailedAppointmentData | Detailed appointment data]].
 
* <code>timestamp</code> – Timestamp of the last update of the requested appointments.
 
* <code>timestamp</code> – Timestamp of the last update of the requested appointments.
* <code>start</code> (optional) – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.
+
* <code>start</code> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)
* <code>end</code> (optional) – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.
+
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)
 
* <code>ignore</code> (mandatory - should be set to "deleted") (deprecated) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.
 
* <code>ignore</code> (mandatory - should be set to "deleted") (deprecated) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.
 
* <code>recurrence_master</code> – Extract the recurrence to several appointments. The default value is false so every appointment of the recurrence will be calculated.
 
* <code>recurrence_master</code> – Extract the recurrence to several appointments. The default value is false so every appointment of the recurrence will be calculated.
Line 1,877: Line 2,089:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>id</code> – Object ID of the appointment to confirm.
 
* <code>id</code> – Object ID of the appointment to confirm.
 +
* <code>occurrence</code> – The numeric identifier of the occurrence to which the confirmation applies (in case "id" denotes a series appointment). Available with v7.6.0
 
* <code>folder</code> – ID of the folder through which the appointment is accessed.
 
* <code>folder</code> – ID of the folder through which the appointment is accessed.
 
* <code>timestamp</code> – Timestamp of the last update of the to confirmed appointment.
 
* <code>timestamp</code> – Timestamp of the last update of the to confirmed appointment.
Line 1,969: Line 2,182:
  
 
Response: An object object with the field "id" containing the ox-object id, if existing, an error message otherwise.
 
Response: An object object with the field "id" containing the ox-object id, if existing, an error message otherwise.
 +
 +
=== Get all Change Exceptions (Since v7.2.0) ===
 +
 +
GET <code>/ajax/calendar?action=getChangeExceptions</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>id</code> – Object id of the appointment series.
 +
* <code>folder</code> – Folder ID of the requested appointments.
 +
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier.
 +
 +
Response with timestamp: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
  
 
== Module "mail" ==
 
== Module "mail" ==
Line 1,996: Line 2,221:
 
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified.
 
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified.
 
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
 
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
 +
* <code>left_hand_limit</code> - A positive integer number to specify the "left-hand" limit of the range to return
 +
* <code>right_hand_limit</code> - A positive integer number to specify the "right-hand" limit of the range to return
 +
* <code>limit</code> - A positive integer number to specify how many items shall be returned according to given sorting; overrides <code>left_hand_limit</code>/<code>right_hand_limit</code> parameters and is equal to <code>left_hand_limit=0</code> and <code>right_hand_limit=&lt;limit&gt;</code>
  
 
Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
 
Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
Line 2,003: Line 2,231:
 
! ID  !! Name                !! Type    !! Value
 
! 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 1 and 10 (inclusive).
+
| 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
 
| 600 || id                  || String  || Object ID
Line 2,042: Line 2,270:
 
|-
 
|-
 
| 64 || user
 
| 64 || user
 +
|-
 +
| 128 || spam
 
|-
 
|-
 
| 256 || forwarded
 
| 256 || forwarded
Line 2,081: Line 2,311:
 
|-
 
|-
 
|    || nested_msgs          || Array  || Each element is a mail object as described in this table, except for fields id, folder_id and attachment.
 
|    || 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 <tt>action=get&attach_src=true</tt>
 +
 +
|-
 +
|    || 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).
 
|}
 
|}
  
Line 2,099: Line 2,340:
 
| disp        || String || Attachment's disposition: null, inline, attachment or alternative.
 
| disp        || String || Attachment's disposition: null, inline, attachment or alternative.
 
|}
 
|}
 +
 +
=== Get all mail conversations (since v7.x) ===
 +
 +
GET <code>/ajax/mail?action=threadedAll</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>folder</code> – Object ID of the folder, whose contents are queried.
 +
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in [[#DetailedMailData | Detailed mail data]].
 +
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified. <b>Note</b>: Applies only to root-level messages.
 +
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified. <b>Note</b>: Applies only to root-level messages.
 +
* <code>includeSent</code> - A boolean value to signal that conversations also include messages taken from special "sent" aka "sent items" folder
 +
* <code>left_hand_limit</code> - A positive integer number to specify the "left-hand" limit of the range to return. <b>Note</b>: Applies only to root-level messages.
 +
* <code>right_hand_limit</code> - A positive integer number to specify the "right-hand" limit of the range to return. <b>Note</b>: Applies only to root-level messages.
 +
* <code>limit</code> - A positive integer number to specify how many items shall be returned according to given sorting; overrides <code>left_hand_limit</code>/<code>right_hand_limit</code> parameters and is equal to <code>left_hand_limit=0</code> and <code>right_hand_limit=&lt;limit&gt;</code>. <b>Note</b>: Applies only to root-level messages.
 +
 +
Response (not IMAP: with timestamp): An JSON array consisting of JSON objects, each representing a conversation's root message along with its message thread. The root message's JSON object is filled according to specified columns and is enhanced by special <code>"thread"</code> JSON field representing the full message thread (including the root message itself). The <code>"thread"</code> JSON field is a JSON array of JSON objects; each representing a message in the conversation sorted by time-line, also filled with specified columns. E.g.
 +
 +
<pre>
 +
{
 +
  "flags":32,
 +
  "color_label":0,
 +
  "unreadCount":0,
 +
  "id":"263852",
 +
  "folder_id":"default0/INBOX",
 +
  "thread":[
 +
      {
 +
        "id":"263852",
 +
        "folder_id":"default0/INBOX",
 +
        "flags":32,
 +
        "color_label":0
 +
      },
 +
      {
 +
        "id":"263853",
 +
        "folder_id":"default0/INBOX",
 +
        "flags":32,
 +
        "color_label":0
 +
      },
 +
      {
 +
        "id":"26323",
 +
        "folder_id":"default0/Sent",
 +
        "flags":32,
 +
        "color_label":0
 +
      },
 +
      {
 +
        "id":"263854",
 +
        "folder_id":"default0/INBOX",
 +
        "flags":32,
 +
        "color_label":0
 +
      }
 +
  ]
 +
}
 +
</pre>
  
 
=== Search mails ===
 
=== Search mails ===
Line 2,116: Line 2,410:
 
Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
 
Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
  
=== Get a list of mails ===
 
  
PUT <code>/ajax/mail?action=list</code>
+
=== Search mails (alternative) ===
 +
 
 +
PUT <code>/ajax/mail?action=search</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>folder</code> – Object ID of the folder, whose contents are queried.
 +
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for mails are defined in [[#DetailedMailData | Detailed mail data]].
 +
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified.
 +
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
 +
 
 +
Request Body: A JSON object containing filters. <code>{"filter":<i>[search term]</i>}</code>
 +
 
 +
This section describes the syntax of the optional JSON object representing the search term.
 +
In general the structure of a search term is in prefix notation; meaning the operator is written before its operands:
 +
 
 +
<code>[">", 5, 2]</code>
 +
 
 +
The available operators are:
 +
* Comparison operators ">", "<", "=", "<=", ">=", "<>"
 +
* logic operators "not", "and", "or"
 +
 
 +
Comparison operators have exactly two operands. Each operand can be either a field name or a constant. A field name is an object with the member "field" specifying the field name, e.g. <code>{ field: "from" }</code>. The available field names are <code>from</code>, <code>to</code>, <code>cc</code>, <code>bcc</code>, <code>subject</code>, <code>received_date</code>, <code>sent_date</code>, <code>size</code>,<code>flags</code>, <code>content</code>, <code>content_type</code>, <code>disp</code> and <code>priority</code> as defined in [[#DetailedMailData | Detailed mail data]]. Primitive JSON types are interpreted as constants. Arrays are not valid operands for comparison 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.
 +
 
 +
<code>
 +
    {"filter":
 +
        ["or",
 +
            ["and",
 +
                ["=", {"field":"to"}, "test1@example.org"],
 +
                ["not",
 +
                    ["=", {"field":"from"}, "test2@example.org"]
 +
                ],
 +
                [">", {"field":"received_date"}, "1458063382000"]
 +
            ],
 +
            ["=", {"field":"subject"}, "TestSubject"]
 +
        ]
 +
    }
 +
</code>
 +
 
 +
Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
 +
 
 +
=== Get a list of mails ===
 +
 
 +
PUT <code>/ajax/mail?action=list</code>
  
 
Parameters:
 
Parameters:
Line 2,178: Line 2,516:
 
! Name    !! Type  !! Value
 
! Name    !! Type  !! Value
 
|-
 
|-
| color_label || Number || The color number between 1 and 10.
+
| color_label || Number || The color number between 0 and 10.
 
|-
 
|-
 
| flags || Number || A set of flags to add or remove. Note: Flags for "recent" (8) and "user" (64) are ignored.
 
| flags || Number || A set of flags to add or remove. Note: Flags for "recent" (8) and "user" (64) are ignored.
Line 2,195: Line 2,533:
 
| clear_flags || Number || A set of flags to remove. Note: Flags for "recent" (8) and "user" (64) are ignored.
 
| clear_flags || Number || A set of flags to remove. Note: Flags for "recent" (8) and "user" (64) are ignored.
 
|}
 
|}
 +
 +
 +
=== Mark all mails as seen (available with v7.6.0) ===
 +
 +
PUT <code>/ajax/mail?action=all_seen</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>folder</code> – Object ID of the folder.
 +
 +
Request Body: n.a.
 +
 +
Response: <code>true</code>
  
 
=== Not IMAP: Get updated mails ===
 
=== Not IMAP: Get updated mails ===
Line 2,226: Line 2,577:
 
** '''NOTE:''' if set, the corresponding gui config setting will be ignored.
 
** '''NOTE:''' if set, the corresponding gui config setting will be ignored.
 
* <code>unseen</code> (optional) – "1" or "true" to leave an unseen mail as unseen although its content is requested
 
* <code>unseen</code> (optional) – "1" or "true" to leave an unseen mail as unseen although its content is requested
 +
* <code>max_size</code> (optional - available since v7.6.1) A positive integer number (greater than 10000) to specify how many characters of the message content will be returned. If the number is smaller than 10000 the value will be ignored and 10000 used.
 +
* <code>attach_src</code> (optional - available since v7.6.1) 1 to let the JSON mail representation being extended by <code>"source"</code> field containing the mail raw RFC822 source data
  
 
Response (not IMAP: with timestamp): An JSON object containing all data of the requested mail. The fields of the object are listed in [[#DetailedMailData | Detailed mail data]]. The fields id and attachment are not included. '''NOTE:''' Of course response is not a JSON object if either parameter <code>hdr</code> or parameter <code>src</code> are set to "1". Then the response contains plain text. Moreover if optional parameter <code>save</code> is set to "1" the complete message source is going to be directly written to output stream to open browser's save dialog.
 
Response (not IMAP: with timestamp): An JSON object containing all data of the requested mail. The fields of the object are listed in [[#DetailedMailData | Detailed mail data]]. The fields id and attachment are not included. '''NOTE:''' Of course response is not a JSON object if either parameter <code>hdr</code> or parameter <code>src</code> are set to "1". Then the response contains plain text. Moreover if optional parameter <code>save</code> is set to "1" the complete message source is going to be directly written to output stream to open browser's save dialog.
Line 2,273: Line 2,626:
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>lineWrapAfter</code> – An integer value specifying the line-wrap setting (only effective for plain-text content); if absent the setting is taken from user's mail settings. Available with v7.8.1.
  
 
Request Body: This method uses the encoding multipart/form-data or multipart/mixed.
 
Request Body: This method uses the encoding multipart/form-data or multipart/mixed.
Line 2,279: Line 2,633:
 
** 1 - A reply mail. The field "msgref" must be present
 
** 1 - A reply mail. The field "msgref" must be present
 
** 2 - A forward mail. The field "msgref" must be present
 
** 2 - A forward mail. The field "msgref" must be present
 +
** 3 - A draft edit operation. The field "msgref" must be present in order to delete previous draft message since e.g. IMAP does not support changing/replacing a message but requires a delete-and-insert sequence
 
** 4 - Transport of a draft mail. The field "msgref" must be present
 
** 4 - Transport of a draft mail. The field "msgref" must be present
 +
** 6 - This type signals that user intends to send out a saved draft message and expects the draft message (referenced by "msgref" field) being deleted after successful transport
 
Example of a normal new mail which appends user's VCard and requests a read receipt from receiver:
 
Example of a normal new mail which appends user's VCard and requests a read receipt from receiver:
  
Line 2,285: Line 2,641:
 
"subject":"Mail Subject","priority":"3","disp_notification_to":true,"vcard":1,
 
"subject":"Mail Subject","priority":"3","disp_notification_to":true,"vcard":1,
 
"attachments":[{"content_type":"ALTERNATIVE","content":"Simple Mail Text!&lt;br&gt;&lt;br&gt;\u000a\u000a"}]}</code>
 
"attachments":[{"content_type":"ALTERNATIVE","content":"Simple Mail Text!&lt;br&gt;&lt;br&gt;\u000a\u000a"}]}</code>
* The form field <code>attachment</code>''n'' (optional) – One or more file upload form fields whose referenced file are going to appended as attachments
+
* The request accepts file fields in upload form that denote referenced files that are going to be appended as attachments
 +
* For "text/plain" mail bodies, the JSON boolean field "raw" may be specified inside the body's JSON representation to signal that the text content shall be kept as-is; meaning to keep all formatting intact
  
 
==== Attach data sources ====
 
==== Attach data sources ====
Line 2,359: Line 2,716:
 
* <code>folder</code> - Object ID of the folder, whose contents are queried.
 
* <code>folder</code> - Object ID of the folder, whose contents are queried.
 
* <code>view</code> (optional - available with SP6) - "text" forces the server to deliver a text-only version of the requested mail's body, even if content is HTML. "html" to allow a possible HTML mail body being transferred as it is (but white-list filter applied).'''NOTE:''' if set, the corresponding gui config setting will be ignored.
 
* <code>view</code> (optional - available with SP6) - "text" forces the server to deliver a text-only version of the requested mail's body, even if content is HTML. "html" to allow a possible HTML mail body being transferred as it is (but white-list filter applied).'''NOTE:''' if set, the corresponding gui config setting will be ignored.
 +
* <code>setFrom</code> (optional - available since v7.6.0) A flag ("true"/"false") that signals if "From" header shall be pre-selected according to a suitable recipient address that matches one of user's E-Mail address aliases; only supported for <code>/ajax/mail?action=replyall</code> and <code>/ajax/mail?action=reply</code>
 +
* <code>max_size</code> (optional - available since v7.6.1) A positive integer number (greater than 10000) to specify how many characters of the message content will be returned. If the number is smaller than 10000 the value will be ignored and 10000 used.
  
 
Response (not IMAP: with timestamp): An object containing all data of the requested mail. The fields of the object are listed in [[#DetailedMailData | Detailed mail data]]. The fields id and attachment are not included.
 
Response (not IMAP: with timestamp): An object containing all data of the requested mail. The fields of the object are listed in [[#DetailedMailData | Detailed mail data]]. The fields id and attachment are not included.
Line 2,393: Line 2,752:
 
Response: An array with IDs of mail folder that could not be cleared; meaning the response body is an empty JSON array if everything went well.
 
Response: An array with IDs of mail folder that could not be cleared; meaning the response body is an empty JSON array if everything went well.
  
== Module "groups" ==
+
=== Acknowledge receipt ===
  
The group module allows to query available groups. It is mainly used by the dialog for the selection of participants.
+
PUT <code>/ajax/mail?action=receipt_ack</code>
  
=== Get a group ===
+
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 
 +
Request Body: A JSON object containing the "from address", the id of the folder and the mail id: e.g.: {"from":"mymail@domain.com","folder":"default0/INBOX","id":"1234"}
 +
 
 +
Response: A JSON object with an empty data field if everything went well or a JSON object containing the error information.
 +
 
 +
== Module "groups" ==
 +
 
 +
The group module allows to query available groups. It is mainly used by the dialog for the selection of participants.
 +
 
 +
=== Get a group ===
  
 
GET <code>/ajax/group?action=get</code>
 
GET <code>/ajax/group?action=get</code>
Line 2,633: Line 3,003:
 
Response with timestamp: An array with new, modified and deleted resources. New, modified and deleted resources are represented by JSON objects as described in [[#ResourceResponse | Resource response]].
 
Response with timestamp: An array with new, modified and deleted resources. New, modified and deleted resources are represented by JSON objects as described in [[#ResourceResponse | Resource response]].
  
== Module "infostore" ==
+
== Module "infostore" or "Filestore" or "Files" or "Drive" ==
 
+
This module has been renamed quite often. Whatever its name, it combines the knowledge database, bookmarks and document storage.
The infostore module combines the knowledge database, bookmarks and documents.
 
  
 
=== Get all infoitems ===
 
=== Get all infoitems ===
Line 2,653: Line 3,022:
 
|+ align="bottom" | Detailed infoitem data
 
|+ align="bottom" | Detailed infoitem data
 
! ID  !! Name            !! Type    !! Value
 
! ID  !! Name            !! Type    !! Value
 +
|-
 +
| 108 || object_permissions          || Array  || Each element is an object described in [[#ObjectPermissionObject | 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
 
| 700 || title          || String  || Title
Line 2,674: Line 3,047:
 
| 709 || version_comment || String  || A version comment is used to file a changelog for the file.
 
| 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
+
| 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.
 
| 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 [[#ExtendedObjectPermissionObject | 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.
 
|}
 
|}
  
=== Get a list of infoitems ===
+
{| id="ObjectPermissionObject" cellspacing="0" border="1"
 +
|+ align="bottom" | Object Permission object
 +
! Name  !! Type    !! Value
 +
|-
 +
| bits  || Number  || A number as described in [[#ObjectPermissionFlags | 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).
 +
|}
  
PUT <code>/ajax/infostore?action=list</code>
+
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"
 +
|+ align="bottom" | 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 [[#ObjectPermissionFlags | 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 [[#DetailedContactData | 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.
 +
|}
  
Parameters:
+
{| id="ObjectPermissionFlags" cellspacing="0" border="1"
* <code>session</code> – A session ID previously obtained from the login module.
+
|+ align="bottom" | Object Permission flags
 +
! Bits  !! Value
 +
|-
 +
| 0 || The numerical value indicating no object permissions.
 +
|-
 +
| 1 || The numerical value indicating read object permissions.
 +
|-
 +
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).
 +
|}
 +
 
 +
=== Get a list of infoitems ===
 +
 
 +
PUT <code>/ajax/infostore?action=list</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for infoitems are defined in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].
 
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for infoitems are defined in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].
  
Line 2,723: Line 3,157:
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>folder</code> (optional) – The folder ID to restrict the search to. If not specified, all folders are searched.
 
* <code>columns</code> – The requested fields as per tables [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].
 
* <code>columns</code> – The requested fields as per tables [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].
 
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
 
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
Line 2,729: Line 3,164:
 
* <code>end</code> (optional) – The last index (inclusive) from the ordered search, that is requested.
 
* <code>end</code> (optional) – The last index (inclusive) from the ordered search, that is requested.
  
Request body: An Object as described in [[#SearchContacts | Search contacts]].
+
Request body: The search pattern string in a JSON object named "pattern".
  
 
=== Get an infoitem document ===
 
=== Get an infoitem document ===
Line 2,745: Line 3,180:
  
 
Note: The Filename may be added to the customary infostore path to suggest a filename to a Save-As dialog.
 
Note: The Filename may be added to the customary infostore path to suggest a filename to a Save-As dialog.
 +
 +
=== Get a ZIP archive containing the infoitems of a denoted folder (available with v7.6.1) ===
 +
 +
GET <code>/ajax/infostore/[filename]?action=zipfolder</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>folder</code> – Object ID of the infoitem's folder.
 +
* <code>recursive</code> – <code>true</code> to also include subfolders and their infoitems respectively; otherwise <code>false</code> to only consider the infoitems of specified folder
 +
 +
Response body: The raw byte data of the ZIP archive. The response type for the HTTP Request is set to <code>application/zip</code>.
  
 
=== Get all versions ===
 
=== Get all versions ===
Line 2,759: Line 3,205:
 
Response with timestamp: An array with infoitem data. Each array element describes one infoitem and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. The timestamp is the timestamp relating to the requested infostore item.
 
Response with timestamp: An array with infoitem data. Each array element describes one infoitem and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. The timestamp is the timestamp relating to the requested infostore item.
  
=== Update an infoitem via PUT ===
+
=== Check if file name is valid (since 7.8.1, Preliminary) ===
  
PUT <code>/ajax/infostore?action=update</code>
+
GET <code>/ajax/infostore?action=checkname</code>
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>id</code> – Object ID of the updated infoitem.
+
* <code>name</code> – Name of the file to check.
* <code>timestamp</code> – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.
 
  
Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present.
+
Response: An empty JSON object when file name is valid.
  
=== Update an infoitem via POST ===
+
=== Get multiple documents as a ZIP archive (available with v7.4.0) ===
  
POST <code>/ajax/infostore?action=update</code>
+
GET <code>/ajax/infostore?action=zipdocuments</code>
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>id</code> – Object ID of the updated infoitem.
+
* <code>body</code> – A URL-encoded JSON array; see below for details
* <code>timestamp</code> – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.
 
* <code>json</code> - Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present.
 
* <code>file</code> – File Metadata as per <input type=”file” />
 
  
Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.
+
Parameter <code>body</code>: A JSON array of JSON object tuples specifying the documents' versions to include in the requested ZIP archive; e.g<br>
 +
<pre>
 +
[{"id":"61820","folder":"70303"},{"id":"61821","folder":"70303", "version": "1"}]
 +
</pre>
 +
The field <code>"version"</code> is optional; if missing it refers to latest/current version.<br>
 +
So, a valid parameter would look like:
 +
<pre>
 +
...&body=%5B%7B%22id%22%3A%2261820%22%2C%22folder%22%3A%2270303%22%7D%2C%7B%22id%22%3A%2261821%22%2C%22folder%22%3A%2270303%22%2C%22version%22%3A%221%22%7D%5D
 +
</pre>
  
Response: The response is sent as a HTML document (see introduction).
+
Response: The download offer for the requested ZIP archive containing specified document versions
  
=== Create an infoitem via PUT ===
+
=== Move one or more infoitems via PUT ===
  
PUT <code>/ajax/infostore?action=new</code>
+
PUT <code>/ajax/infostore?action=move</code>
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>folder</code> – ID of the destination folder.
  
Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included.
+
Request body: A JSON array consisting of JSON objects each referencing to an existing infoitem that is supposed to be moved to the destination folder
  
Response: Object ID of the newly created infoitem.
+
<pre>
 +
[
 +
  {"id":"31841/36639", "folder":"31841"},
 +
  {"id":"31841/36641", "folder":"31841"}
 +
]
 +
</pre>
 +
 
 +
Response: A JSON array consisting of those identifiers that could not be moved (due to a conflict) or an empty JSON array if everything went fine
  
=== Create an infoitem via POST ===
+
=== Update an infoitem via PUT ===
  
POST <code>/ajax/infostore?action=new</code>
+
PUT <code>/ajax/infostore?action=update</code>
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>json</code> - Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included.
+
* <code>id</code> – Object ID of the updated infoitem.
* <code>file</code> – File metadata as per <input type=”file” />
+
* <code>timestamp</code> – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.
 +
 
 +
Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:
 +
 
 +
<pre>
 +
{
 +
  "file":{
 +
    "object_permissions":[
 +
      {
 +
        "bits":403710016,
 +
        "entity":84,
 +
        "group":false
 +
      },
 +
      {
 +
        "type":"guest",
 +
        "email_address":"john.doe@example.com",
 +
        "display_name":"John Doe",
 +
        "bits":1
 +
      }
 +
    ]
 +
  },
 +
  "notification":{
 +
    "transport":"mail",
 +
    "message":"Hi!\nHave a look at this!"
 +
  }
 +
}
 +
</pre>
 +
 
 +
=== Update an infoitem via POST ===
 +
 
 +
POST <code>/ajax/infostore?action=update</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>id</code> – Object ID of the updated infoitem.
 +
* <code>timestamp</code> – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.
 +
* <code>offset</code> – Optionally sets the start offset in bytes where to append the data to the document, must be equal to the actual document's length (available with v7.8.1). Only available if the underlying [[#FileStorageAccount | File storage account]] supports the "RANDOM_FILE_ACCESS" capability.
 +
* <code>json</code> - Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.
 +
* <code>file</code> – File Metadata as per <input type=”file” />
  
 
Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.
 
Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.
  
Response: Object ID of the newly created infoitem. The response is sent as a HTML document (see introduction).
+
Response: The response is sent as a HTML document (see introduction).
  
=== Save an attachment in the infostore ===
+
=== Create an infoitem via PUT ===
  
PUT <code>/ajax/infostore?action=saveAs</code>
+
PUT <code>/ajax/infostore?action=new</code>
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>attached</code> – The Object ID of the Object with the attachment
 
* <code>folder</code> – The Folder ID of the Object with the attachment
 
* <code>module</code> – The Module type of the Object with the attachment.
 
* <code>Attachment</code> – The id of the attachement to save.
 
  
Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included. The fields in this infoitem object override values from the attachment. The folder_id must be given.
+
Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:
 +
 
 +
<pre>
 +
{
 +
  "file":{
 +
    "object_permissions":[
 +
      {
 +
        "bits":403710016,
 +
        "entity":84,
 +
        "group":false
 +
      },
 +
      {
 +
        "type":"guest",
 +
        "email_address":"john.doe@example.com",
 +
        "display_name":"John Doe",
 +
        "bits":1
 +
      }
 +
    ]
 +
  },
 +
  "notification":{
 +
    "transport":"mail",
 +
    "message":"Hi!\nHave a look at this!"
 +
  }
 +
}
 +
</pre>
  
 
Response: Object ID of the newly created infoitem.
 
Response: Object ID of the newly created infoitem.
  
=== Delete infoitems ===
+
=== Create an infoitem via POST ===
  
PUT <code>/ajax/infostore?action=delete</code>
+
POST <code>/ajax/infostore?action=new</code>
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>timestamp</code> – Timestamp of the last update of the deleted infoitems.
+
* <code>json</code> - Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.
 +
* <code>file</code> – File metadata as per <input type=”file” />
  
Request body: An array with objects to delete. The fields for the object are described in [[#FullIdentifierForAnInfostoreDocument|Full identifier for an infostore document]].
+
Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.
 +
 
 +
Response: Object ID of the newly created infoitem. The response is sent as a HTML document (see introduction).
 +
 
 +
=== Save an attachment in the infostore ===
 +
 
 +
PUT <code>/ajax/infostore?action=saveAs</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>attached</code> – The Object ID of the Object with the attachment
 +
* <code>folder</code> – The Folder ID of the Object with the attachment
 +
* <code>module</code> – The Module type of the Object with the attachment.
 +
* <code>Attachment</code> – The id of the attachement to save.
 +
 
 +
Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included. The fields in this infoitem object override values from the attachment. The folder_id must be given. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:
 +
 
 +
<pre>
 +
{
 +
  "file":{
 +
    "object_permissions":[
 +
      {
 +
        "bits":403710016,
 +
        "entity":84,
 +
        "group":false
 +
      },
 +
      {
 +
        "type":"guest",
 +
        "email_address":"john.doe@example.com",
 +
        "display_name":"John Doe",
 +
        "bits":1
 +
      }
 +
    ]
 +
  },
 +
  "notification":{
 +
    "transport":"mail",
 +
    "message":"Hi!\nHave a look at this!"
 +
  }
 +
}
 +
</pre>
 +
 
 +
Response: Object ID of the newly created infoitem.
 +
 
 +
=== Delete infoitems ===
 +
 
 +
PUT <code>/ajax/infostore?action=delete</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>timestamp</code> – Timestamp of the last update of the deleted infoitems.
 +
* <code>hardDelete</code> - Optional, defaults to \"false\". If set to \"true\", the file is deleted permanently. Otherwise, and if the underlying storage supports a trash folder and the file is not yet located below the trash folder, it is moved to the trash folder.
 +
 
 +
Request body: An array with objects to delete. The fields for the object are described in [[#FullIdentifierForAnInfostoreDocument|Full identifier for an infostore document]].
  
 
Response: An array with [[]].  
 
Response: An array with [[]].  
Line 2,927: Line 3,496:
 
Response with timestamp: Can only contain errors.
 
Response with timestamp: Can only contain errors.
  
== Module "Links" (deprecated) ==
+
=== Get shared infoitems (Since 7.8.0, Preliminary) ===
 
 
The link module provides the ability to connect two objects from any module. 
 
 
 
=== Get All Links from an Object ===
 
  
GET <code>/ajax/link?action=all</code>
+
GET <code>/ajax/infostore?action=shares</code>
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>id</code> – The Object ID of the Object
+
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for infoitems are defined in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].
* <code>folder</code> – The Folder ID of the Object
+
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
* <code>module</code> – The Module type of the Object
+
* <code>order</code> (optional) "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  
Response: An Array with all Links ([[#LinkObject | Link object]]) from the given Object ID.
+
Response: An array with infoitem data. Each array element describes one infoitem and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
  
=== Create a Link ===
+
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===
  
PUT <code>/ajax/link?action=new</code>
+
PUT <code>/ajax/infostore?action=notify</code>
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>id</code> – Object ID of the shared infoitem to notify about.
  
Request body: Link object as described in [[#LinkObject | Link object]].
+
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).
  
Response: An OK.
+
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.
  
{| id="LinkObject" cellspacing="0" border="1"
+
== Module "Attachments" ==
|+ align="bottom" | Link Object
+
 
! Field              !! Name    !! Type  !! Description
+
The Attachment Module allows file attachments to arbitrary objects. An Attachment always belongs to an object (called 'attached') in a certain folder of a certain module. 
|-
+
 
| First Object ID    || id1    || Number || The ID of the first Object you want to start to link
+
=== Get All Attachments for an Object ===
|-
 
| First Module Type  || module1 || Number || The Module of this Object Possible Values:
 
{| cellspacing="0" border="1"
 
| 1  || Appointment
 
|-
 
| 4  || Task
 
|-
 
| 7  || Contact
 
|-
 
| 13  || Project
 
|-
 
| 17  || Forum
 
|-
 
| 18  || Pin board
 
|-
 
| 19  || Email
 
|-
 
| 137 || Infostore
 
|}
 
|-
 
| First Folder ID    || folder1 || String || The Folder of this Object
 
|-
 
| Second Object ID  || id2    || Number || The ID of the second Object you want to link the first Object with
 
|-
 
| Second Module Type || module2 || Number || The Module of the second Object
 
Possible Values:
 
{| cellspacing="0" border="1"
 
| 1  || Appointment
 
|-
 
| 4  || Task
 
|-
 
| 7  || Contact
 
|-
 
| 13  || Project
 
|-
 
| 17  || Forum
 
|-
 
| 18  || Pin board
 
|-
 
| 19  || Email
 
|-
 
| 137 || Infostore
 
|}
 
|-
 
| Second Folder ID  || folder2 || String || The Folder of the second Object
 
|}
 
  
=== Delete Link ===
+
GET <code>/ajax/attachment?action=all</code>
 
 
PUT <code>/ajax/link?action=delete</code>
 
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>id</code> – The ID of the base Object
+
* <code>attached</code> – The Object ID of the Object
* <code>module</code> – The type of the Object
+
* <code>folder</code> – The Folder ID of the Object
* <code>folder</code> – The Folder of the Object
+
* <code>module</code> – The Module type of the Object
 +
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for attachment's are defined in [[#CommonObjectData | Common object data]] (with only id, created_by and creation_date available) and [[#AttachmentObject | Attachment object]].
 +
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
 +
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  
Request body: A List of arrays with the information of the Links to delete which looks like [[#DeleteObject | Delete object]].
+
Response: An array with attachment data. Each array element describes one attachment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
 
 
Response: A List of arrays with object Ids of links which are not readable by the user and were therefore not deleted. See [[#DeleteObject | Delete object]].
 
 
 
{| id="DeleteObject" cellspacing="0" border="1"
 
|+ align="bottom" | Delete Object
 
! Field    !! Type  !! Array Position
 
|-
 
| Object id || Number || 0
 
|-
 
| Module    || Number || 1
 
|-
 
| Folder    || String || 2
 
|}
 
 
 
== Module "Attachments" ==
 
 
 
The Attachment Module allows file attachments to arbitrary objects. Object addresses are defined analogous to the Link module. An Attachment always belongs to an object (called 'attached') in a certain folder of a certain module. 
 
 
 
=== Get All Attachments for an Object ===
 
 
 
GET <code>/ajax/attachment?action=all</code>
 
 
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>attached</code> – The Object ID of the Object
 
* <code>folder</code> – The Folder ID of the Object
 
* <code>module</code> – The Module type of the Object
 
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for attachment's are defined in [[#CommonObjectData | Common object data]] (with only id, created_by and creation_date available) and [[#AttachmentObject | Attachment object]].
 
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
 
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
 
 
 
Response: An array with attachment data. Each array element describes one attachment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
 
  
 
=== Get a list of attachments ===
 
=== Get a list of attachments ===
Line 3,262: Line 3,751:
 
The filestore module allows accesssing information about the use and quota of the filestore.
 
The filestore module allows accesssing information about the use and quota of the filestore.
  
=== Get the filestore usage data ===
+
=== Get quota information (Since 7.6.1, Preliminary) ===
  
GET <code>/ajax/quota?action=filestore</code>
+
GET <code>/ajax/quota?action=get</code>
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>module</code> (optional) – The module identifier to get quota information for, required if <code>account</code> is set.
 +
* <code>account</code> (optional) – The account identifier within the module to get quota information for.
  
Response: A JSON Object containing the fields “use” and “quota”. “use” represents the uploaded files sizes sum and the field “quota” represents the maximum.
+
Response: A JSON object containing the requested quota information. If no <code>module</code> was specified, all defined [[#ModuleQuota | module quotas]] are set in the JSON object, each one mapped to it's module identifier. If the quota from a <code>module</code> was requested, a JSON array containing all [[#AccountQuota | account quotas]] of this module are returned. If both a <code>module</code> and <code>account</code> were requested, a JSON object representing this specific [[#AccountQuota | account auota]] is returned.  
  
=== Get the mail usage data ===
+
Note: In case there is no quota limitation defined for a module or account, no corresponding JSON object is included in the response.
  
GET <code>/ajax/quota?action=mail</code>
 
  
Parameters:
+
{| id="ModuleQuota" cellspacing="0" border="1"
* <code>session</code> – A session ID previously obtained from the login module.
+
|+ align="bottom" | Module Quota
 +
! Field    !! Type  !! Description
 +
|-
 +
| display_name || String || The display name of the module
 +
|-
 +
| accounts|| Array || Each element identifies an account quota within the module, as described in [[#AccountQuota | Account Quota]]
 +
|-
 +
|}
  
Response: A JSON Object containing the fields “use” and “quota”. “use” represents the use mail quota and the field “quota” represents the maximum. -1 represents an unlimited quota.
+
 
 
+
{| id="AccountQuota" cellspacing="0" border="1"
 
+
|+ align="bottom" | Account Quota
== Module "import"==
+
! Field    !! Type  !! Description
The module import allows to import specific module data (like Contacts, Tasks or Appointments) in several formats (iCal, vCard, CSV) into a folder.
+
|-
 +
| account_id || String || Identifier of the account
 +
|-
 +
| account_name || String || Name of the account
 +
|-
 +
| countquota || Number || The account's quota limit for the number of items, or not set if not defined
 +
|-
 +
| countuse || Number || The account's actual usage for the number of items, or not set if no count quota defined
 +
|-
 +
| quota || Number || The account's quota limit for the storage in bytes, or not set if not defined
 +
|-
 +
| use || Number || The account's actual usage for the storage in bytes, or not set if no storage quota defined
 +
|-
 +
|}
 +
 
 +
 
 +
=== Get the filestore usage data ===
 +
 
 +
GET <code>/ajax/quota?action=filestore</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 
 +
Response: A JSON Object containing the fields “use” and “quota”. “use” represents the uploaded files sizes sum and the field “quota” represents the maximum.
 +
 
 +
=== Get the mail usage data ===
 +
 
 +
GET <code>/ajax/quota?action=mail</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 
 +
Response: A JSON Object containing the fields “use” and “quota”. “use” represents the use mail quota and the field “quota” represents the maximum. -1 represents an unlimited quota.
 +
 
 +
== Module "import"==
 +
The module import allows to import specific module data (like Contacts, Tasks or Appointments) in several formats (iCal, vCard, CSV) into a folder. Please note: The callback for all actions of this bundle is callback_import, not callback_$actionname for legacy purposes.
  
 
=== Import CSV ===
 
=== Import CSV ===
Line 3,290: Line 3,822:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>folder</code> – ObjectID of the folder into which data should be imported. This must be a Contact folder.
 
* <code>folder</code> – ObjectID of the folder into which data should be imported. This must be a Contact folder.
 +
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.
  
 
Request body: A "multipart/form-data" encoded .CSV file. The field name for the file is "file". The column titles of the table are those used within the OX, see column ''Displayed Name'' in [[#DetailedContactData]].
 
Request body: A "multipart/form-data" encoded .CSV file. The field name for the file is "file". The column titles of the table are those used within the OX, see column ''Displayed Name'' in [[#DetailedContactData]].
Line 3,301: Line 3,834:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>folder</code> – ObjectID of the folder into which data should be imported. This must be a Contact folder.
 
* <code>folder</code> – ObjectID of the folder into which data should be imported. This must be a Contact folder.
 +
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.
  
 
Request body: An .CSV file with Windows' default encoding Windows-1252. The column titles of the table may be those used by the English, French or German version of Outlook.
 
Request body: An .CSV file with Windows' default encoding Windows-1252. The column titles of the table may be those used by the English, French or German version of Outlook.
Line 3,313: Line 3,847:
 
* <code>folder</code> – ObjectID of the folder into which data should be imported. This may be an Appointment or a Task folder. May even be a list containing both.
 
* <code>folder</code> – ObjectID of the folder into which data should be imported. This may be an Appointment or a Task folder. May even be a list containing both.
 
* <code>suppressNotification</code> – This optional parameter can be used to disable the notifications for new appointments that are imported through the given iCal file. This help keeping the Inbox clean if a lot of appointments need to be imported. The value of this parameter does not matter because only for the existence of the parameter is checked.
 
* <code>suppressNotification</code> – This optional parameter can be used to disable the notifications for new appointments that are imported through the given iCal file. This help keeping the Inbox clean if a lot of appointments need to be imported. The value of this parameter does not matter because only for the existence of the parameter is checked.
 +
* <code>ignoreUIDs</code> – Optional. When set to "true", UIDs are partially ignored during import of tasks and appointments from iCal. Internally, each UID is replaced statically by a random one to preserve possibly existing relations between recurring appointments in the same iCal file, but at the same time to avoid collisions with already existing tasks and appointments.
  
 
Request body: An iCalendar file.
 
Request body: An iCalendar file.
Line 3,339: Line 3,874:
 
* <code>folder</code> – ObjectID of the folder whose contents are to be exported. This must be a Contact folder.
 
* <code>folder</code> – ObjectID of the folder whose contents are to be exported. This must be a Contact folder.
 
* <code>columns</code> – (optional) Columns to be imported from the given file, given as an array of column numbers. See [[#DetailedContactData | Detailed contact data]] for numbers.
 
* <code>columns</code> – (optional) Columns to be imported from the given file, given as an array of column numbers. See [[#DetailedContactData | Detailed contact data]] for numbers.
 
+
* <code>export_dlists</code> – (optional) toggles whether distribution lists are exported, too. Default is false. Option exists since 7.4.1.
 
Response: An InputStream containing the file of the MIME type <code>text/csv</code>.
 
Response: An InputStream containing the file of the MIME type <code>text/csv</code>.
  
Line 3,373: Line 3,908:
  
 
Response: A JSON array containing the IDs of folders that could not be cleared due to a concurrent modification. Meaning you receive an empty JSON array if everything worked well.
 
Response: A JSON array containing the IDs of folders that could not be cleared due to a concurrent modification. Meaning you receive an empty JSON array if everything worked well.
 +
 +
== Module "token" (since 7.4.0) ==
 +
The module token delivers several core API extensions to support token based logins.
 +
 +
=== Get a login token ===
 +
GET <code>/ajax/token?action=acquireToken</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 +
Response:
 +
A JSON object with the timestamp of the creation date and a token which can be used to create a new session.
  
 
== Module "mailfilter" ==
 
== Module "mailfilter" ==
The module mailfilter descriptes how to add, update or delete mail filter rules or to check which actions are supported by the underlying system.
+
The module mailfilter describes how to add, update or delete mail filter rules or to check which actions are supported by the underlying system.
  
 
A detailed description can be found here [[ HTTP_API_MailFilter | Mail Filter HTTP API]]
 
A detailed description can be found here [[ HTTP_API_MailFilter | Mail Filter HTTP API]]
Line 3,418: Line 3,965:
  
 
=== Requesting an image ===
 
=== Requesting an image ===
GET <code>/ajax/image</code>  
+
Open-Xchange Server supports multiple image sources that are identified through request's path identifier
 +
 
 +
* Inline images from mails
 +
** Request path needs to be <code>"/mail/picture"</code><br><br>
 +
* Contact profile image
 +
** Request path needs to be <code>"/contact/picture"</code><br><br>
 +
* User profile image
 +
** Request path needs to be <code>"/user/picture"</code><br><br>
 +
* MP3 cover image
 +
** Request path needs to be <code>"/file/mp3cover"</code><br><br>
 +
* Fetch a previously uploaded image using <code>"/ajax/file"</code> interface
 +
** Request path needs to be <code>"/mfile/picture"</code><br><br>
 +
 
 +
Each image source requires an individual set of required parameters
 +
 
 +
==== Inline images from mails ====
 +
GET <code>/mail/picture</code>  
  
 
Parameters:
 
Parameters:
* <code>uid</code> – The unique ID referring to the desired image
+
* <code>accountId</code> – The mail account identifier
 +
* <code>folder</code> – The identifier of the folder in which the mail resides
 +
* <code>id</code> – The mail identifier
 +
* <code>uid</code> – The identifier of the image inside the referenced mail
  
 
Response: The content of the requested image is directly written into output stream
 
Response: The content of the requested image is directly written into output stream
  
== Module "conversion" (preliminary) ==
 
  
A generic module to request data from a data source and to process obtained/submitted data with a data handler. Thus data is converted from a data source by a data handler.
+
==== Contact profile images ====
 +
GET <code>/contact/picture</code>
  
=== Converting data ===
+
Parameters:
PUT <code>/ajax/conversion?action=convert</code><br>
+
* <code>folder</code> – The identifier of the folder in which the contact resides
or<br>
+
* <code>id</code> – The contact identifier
POST <code>/ajax/conversion?action=convert</code>  
+
 
 +
Response: The content of the requested image is directly written into output stream
 +
 
 +
 
 +
==== User profile images ====
 +
GET <code>/user/picture</code>
 +
 
 +
Parameters:
 +
* <code>id</code> – The user identifier
 +
 
 +
Response: The content of the requested image is directly written into output stream
 +
 
 +
 
 +
==== MP3 cover image ====
 +
GET <code>/file/mp3cover</code>
 +
 
 +
Parameters:
 +
* <code>id</code> – The identifier of the uploaded image
 +
 
 +
Response: The content of the requested image is directly written into output stream
 +
 
 +
 
 +
==== Managed Image File ====
 +
GET <code>/image/mfile/picture</code>
 +
 
 +
Parameters:
 +
* <code>uid</code> – The identifier of the uploaded image
 +
 
 +
Response: The content of the requested image is directly written into output stream
 +
 
 +
== Module "conversion" (preliminary) ==
 +
 
 +
A generic module to request data from a data source and to process obtained/submitted data with a data handler. Thus data is converted from a data source by a data handler.
 +
 
 +
=== Converting data ===
 +
PUT <code>/ajax/conversion?action=convert</code><br>
 +
or<br>
 +
POST <code>/ajax/conversion?action=convert</code>  
  
 
Parameters: &lt;no parameters required&gt;
 
Parameters: &lt;no parameters required&gt;
Line 3,553: Line 4,156:
 
<code>
 
<code>
 
{<br>
 
{<br>
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.mail.vcard&quot;<br>
+
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.mail.vcard&quot;,<br>
 
&nbsp;&quot;args&quot;:<br>
 
&nbsp;&quot;args&quot;:<br>
 
&nbsp;&nbsp;[<br>
 
&nbsp;&nbsp;[<br>
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.fullname&quot;:&quot;&lt;folder-fullname&gt;&quot;}<br>
+
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.fullname&quot;:&quot;&lt;folder-fullname&gt;&quot;},<br>
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.mailid&quot;:&quot;&lt;mail-id&gt;&quot;}<br>
+
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.mailid&quot;:&quot;&lt;mail-id&gt;&quot;},<br>
 
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.sequenceid&quot;:&quot;&lt;attachment-sequence-id&gt;&quot;}<br>
 
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.sequenceid&quot;:&quot;&lt;attachment-sequence-id&gt;&quot;}<br>
 
&nbsp;&nbsp;]<br>
 
&nbsp;&nbsp;]<br>
Line 3,566: Line 4,169:
 
<code>
 
<code>
 
{<br>
 
{<br>
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.contact&quot;<br>
+
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.contact&quot;,<br>
 
&nbsp;&quot;args&quot;:<br>
 
&nbsp;&quot;args&quot;:<br>
 
&nbsp;&nbsp;[<br>
 
&nbsp;&nbsp;[<br>
Line 3,753: Line 4,356:
 
|  1022  ||  transport_secure || Boolean    || Whether to establish a secure connection to transport server (SSL, TLS).
 
|  1022  ||  transport_secure || Boolean    || Whether to establish a secure connection to transport server (SSL, TLS).
 
|-
 
|-
|  1023  ||  transport_login || String    || The transport login. If empty "login" is taken as transport login as well.
+
|  1023  ||  transport_login || String    || The transport login. '''Please see "transport_auth" for the handling of this field.'''
 
|-
 
|-
|  1024  ||  transport_password || String    || The transport password. If empty "password" is taken as transport password as well.
+
|  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
 
|  1025  ||  unified_inbox_enabled || Boolean    || If enabled for Unified INBOX
Line 3,784: Line 4,387:
 
|-
 
|-
 
|  1038  ||  reply_to || String    || The customizable reply-to 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. Possible values: "mail", "custom", and "none".<br>- "mail" signals to use the same credentials as given in associated mail store (IMAP, POP3).<br>- "custom" signals that individual credentials are supposed to be used (fields "transport_login" and "transport_password" are considered).<br>- "none" means the mail transport does not support any authentication mechanism (rare case!)
 +
|
 +
|-
 +
|  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.
 
|}
 
|}
  
Line 3,834: Line 4,452:
 
[[Category: OX6]]
 
[[Category: OX6]]
  
== Module "user" (available with v6.14) ==
+
== Module Auto Configuration (since 6.22) ==
  
The user module is used to access user information.
+
=== Get Auto Configuration ===
 +
 
 +
POST <code>/ajax/autoconfig?action=get</code>
 +
 
 +
application/x-www-form-urlencoded parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>email</code> – Email Adress for which a mail configuration will be discovered.
 +
* <code>password</code> – Corresponding password for the mail account (optional)
 +
* <code>force_secure</code> – '''Available since v7.8.2''' Enforce a secure connection for configured mail account, default is true (optional)
 +
 
 +
Response: A JSON Object containing the best available settings for an appropriate mail Server for the given email address. The fields are described in [[#MailAccountData | mail account data]]. The Data may be incomplete or even empty.
 +
 
 +
== Module "user" (available with v6.14) ==
 +
 
 +
The user module is used to access user information.
  
 
=== Get all users ===
 
=== Get all users ===
Line 3,865: Line 4,497:
 
|-
 
|-
 
| 615 || Login info                  || login_info          || String    || The user's login information
 
| 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)
 
|}
 
|}
  
Line 3,974: Line 4,608:
 
Response: The boolean value "true" if PUT was successful; otherwise "false"
 
Response: The boolean value "true" if PUT was successful; otherwise "false"
  
== Module "OAuth" (available with v6.20) ==
+
== Module "user/me" (available with v7.6.2) ==
 +
 
 +
The user/me module is used to access formal information about current user.
 +
 
 +
=== Get user information ===
 +
 
 +
GET <code>/ajax/user/me</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 
 +
Response with timestamp: A JSON object providing information for current user
 +
 
 +
<code>
 +
  {
 +
    "data": {
 +
        "context_id": 1234,
 +
        "user_id": 5,
 +
        "is_context_admin": false,
 +
        "login_name": "user5",
 +
        "display_name": "User Five"
 +
    },
 +
    "timestamp": 1400855683800
 +
  }
 +
</code>
 +
 
 +
== Module "OAuth" ==
  
The OAuth module is used to manage multiple OAuth accounts for certian online services for a user. The OAuth mechanism allows the Open-Xchange application to act as behalf of this user using previously obtained access tokens granted by user.
+
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:
  
The OAuth interface is divided into two parts: Account access and service's meta data access.
+
* Manage multiple OAuth accounts for certain online services for a user. The OAuth mechanism allows the Open-Xchange application to act as behalf of this user using previously obtained access tokens granted by user. The according interface is divided into two parts: Account access and service's meta data access.
 +
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".
  
=== OAuth account access ===
+
=== OAuth account access (available with v6.20) ===
  
 
The OAuth service account access description.
 
The OAuth service account access description.
Line 4,082: Line 4,743:
 
Response: A JSON object describing the newly created OAuth account as specified in [[#OAuthAccountData | OAuth account data]].
 
Response: A JSON object describing the newly created OAuth account as specified in [[#OAuthAccountData | OAuth account data]].
  
=== OAuth service meta data access ===
+
=== OAuth service meta data access (available with v6.20) ===
  
 
The OAuth service meta data access description.
 
The OAuth service meta data access description.
Line 4,116: Line 4,777:
 
|}
 
|}
  
== Module "JSlob" (available with v6.22) ==
+
=== Manage OAuth grants (available with v7.8.0) ===
 
 
The JSlob module is used to store&retrieve arbitrary JSON-structured configuration for a single user.
 
 
 
  
=== Get all JSLobs ===
+
==== Get all grants ====
  
GET <code>/ajax/jslob?action=all</code>
+
GET <code>/ajax/oauth/grants?action=all</code>
  
 
Parameters:
 
Parameters:
 
* <code>session</code> – A session ID previously obtained from the login module.
 
* <code>session</code> – A session ID previously obtained from the login module.
* <code>serviceId</code> – Optional identifier for the JSlob service. Default is <code>com.openexchange.jslob.config</code>
 
  
 +
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].
  
Response: An array with JSON configurations. Each array element is a JSON object representing a certain configuration consisting if a "id" and "jslob" field. See [[#JSlobData | JSlob data ]]
+
{| id="OAuthGrants" cellspacing="0" border="1"
 +
|+ align="bottom" | OAuth grants
 +
! Field    !! Type  !! Description
 +
|-
 +
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].
 +
|-
 +
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}
 +
|-
 +
| date || Time || The time when the access was granted.
 +
|-
 +
|}
  
{| id="JSlobData" cellspacing="0" border="1"
+
{| id="OAuthClient" cellspacing="0" border="1"
|+ align="bottom" | JSlob data
+
|+ align="bottom" | OAuth client
 
! Field    !! Type  !! Description
 
! Field    !! Type  !! Description
 
|-
 
|-
| id || String or Number || The identifier of the JSlob.
+
| id || String || The clients ID.
 +
|-
 +
| name || String || The clients/services name.
 +
|-
 +
| description || String || A description of the client.
 +
|-
 +
| website || String || A URL to the clients website.
 
|-
 
|-
| jslob || JSON object || The JSON configuration.
+
| icon || String || A URL or path to obtain the clients icon via the "image" module.
 
|-
 
|-
 
|}
 
|}
  
=== List denoted JSLobs ===
+
==== Revoke access ====
 +
 
 +
GET <code>oauth/grants?action=revoke</code>
 +
 
 +
Parameters:
 +
* <code>client</code> - The ID of the client whose access shall be revoked.
 +
 
 +
Response: Nothing.
 +
 
 +
== Module "JSlob" (available with v6.22) ==
 +
 
 +
The JSlob module is used to store&retrieve arbitrary JSON-structured configuration for a single user.
 +
 
 +
 
 +
=== Get all JSLobs ===
 +
 
 +
GET <code>/ajax/jslob?action=all</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>serviceId</code> – Optional identifier for the JSlob service. Default is <code>com.openexchange.jslob.config</code>
 +
 
 +
 
 +
Response: An array with JSON configurations. Each array element is a JSON object representing a certain configuration consisting if a "id" and "jslob" field. See [[#JSlobData | JSlob data ]]
 +
 
 +
{| id="JSlobData" cellspacing="0" border="1"
 +
|+ align="bottom" | JSlob data
 +
! Field    !! Type  !! Description
 +
|-
 +
| id || String or Number || The identifier of the JSlob.
 +
|-
 +
| jslob || JSON object || The JSON configuration.
 +
|-
 +
|}
 +
 
 +
=== List denoted JSLobs ===
  
 
PUT <code>/ajax/jslob?action=list</code>
 
PUT <code>/ajax/jslob?action=list</code>
Line 4,202: Line 4,911:
 
to be done...
 
to be done...
  
== Messaging Services ==
 
  
Messaging Services represent a messaging backend. The messaging services add a new folder module "messaging".  
+
== Module "freebusy" (available with v6.22.1) ==
 +
 
 +
Provides access to free/busy information.
 +
 
 +
 
 +
=== Get free/busy information ===
  
A *Messaging Service* Object has the following structure:
+
GET <code>/ajax/freebusy?action=get</code>
  
{| id="MessagingService" cellspacing="0" border="1"
+
Parameters:
|+ align="bottom" | Messaging Service
+
* <code>session</code> – A session ID previously obtained from the login module.
! Field    !! Type  !! Description
+
* <code>participant</code> – The participant to get the free/busy data for. May be either an internal user-, group- or resource-ID, or an e-mail address for external participants.
|-
+
* <code>from</code> – The lower (inclusive) limit of the requested time-range.
 +
* <code>until</code> – The upper (exclusive) limit of the requested time-range.
 +
* <code>merged</code> (optional) – True or False. Whether to pre-process the free/busy data on the server or not. This includes sorting as well as merging overlapping free/busy intervals.
 +
 
 +
Response: An array of free/busy intervals as described in [[#FreeBusyInterval | Free/Busy interval]]
 +
 
 +
{| id="FreeBusyInterval" cellspacing="0" border="1"
 +
|+ align="bottom" | Free/Busy interval
 +
! Name        !! Type    !! Value
 +
|-
 +
| start_date  || Time      || Start time of the interval.
 +
|-
 +
| end_date    || Time      || End time of the interval.
 +
|-
 +
| shown_as    || Number    || The busy status of this interval, one of:
 +
{| cellspacing="0" border="1"
 +
| 1 || unknown
 +
|-
 +
| 1 || reserved
 +
|-
 +
| 2 || temporary
 +
|-
 +
| 3 || absent
 +
|-
 +
| 4 || free
 +
|}
 +
|-
 +
| id          || String    || Object ID of the corresponding appointment if available.
 +
|-
 +
| folder_id  || String    || Folder ID of the corresponding appointment if available.
 +
|-
 +
| title      || String    || Title of the corresponding appointment if available.
 +
|-
 +
| location    || String    || Location of the corresponding appointment if available.
 +
|-
 +
| full_time  || Boolean    || True if the corresponding appointment is a whole day appointment, not present otherwise.
 +
|}
 +
 
 +
 
 +
=== Get a list of free/busy information ===
 +
 
 +
PUT <code>/ajax/freebusy?action=list</code>
 +
 
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>from</code> – The lower (inclusive) limit of the requested time-range.
 +
* <code>until</code> – The upper (exclusive) limit of the requested time-range.
 +
* <code>merged</code> (optional) – True or False. Whether to pre-process the free/busy data on the server or not. This includes sorting as well as merging overlapping free/busy intervals.
 +
 
 +
Request body: An array of participants to get the free/busy data for. Each participant may be either an internal user-, group- or resource-ID, or an e-mail address for external participants.
 +
 
 +
Response: The free/busy data for all requested participants inside a JSON object with the participants as keys. Besides a combined data element for a requested group, all group members are resolved and listed seperately in the result. If the 'merged' view was requested, an additional data element named 'merged' representing a combined view for all requested participants is added to the results implicitly.
 +
 
 +
 
 +
== Messaging Services ==
 +
 
 +
Messaging Services represent a messaging backend. The messaging services add a new folder module "messaging".
 +
 
 +
A *Messaging Service* Object has the following structure:
 +
 
 +
{| id="MessagingService" cellspacing="0" border="1"
 +
|+ align="bottom" | Messaging Service
 +
! Field    !! Type  !! Description
 +
|-
 
| id            || String      || Identifies a messagingService. Usually a String in reverse domain name notation. Example: "com.openexchange.messaging.twitter"
 
| id            || String      || Identifies a messagingService. Usually a String in reverse domain name notation. Example: "com.openexchange.messaging.twitter"
 
|-
 
|-
Line 4,496: Line 5,272:
  
 
Response: An array of arrays with the sub arrays containing the values of the fields asked for by the columns parameter.
 
Response: An array of arrays with the sub arrays containing the values of the fields asked for by the columns parameter.
 +
 +
== Snippet module (available with v7.0.0/v6.22.0) ==
 +
 +
=== Gets a certain snippet by identifier ===
 +
 +
GET /ajax/snippet?action=get
 +
 +
* session - The session identifier
 +
* id - The snippet identifier
 +
 +
Response:
 +
The snippet's JSON representation; e.g.
 +
 +
  {
 +
    "id": "1",
 +
    "type": "signature",
 +
    "props": {"x-custom": "any value"},
 +
    "module": "mail",
 +
    "displayname": "My signature",
 +
    "misc": {"foo": "bar"},
 +
    "createdby": 17,
 +
    "content": "-- \\nMy name and position here",
 +
    "accountid": 0,
 +
    "shared": false,
 +
    "files":
 +
    [
 +
      {
 +
        "mimetype": "image/png; name=pic.png",
 +
        "filename": "pic.png",
 +
        "id": "46f49f8a-40d5-4f29-8bc9-728f3420864c",
 +
        "size": 6074
 +
      }
 +
    ]
 +
  }
 +
 +
=== Gets all snippets associated with the current user and context ===
 +
 +
GET /ajax/snippet?action=all
 +
 +
* session - The session identifier
 +
* type - Optional CSV of types to filter by; e.g. "signature"
 +
 +
Response:
 +
A JSON array of snippets' JSON representations
 +
 +
 +
 +
=== Gets certain snippets by identifiers ===
 +
 +
GET /ajax/snippet?action=list
 +
 +
* session - The session identifier
 +
 +
Request body:
 +
A JSON array of snippet identifiers
 +
 +
Response:
 +
A JSON array of snippets' JSON representations
 +
 +
 +
 +
=== Gets a certain snippet's attachment by identifier ===
 +
 +
GET /ajax/snippet?action=getattachment
 +
 +
* session - The session identifier
 +
* id - The snippet identifier
 +
* attachmentid - The attachment identifier
 +
 +
Response:
 +
The attachment's raw data
 +
 +
 +
 +
=== Creates a new snippet ===
 +
 +
PUT /ajax/snippet?action=new
 +
 +
* session - The session identifier
 +
 +
Request body:
 +
A JSON representation of the snippet.
 +
Excluding its attachments (see attach/detach actions)
 +
 +
Response:
 +
The created snippet's identifier
 +
 +
 +
 +
=== Updates a certain snippet by identifier ===
 +
 +
PUT /ajax/snippet?action=update
 +
 +
* session - The session identifier
 +
* id - The snippet identifier
 +
 +
Request body:
 +
A JSON representation of the snippet providing the fields that should be changed.
 +
Excluding its attachments (see attach/detach actions)
 +
 +
Response:
 +
The updated snippet's JSON representation
 +
 +
 +
 +
=== Deletes a certain snippet by identifier ===
 +
 +
PUT /ajax/snippet?action=delete
 +
 +
* session - The session identifier
 +
* id - The snippet identifier (otherwise provide one or more identifiers through request body's JSON array)
 +
 +
Request body:
 +
A JSON array of identifiers denoting the snippets to delete
 +
 +
Response:
 +
An empty/dummy result (don't care)
 +
 +
 +
 +
=== Attaches one or more files to an existing snippet ===
 +
 +
POST /ajax/snippet?action=attach
 +
 +
* session - The session identifier
 +
* id - The snippet identifier
 +
 +
Request body:
 +
Multipart form data providing the upload files to attach to the snippet.
 +
 +
Response:
 +
The updated snippet's identifier
 +
 +
 +
 +
=== Detaches open or more files from an existing snippet ===
 +
 +
PUT /ajax/snippet?action=detach
 +
 +
* session - The session identifier
 +
* id - The snippet identifier
 +
 +
Request body:
 +
A JSON array providing the identifiers of the attachments to remove from snippet
 +
 +
Response:
 +
The updated snippet's identifier
 +
 +
== Module Halo ==
 +
 +
=== Investigate contact ===
 +
 +
PUT /appsuite/api/halo/contact?action=investigate
 +
 +
The investigate action provides access to different halo providers.
 +
Each provider requires an own set of parameters and also provides different results.
 +
The following section describes some but not necessarily all of this providers.
 +
Each request contains the following common parameters:
 +
 +
* <code>session</code> - A session ID previously obtained from the login module.
 +
* <code>provider</code> - The provider to use.
 +
* <code>timezone</code> - (optional) The timezone.
 +
 +
 +
In addition to this parameters a contact must be defined. This can be done either with at least one of the following parameters:
 +
 +
* <code>email1</code>
 +
* <code>email2</code>
 +
* <code>email3</code>
 +
* <code>internal_userid</code>
 +
 +
or within the request body.
 +
 +
Request body:
 +
 +
Instead of the contact parameters one can send a JSON object within the body of the request. This body describes the contact.
 +
If used, it must contain at least one of the fields shown below. If the requests contains a body, the contact specific parameters are ignored.
 +
It is also possible to provide more contact information. Empty fields are filled up with this values.
 +
 +
 +
JSON object:
 +
<pre>
 +
    {
 +
"contact_id":12345
 +
"internal_userid":12345
 +
"email1": mail1@domain.com
 +
"email2": mail2@domain2.com
 +
"email3": mail3@domain3.com
 +
    }
 +
</pre>
 +
 +
Request response:
 +
The request responds with a JSON object. The content and structure of this object depends on the chosen provider.
 +
In each case the response contains only data known to the server. Therefore some or all fields may be null.
 +
 +
 +
<strong> Provider: com.openexchange.halo.contacts </strong>
 +
 +
Request parameters:
 +
 +
* <code>columns</code> - A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for contacts are defined in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]].
 +
 +
Request response:
 +
 +
A JSON array with the contact informations specified by the columns parameter.
 +
 +
 +
<strong> Provider: com.openexchange.halo.appointments </strong>
 +
 +
Requests parameters:
 +
 +
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for tasks are defined in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[##DetailedTaskData | Detailed task data]].
 +
* <code>start</code> - The start point in milliseconds since 01.01.1970
 +
* <code>end</code> - The end point in milliseconds since 01.01.1970
 +
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
 +
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
 +
 +
Request response:
 +
 +
A JSON array of appointments. Each appointment contains the fields specified by the columns parameter.
 +
 +
 +
<strong> Provider: com.openexchange.halo.mail </strong>
 +
 +
Request parameters:
 +
 +
* <code>columns</code> - A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for mails are defined in [[#DetailedMailData | Detailed mail data]].
 +
* <code>limit</code> - The maximum number of mails within the result.
 +
 +
Request response:
 +
 +
A JSON array of mails. Each mail contains the fields specified by the columns parameter.
 +
 +
=== Get halo services ===
 +
 +
GET /appsuite/api/halo/contact?action=services
 +
 +
Request parameter:
 +
* <code>session</code> - A session ID previously obtained from the login module.
 +
 +
Request response:
 +
 +
A JSON object with a "data" field which contains an array of all available halo providers.
 +
 +
=== Get contact picture ===
 +
 +
GET /appsuite/api/halo/contact/picture
 +
* <code>session</code> - (optional) falls back to the public session cookie
 +
* <code>internal_userid</code> - (optional)  The internal user id of a user whose picture you want to load
 +
* <code>userid</code> - (optional) an alias for internal_userid
 +
* <code>user_id</code> - (optional)  an alias for internal_userid
 +
* <code>id</code> - (optional) a contact id
 +
* <code>email</code> - (optional) an email to search for. Will pick global address book matches before regular matches. After that picks the most recently changed contact
 +
* <code>email1</code> - (optional)  an alias for email
 +
* <code>email2</code> - (optional) another email address to use to find matches
 +
* <code>email3</code> - (optional) and yet another email address to use to find matches
 +
 +
''At least one of the optional search parameters should be set. All parameters are connected by OR during the search. More specific parameters like user_id or id are prioritized in case of multiple matches.''
 +
 +
Response:
 +
The picture with proper eTag and caching headers set, or an HTTP Status 404 response, if no picture could be found.
 +
 +
== Module "capabilities" (available with v7.4.2) ==
 +
 +
Provides access to capabilities, i.e. modules or features that are available on the backend and the user has access to.
 +
 +
=== Get a capability ===
 +
 +
GET <code>/ajax/capabilities?action=get</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>id</code> – The identifier of the capability
 +
 +
Response: The requested capability as described in [[#Capability| Capability]], if available, otherwise an empty result
 +
 +
{| id="Capability" cellspacing="0" border="1"
 +
|+ align="bottom" | Capability
 +
! Name        !! Type    !! Value
 +
|-
 +
| id  || String      || The identifier of the capability
 +
|-
 +
| attributes    || Object      || A JSON object holding optional properties of the capability
 +
|}
 +
 +
=== Get all capabilities ===
 +
 +
GET <code>/ajax/capabilities?action=all</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 +
Response: An array of capability objects as described in [[#Capability| Capability]].
 +
 +
 +
== Module "jump" (available with v7.6.0) ==
 +
 +
The jump module is used to pass an acquired identity token for an authenticated user from one system to another for a single sign-on.
 +
 +
=== Acquire an identity token ===
 +
 +
GET <code>/ajax/jump?action=identityToken</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>system</code> – The identifier for the external service/system
 +
 +
Response: The acquired identity token wrapped by a simple JSON object as described in [[#Jump| Jump]]
 +
 +
{| id="Jump" cellspacing="0" border="1"
 +
|+ align="bottom" | Jump
 +
! Name        !! Type    !! Value
 +
|-
 +
| token  || String      || The identifier of the token
 +
|}
 +
 +
== Module "find" (preliminary, available with v7.6.1) ==
 +
The Find API consists of calls for performing searches within the modules mail, contacts, calendar, tasks and drive. It was designed to provide an iterative approach where the search criteria can be refined step-wise until the desired items are found. The starting point is always an "autocomplete" request, that suggests possible search filters based on a users input. Those filters are grouped into categories, called "facets". A facet may provide one or more "values" with every value being a possible filter. A client is meant to remember every value that was selected by a user and include it within the following "autocomplete" and "query" requests, while "query" performs the actual search and returns the found items.
 +
 +
Every request is bound to a module that must be specified via the URL-Parameter "module". Possible modules are
 +
* mail
 +
* contacts
 +
* calendar
 +
* tasks
 +
* drive
 +
 +
=== General assumptions ===
 +
Some of the objects returned by the server contain former user input. A client must never interpret  strings as HTML but always as plain text to be not vulnerable for CSS attacks!
 +
 +
=== Calls ===
 +
The find API provides two dedicated calls under the servlet path <code>find</code>:
 +
* action=autocomplete
 +
* action=query
 +
 +
=== Facets ===
 +
The style of a facet is responsible for how the according object is structured, how it is handled on the server-side and how the client has to handle it.
 +
We distinguish three styles of facets:
 +
* simple
 +
* default
 +
* exclusive
 +
 +
Every facet value contains an embedded "filter" object. The filter must not be changed by the client, it has to be seen as a black-box. Instead the filters
 +
of selected facet values have to be copied and sent to the server with the subsequent requests.
 +
 +
==== Simple Facets ====
 +
A simple facet is a special facet that has exactly one value. The facets
 +
type and its value are strictly coupled, in a way that a display name for both,
 +
facet and value would be redundant. A simple facet generally denotes a logical field like
 +
'phone number'. Internally this logical field can map to several internal fields
 +
(e.g. 'phone_private', 'phone_mobile', 'phone_business'). In clients the facet as
 +
a whole can be displayed as a single item. Example: "Search for 'term' in field 'phone
 +
number'".
 +
 +
 +
{| id="Facet Structure" cellspacing="0" border="1"
 +
|+ align="bottom" | Facet Structure
 +
! Field    !! Type  !! Description
 +
|-
 +
| style || "simple" || Denotes that this is a facet of style simple
 +
|-
 +
| id || <string> || The id of this facet. Unique within an autocomplete response. Can be used to distinguish and filter certain facets.
 +
|-
 +
| name || <string> || A displayable (and localized) name for this facet. If absent, an "item" attribute is present.
 +
|-
 +
| item (optional) || <object> || A more complex object to display this facet. Attributes are "name", "detail" (optional) and "image_url" (optional).
 +
|-
 +
| filter || <object> || The filter to refine the search.
 +
|-
 +
| flags || <array> || An array of flags, represented as strings.
 +
|}
 +
 +
Example:
 +
<pre>
 +
{
 +
    "id":"global",
 +
    "style":"simple",
 +
    "name":"test",
 +
    "filter":{},
 +
    "flags":[]
 +
}
 +
</pre>
 +
 +
==== Default Facets ====
 +
A default facet contains multiple values and may be present
 +
multiple times in search requests to filter results by a combination of different
 +
values (e.g. "mails with 'foo' and 'bar' in subject").
 +
 +
Facet values may be one- or two-dimensional. A one-dimensional value can be displayed as is and contains an according filter object.
 +
A two-dimensional value contains an array "options" with every option defining different semantics of how the value is used to filter the search results.
 +
 +
{| id="Default Facet Structure" cellspacing="0" border="1"
 +
|+ align="bottom" | Facet Structure
 +
! Field    !! Type  !! Description
 +
|-
 +
| style || "default" || Denotes that this is a facet of style default
 +
|-
 +
| id || <string> || The id of this facet. Unique within an autocomplete response. Can be used to distinguish and filter certain facets.
 +
|-
 +
| name || <string> || A displayable (and localized) name for this facet. If absent, an "item" attribute is present.
 +
|-
 +
| item (optional) || <object> || A more complex object to display this facet. Attributes are "name", "detail" (optional) and "image_url" (optional).
 +
|-
 +
| values || <array> || An array of facet values.
 +
|-
 +
| flags || <array> || An array of flags, represented as strings.
 +
|}
 +
 +
{| id="Default Facet Value Structure" cellspacing="0" border="1"
 +
|+ align="bottom" | Value Structure
 +
! Field    !! Type  !! Description
 +
|-
 +
| id || <string> || The values id. Unique within one facet.
 +
|-
 +
| name || <string> || A displayable (and localized) name for this value. May be superseded with an "item" attribute. Absent if the value contains options.
 +
|-
 +
| item (optional) || <object> || A more complex object to display this value. Attributes are "name", "detail" (optional) and "image_url" (optional). Absent if the value contains options.
 +
|-
 +
| filter || <object> || The filter to refine the search. Absent if the value contains options.
 +
|-
 +
| options (optional) || <array> || An array of options.
 +
|}
 +
 +
{| id="Default Facet Option Structure" cellspacing="0" border="1"
 +
|+ align="bottom" | Option Structure
 +
! Field    !! Type  !! Description
 +
|-
 +
| id || <string> || The options id. Unique within a set of options.
 +
|-
 +
| name || <string> || The displayable (and localized) name for this option.
 +
|-
 +
| filter || <object> || The filter to refine the search.
 +
|-
 +
|}
 +
 +
Example:
 +
<pre>
 +
{
 +
    "id":"contacts",
 +
    "style":"default",
 +
    "name":"People",
 +
    "values":[
 +
      {
 +
        "id":"contact/424242669/525793",
 +
        "item":{
 +
          "name":"Test Usere2123",
 +
          "detail":"testuse1212r@example.com"
 +
        },
 +
        "options":[
 +
          {
 +
            "id":"from",
 +
            "name":"From",
 +
            "filter":{}
 +
          },
 +
          {
 +
            "id":"to",
 +
            "name":"To",
 +
            "filter":{}
 +
          },
 +
          {
 +
            "id":"all",
 +
            "name":"From/To",
 +
            "filter":{}
 +
          }
 +
        ]
 +
      }
 +
    ],
 +
    "flags":[]
 +
}
 +
</pre>
 +
 +
==== Exclusive Facets ====
 +
An exclusive facet is a facet where the contained values are
 +
mutually exclusive. That means that the facet must only be present once
 +
in an autocomplete or query request.
 +
 +
Facet values may be one- or two-dimensional. A one-dimensional value can be displayed as is and contains an according filter object.
 +
A two-dimensional value contains an array "options" with every option defining different semantics of how the value is used to filter the search results.
 +
 +
{| id="Exclusive Facet Structure" cellspacing="0" border="1"
 +
|+ align="bottom" | Facet Structure
 +
! Field    !! Type  !! Description
 +
|-
 +
| style || "exclusive" || Denotes that this is a facet of style exclusive
 +
|-
 +
| id || <string> || The id of this facet. Unique within an autocomplete response. Can be used to distinguish and filter certain facets.
 +
|-
 +
| name || <string> || A displayable (and localized) name for this facet. If absent, an "item" attribute is present.
 +
|-
 +
| item (optional) || <object> || A more complex object to display this facet. Attributes are "name", "detail" (optional) and "image_url" (optional).
 +
|-
 +
| options || <array> || An array of facet values.
 +
|-
 +
| flags || <array> || An array of flags, represented as strings.
 +
|}
 +
 +
{| id="Exclusive Facet Value Structure" cellspacing="0" border="1"
 +
|+ align="bottom" | Value Structure
 +
! Field    !! Type  !! Description
 +
|-
 +
| id || <string> || The values id. Unique within one facet.
 +
|-
 +
| name || <string> || A displayable (and localized) name for this value. May be superseded with an "item" attribute. Absent if the value contains options.
 +
|-
 +
| item (optional) || <object> || A more complex object to display this value. Attributes are "name", "detail" (optional) and "image_url" (optional). Absent if the value contains options.
 +
|-
 +
| filter || <object> || The filter to refine the search. Absent if the value contains options.
 +
|-
 +
| options (optional) || <array> || An array of options.
 +
|}
 +
 +
{| id="Exclusive Facet Option Structure" cellspacing="0" border="1"
 +
|+ align="bottom" | Option Structure
 +
! Field    !! Type  !! Description
 +
|-
 +
| id || <string> || The options id. Unique within a set of options.
 +
|-
 +
| name || <string> || The displayable (and localized) name for this option.
 +
|-
 +
| filter || <object> || The filter to refine the search.
 +
|-
 +
|}
 +
 +
Example:
 +
<pre>
 +
{
 +
    "id":"time",
 +
    "style":"exclusive",
 +
    "name":"Time",
 +
    "options":[
 +
      {
 +
        "id":"last_week",
 +
        "name":"last week",
 +
        "filter":{}
 +
      },
 +
      {
 +
        "id":"last_month",
 +
        "name":"last month",
 +
        "filter":{}
 +
      },
 +
      {
 +
        "id":"last_year",
 +
        "name":"last year",
 +
        "filter":{}
 +
      }
 +
    ],
 +
    "flags":[]
 +
}
 +
</pre>
 +
 +
 +
==== Active Facets ====
 +
Every value that has been selected by a user must be remembered and provided with every subsequent request. The representation of a facet within a request body differs from the one within an autocomplete response. We call those "active facets". Their representation is independent from their style.
 +
 +
{| id="Active Facet Structure" cellspacing="0" border="1"
 +
|+ align="bottom" | Active Facet Structure
 +
! Field    !! Type  !! Description
 +
|-
 +
| facet || <string> || The id of the according facet.
 +
|-
 +
| value || <string> || The id of the according value. Must always be copied from the value object, not from a possibly according option (in the two-dimensional case).
 +
|-
 +
| filter || <object> || The filter object, copied from the value or option.
 +
|}
 +
 +
=== Configuration ===
 +
According to the users configuration, some restrictions may apply that have to be heeded by clients. Those restrictions can be retrieved via the "config" or the "jslob" modules. The following restrictions may apply:
 +
 +
* A user might have limited access to modules and therefore the Find API may only serve requests for a subset of all possible modules. The configuration object may contain an object with key "modules". Its value is an array containing all module identifiers that the user is allowed to use. If the user is not allowed to search in any module, the value will be null.
 +
 +
* Some facets can be mandatory, i.e. they must be pre-defined by the client and provided with every request. Whether a facet is mandatory or not is decided on a per-module basis. The configuration object may contain an object with key "mandatory". Every facet that may be mandatory is specified via its id in that object (e.g. mandatory.folder). The value of such a key is either an array containing all module identifiers, where the facet is mandatory or null, if it is not manadatory in any module.
 +
 
 +
* Due to performance reasons the service provider can enforce a minimium number of characters that have to be provided before an autocomplete request may be issued. That property is called "minimumQueryLength" and its value is an integer that specifies the minimum number of characters. If a client does not heed this property, the server will respond with an error if the provided user input is too short.
 +
 +
==== Config Example ====
 +
<pre>
 +
GET http://localhost/appsuite/api/config/search?session={{session}}
 +
Response:
 +
{
 +
    "data": {
 +
        "mandatory": {
 +
            "folder": [
 +
                "mail"
 +
            ]
 +
        },
 +
        "modules": [
 +
            "mail",
 +
            "contacts",
 +
            "calendar",
 +
            "tasks",
 +
            "drive"
 +
        ]
 +
    }
 +
}
 +
 +
GET http://localhost/appsuite/api/config/minimumSearchCharacters?session={{session}}
 +
Response:
 +
{
 +
    "data": 0
 +
}
 +
</pre>
 +
 +
==== JSLob Example ====
 +
<pre>
 +
GET http://localhost/appsuite/api/jslob?action=get&id=io.ox/core&session={{session}}
 +
Response:
 +
{
 +
    "data": {
 +
        "id": "io.ox/core",
 +
        "tree": {
 +
            "search": {
 +
                "modules": [
 +
                    "mail",
 +
                    "contacts",
 +
                    "calendar",
 +
                    "tasks",
 +
                    "drive"
 +
                ],
 +
                "mandatory": {
 +
                    "folder": [
 +
                        "mail"
 +
                    ]
 +
                },
 +
                "minimumQueryLength": 0
 +
            }
 +
        }
 +
    }
 +
}
 +
</pre>
 +
 +
=== autocomplete ===
 +
Mandatory URL parameters:
 +
* action=autocomplete
 +
* module=<module-name>
 +
* session=<session-id>
 +
 +
Optional URL parameters:
 +
* limit=<int> - The maximum number of values returned per facet
 +
 +
Request body: A JSON object containing the users input (specified as "prefix"), already selected facets and possible options.
 +
 +
 +
==== Example ====
 +
<pre>
 +
PUT http://localhost/appsuite/api/find?action=autocomplete&module=mail&limit=3&session={{session}}
 +
{
 +
  "prefix":"test", 
 +
  "facets":[
 +
    {
 +
      "facet":"folder",
 +
      "value":"default0/INBOX"
 +
    }
 +
  ],
 +
  "options":{
 +
    "timezone":"UTC",
 +
    "admin":false
 +
  }
 +
}
 +
 +
Response:
 +
{
 +
  "data":{
 +
    "facets":[
 +
      {
 +
        "id":"global",
 +
        "style":"simple",
 +
        "name":"test",
 +
        "filter":{},
 +
        "flags":[]
 +
      },     
 +
      {
 +
        "id":"contacts",
 +
        "style":"default",
 +
        "name":"People",
 +
        "values":[
 +
          {
 +
            "id":"contact/424242669/525793",
 +
            "item":{
 +
              "name":"Test Usere2123",
 +
              "detail":"testuse1212r@example.com"
 +
            },
 +
            "options":[
 +
              {
 +
                "id":"from",
 +
                "name":"From",
 +
                "filter":{}
 +
              },
 +
              {
 +
                "id":"to",
 +
                "name":"To",
 +
                "filter":{}
 +
              },
 +
              {
 +
                "id":"all",
 +
                "name":"From/To",
 +
                "filter":{}
 +
              }
 +
            ]
 +
          }
 +
        ],
 +
        "flags":[]
 +
      },
 +
      {
 +
        "id":"time",
 +
        "style":"exclusive",
 +
        "name":"Time",
 +
        "options":[
 +
          {
 +
            "id":"last_week",
 +
            "name":"last week",
 +
            "filter":{}
 +
          },
 +
          {
 +
            "id":"last_month",
 +
            "name":"last month",
 +
            "filter":{}
 +
          },
 +
          {
 +
            "id":"last_year",
 +
            "name":"last year",
 +
            "filter":{}
 +
          }
 +
        ],
 +
        "flags":[]
 +
      }
 +
    ]
 +
  }
 +
}
 +
</pre>
 +
 +
=== query ===
 +
Mandatory URL parameters:
 +
* action=query
 +
* module=<module-name>
 +
* session=<session-id>
 +
 +
Optional URL parameters:
 +
* columns=<column-ids> - A comma-separated list of the module-specific columns that shall be contained in the response items.
 +
 +
Request body: A JSON object containing the selected facets and possible options. For pagination the keys "start" and "size" can be set.
 +
 +
==== Example ====
 +
<pre>
 +
PUT http://localhost/appsuite/api/find?action=query&module=mail&columns=102,600,601,602,603,604,605,607,608,610,611,614,652&session={{session}}
 +
{
 +
  "facets":[
 +
    {
 +
      "facet":"folder",
 +
      "value":"default0/INBOX",
 +
      "filter":null
 +
    },
 +
    {
 +
      "facet":"subject",
 +
      "value":1409579708116,
 +
      "filter":{
 +
        "fields":[
 +
          "subject"
 +
        ],
 +
        "queries":[
 +
          "lorem"
 +
        ]
 +
      }
 +
    }
 +
  ],
 +
  "options":{
 +
    "timezone":"UTC",
 +
    "admin":false
 +
  },
 +
  "start":0,
 +
  "size":101
 +
}
 +
 +
Response:
 +
{
 +
  "data":{
 +
    "num_found":-1,
 +
    "start":0,
 +
    "size":1,
 +
    "results":[
 +
      {
 +
        "color_label":0,
 +
        "id":"110458",
 +
        "folder_id":"default0/INBOX",
 +
        "attachment":false,
 +
        "from":[
 +
          [
 +
            "John Doe",
 +
            "john.doe@example.com"
 +
          ]
 +
        ],
 +
        "to":[
 +
          [
 +
            "Jane Doe",
 +
            "jane.doe@example.com"
 +
          ]
 +
        ],
 +
        "cc":[
 +
 +
        ],
 +
        "subject":"Lorem Ipsum",
 +
        "size":7501,
 +
        "received_date":1408531387000,
 +
        "flags":32,
 +
        "priority":3,
 +
        "account_name":"E-Mail",
 +
        "account_id":0
 +
      }
 +
    ]
 +
  }
 +
}
 +
</pre>
 +
 +
=== Available Options ===
 +
Every request body may contain an "options" object to finetune some specific behavior. Currently possible options are:
 +
* timezone: <tz-name> - The timezone to use if any dates are returned.
 +
* admin: <boolean> - true to include the context admin if it matches any search criteria. If the context admin shall always be ignored (i.e. not returned), false has to be set.
 +
 +
=== Possible Flags ===
 +
Every facet may carry one or more flags that describe further aspects of that facet. Currently possible flags are:
 +
* conflicts - Specified in the form of "conflicts:<other-id>". A facet carrying this flag must not be combined with a facet of type <other-id>.
 +
 +
 +
== Module "share/management" (preliminary, available with v7.8.0) ==
 +
 +
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].
 +
 +
=== Get a link ===
 +
 +
PUT <code>/ajax/share/management?action=getLink</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 +
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].
 +
 +
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].
 +
 +
{| id="ShareTarget" cellspacing="0" border="1"
 +
|+ align="bottom" | Share Target
 +
! Name                !! Type  !! Value
 +
|-
 +
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore"
 +
|-
 +
| folder || String || The folder identifier
 +
|-
 +
| item  || String || (Optional) The object identifier, in case the share targets a single item
 +
|}
 +
 +
{| id="ShareLink" cellspacing="0" border="1"
 +
|+ align="bottom" | Share Link
 +
! Name                !! Type  !! Value
 +
|-
 +
| url  || String  || The link to the share (read-only)
 +
|-
 +
| entity  || Number  || The identifier of the anonymous user entity for the share (read-only)
 +
|-
 +
| is_new  || Boolean  || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed  (read-only)
 +
|-
 +
| expiry_date || Time  ||  (Optional) The end date / expiration time after which the share link is no longer accessible.
 +
|-
 +
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share
 +
|-
 +
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client
 +
|}
 +
 +
=== Update a link ===
 +
 +
PUT <code>/ajax/share/management?action=updateLink</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.
 +
 +
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.
 +
 +
Response with timestamp: An empty JSON result in case of no errors.
 +
 +
=== Delete a link ===
 +
 +
PUT <code>/ajax/share/management?action=deleteLink</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 +
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].
 +
 +
Response with timestamp: An empty JSON result in case of no errors.
 +
 +
=== Send a link ===
 +
 +
PUT <code>/ajax/share/management?action=sendLink</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 +
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. The first element of each address is the personal name, the second element is the email address. Missing address parts are represented by <code>null</code> values. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).
 +
 +
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.
 +
 +
== Module "drive" ==
 +
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side.
 +
 +
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].
 +
 +
 +
== Module "passwordchange" ==
 +
 +
Users can change their password via the "passwordchange" module.
 +
 +
=== Update password ===
 +
 +
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set.
 +
 +
PUT <code>/ajax/passwordchange?action=update</code>
 +
 +
Parameters:
 +
* <code>session</code> – A session ID previously obtained from the login module.
 +
 +
Request body: A JSON object as described in PasswordChange.
 +
 +
Response: An empty JSON result in case of no errors.
 +
 +
{| id="PasswordChange" cellspacing="0" border="1"
 +
|+ align="bottom" | Password change
 +
! Name                !! Type  !! Value
 +
|-
 +
| old_password || String || The users' current password or 'null' if the password wasn't set before (especially for guest users)
 +
|-
 +
| new_password || String || The new password the user wants to set or 'null' to remove the password (especially for guest users)
 +
|-
 +
|}
 +
 +
== File Storage Services ==
 +
 +
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.
 +
 +
A *File Storage Service* Object has the following structure:
 +
 +
{| id="FileStorageService" cellspacing="0" border="1"
 +
|+ align="bottom" | File Storage Service
 +
! Field    !! Type  !! Description
 +
|-
 +
| id            || String      || Identifies a file storage service. Example: "boxcom"
 +
|-
 +
| displayName  || String      || Human readable display name of the service. Example: "Box File Storage Service"
 +
|-
 +
| configuration || JSON object      || A description for dynamic form fields. Same as in PubSub
 +
|-
 +
|}
 +
 +
The available JSON calls are:
 +
 +
=== Get all available file storage accounts ===
 +
GET /ajax/fileservice?action=all
 +
 +
* session - A session ID previously obtained from the login module.
 +
 
 +
Response: A standard response object containing an array of file storage service objects.
 +
 +
=== Get a file storage account ===
 +
GET /ajax/fileservice?action=get
 +
 +
* session - A session ID previously obtained from the login module.
 +
* id - The ID of the file storage service to load
 +
 +
Response: A standard response object containing a file storage service object.
 +
 +
== File Storage Accounts ==
 +
 +
A file storage account represents the concrete configuration of an account of a given file storage service.
 +
A *file storage account* has the following structure:
 +
 +
{| id="FileStorageAccount" cellspacing="0" border="1"
 +
|+ align="bottom" | File Storage Account
 +
! Field    !! Type  !! Description
 +
|-
 +
| id          || String      || Identifies a given file storage account in the scope of its file storage service (Infostore, Dropbox.com, Google OneDrive etc.). This is not writeable and is generated by the server
 +
|-
 +
| filestorageService || String  || The identifier of the file storage service this account belongs to
 +
|-
 +
| qualifiedId || String || Identifies a given file storage account globally, i.e. accross all file storage services. This is not writeable and is generated by the server
 +
|-
 +
| displayName || String || User chosen String to identify a given account. Will also be translated into the folder name of the folder representing the accounts content
 +
|-
 +
| rootFolder || String || ID of the accounts root folder within the folder tree. This is not writeable and is generated by the server
 +
|-
 +
| isDefaultAccount || Boolean || Whether this account is the users default account. Exactly one account will have this flag set to <code>true</code>.
 +
|-
 +
| configuration || Object || Configuration data according to the formDescription of the relevant file storage service
 +
|-
 +
| capabilities || List of Strings || A list of capability names. Possible values are: "FILE_VERSIONS", "EXTENDED_METADATA", "RANDOM_FILE_ACCESS", "LOCKS"
 +
|}
 +
 +
The available JSON calls are
 +
 +
=== Create a file storage account ===
 +
PUT /ajax/fileaccount?action=new
 +
 +
* session - A session ID previously obtained from the login module.
 +
 +
Request body: A JSON Object describing the account to be created.
 +
Response: A response object containing the new account id as its data.
 +
 +
 +
=== Update a file storage account ===
 +
PUT /ajax/fileaccount?action=update
 +
 +
* session - A session ID previously obtained from the login module.
 +
 +
Request body: A JSON Object describing the update to the account. Note that the "id" and "filestorageService" must always be set.
 +
Response: A response object containing the number 1 as its data on success.
 +
 +
 +
=== Get a file storage account ===
 +
GET /ajax/fileaccount?action=get
 +
 +
* session - A session ID previously obtained from the login module.
 +
* filestorageService - The file storage service id that the account belongs to
 +
* id - An account ID to load
 +
 +
Response: A response object containing the JSON Object representing the loaded account as its data.
 +
 +
 +
=== Delete a file storage account ===
 +
GET /ajax/fileaccount?action=delete
 +
 +
* session - A session ID previously obtained from the login module.
 +
* filestorageService - The file storage service id that the account belongs to
 +
* id - An account ID to delete
 +
 +
Response: A response object containing 1 as its data on success.
 +
 +
 +
=== Get all available file storage accounts ===
 +
GET /ajax/fileaccount?action=all
 +
 +
* session - A session ID previously obtained from the login module
 +
* filestorageService - (optional) list only those accounts that belong to the given file storage service.
 +
 +
Response: A response object containing a JSON array of account objects in its data section.
 +
 +
 +
=== Example for creating a new OAuth-based file storage account ===
 +
 +
First, get the description of the file storage service for which a new account is supposed to be created:<br>
 +
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code>
 +
 +
The response might be:
 +
<code>
 +
  {
 +
    id: "boxcom"
 +
    displayName: "Box File Storage Service"
 +
    configuration: {
 +
      widget: "oauthAccount"
 +
      options: {
 +
        type: "com.openexchange.oauth.boxcom"
 +
      }
 +
      name: "account"
 +
      displayName: "Select an existing account"
 +
      mandatory: true
 +
    }
 +
  }
 +
</code>
 +
 +
Next get the associated OAuth account information:<br>
 +
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code>
 +
 +
The response might be:
 +
<code>
 +
  {"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}
 +
</code>
 +
 +
Finally, create the file storage account:<br>
 +
<code>
 +
  PUT /ajax/fileaccount?action=new&session=...
 +
 
 +
  {
 +
    "filestorageService":"boxcom",
 +
    "displayName":"My box.com account",
 +
    "configuration":{
 +
      "account":"333",
 +
      "type":"com.openexchange.oauth.boxcom"
 +
    }
 +
  }
 +
</code>
 +
 +
The response provides the relative (in context of the according file storage service) identifier of the newly created account:
 +
<code>{"data":19}</code>

Revision as of 09:40, 5 July 2017

This information is valid until 7.8.2

The latest content on this page has moved to https://documentation.open-xchange.com/components/middleware/http/latest/index.html.

Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.

Contents

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.

Response body
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

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

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


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.

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.

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.

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,
  • for POST requests all described parameters are normally expected in the request body, exceptions are documented,
  • "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.

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.

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

Because of security reasons each login variation will reject requests containing the parameter "password" within the URL query (starting with 7.8.0).

Login

POST /ajax/login?action=login

Parameters are normally expected in the POST request body:

  • name – The login name.
  • password – The password MUST be placed in the request body, otherwise the login request will be denied.
  • 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 the HTTP 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 the HTTP 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.

DISCLAIMER: This request MUST NOT be used by some server side instance. If some server side instance uses this request to create a session for a browser on some client machine, then you have to transfer the full URL with server and client token over some connection to the client. This creates a VULNERABILITY if this is done. The token login method is only secure if this request is already sent from the same machine that later runs the browser using the created 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 the HTTP 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.
  • jsonResponse (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect.


Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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.

Autologin

If the session ID was stored in a cookie before via the store request, the user can reuse his old session by using the autologin request.

GET /ajax/login?action=autologin

Parameters:

  • 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.
  • client (optional) – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.

Response: A JSON object containing the session ID used for all subsequent requests.

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/
    • gui – A string containing GUI-specific settings (currently, it is a huge JSON object).
    • fastgui - A string containing GUI-specific settings. This is a JSON object that must be kept small for performance.
    • context_id - the unique identifier of the context (read-only, added 2008-01-28).
    • cookielifetime - the cookie life time in seconds or -1 for session cookie (read-only, added 2010-11-16).
    • identifier – the unique identifier of the user (read-only).
    • contact_id – the unique identifier of the contact data of the user (read-only).
    • language – the configured language of the user.
    • timezone – the configured timezone of the user.
    • 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).
    • calendarnotification - send a mail notification for appointments (deprecated since 2008-12-11)
    • tasknotification - send a mail notification for tasks (deprecated since 2008-12-11)
    • reloadTimes - Selectable times for GUI reload
    • serverVersion - Version string of the server.
    • currentTime - User timezone specific long of the current server time.
    • maxUploadIdleTimeout - Timeout after that idle uploads are deleted.
    • 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)
    • 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)
    • participants
      • autoSearch - If a search for all users, groups and resources when participant selection dialog is opened. (read-only, added 2008-10-09/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)
    • 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)
    • minimumSearchCharacters – Minimum number of characters a search pattern must have to prevent large responses and slow queries. (read-only, added 2008-10-20/SP5)
    • 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)
          • pictures – identifier of the default infostore pictures folder (read-only, since 7.8.0)
          • documents – identifier of the default infostore documents folder (read-only, since 7.8.0)
          • music – identifier of the default infostore music folder (read-only, since 7.8.0)
          • videos – identifier of the default infostore videos folder (read-only, since 7.8.0)
          • templates – identifier of the default infostore templates folder (read-only, since 7.8.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.


Get a property (since 7.6.2)

GET /ajax/config?action=get_property

Parameters:

  • session – A session ID previously obtained from the login module.
  • name – The name of the property to return.

Response: A JSON response providing the property's name and its value; e.g.

 {
   "data": {
       "name": "com.openexchange.dummy.prop001",
       "value": "test1234"
   }
 }

Set a property (since 7.6.2)

Note: Only allowed for context administrator!

PUT /ajax/config?action=set_property

Parameters:

  • session – A session ID previously obtained from the login module.
  • name – The name of the property to set.

Request body: A JSON object providing the value to set; e.g

 {"value":"test1237"}


Response: A JSON response providing the property's name and its new value; e.g.

 {
   "data": {
       "name": "com.openexchange.dummy.prop001",
       "value": "test1237"
   }
 }

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.

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 Type of folder:
1 private
2 public
3 shared
5 system folder
7 This type is no more in use (legacy type). Will be removed with a future update!
16 trash
20 pictures
21 documents
22 music
23 videos
24 templates
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.


Permission flags
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 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.
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.

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 and Detailed 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.
  • cascadePermissions – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)

Request body: Folder object as described in Common folder data and Detailed folder data. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders for all modules except mail. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:

{
  "folder":{
    "permissions":[
      {
        "bits":403710016,
        "entity":84,
        "group":false
      },
      {
        "type":"guest",
        "email_address":"john.doe@example.com",
        "display_name":"John Doe",
        "bits":257
      }
    ]
  },
  "notification":{
    "transport":"mail",
    "message":"Hi!\nHave a look at this!"
  }
}

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. It is possible to let added permission entities be notified about newly shared folders for all modules except mail. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:

{
  "folder":{
    "permissions":[
      {
        "bits":403710016,
        "entity":84,
        "group":false
      },
      {
        "type":"guest",
        "email_address":"john.doe@example.com",
        "display_name":"John Doe",
        "bits":257
      }
    ]
  },
  "notification":{
    "transport":"mail",
    "message":"Hi!\nHave a look at this!"
  }
}

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 – The optional 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 concurrent modification. Meaning you receive an empty JSON array if everything worked well.

Get all visible folder of a certain module (since v6.18.2)

GET /ajax/folders?action=allVisible

Parameters:

  • session – A session ID previously obtained from the login module.
  • tree – The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
  • content_type – The desired content type (either numbers or strings; e.g. "tasks", "calendar", "contacts", "mail", "infostore")
  • 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.

Response with timestamp: A JSON object containing three fields: "private", "public, and "shared". Each field is a JSON array with data for all folders. Each folder is itself described by an array.

Get shared folders (Since 7.8.0, Preliminary)

GET /ajax/folders?action=shares

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.
  • 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.
  • content_type – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".

Response with timestamp: An array with data for all folders that are considered as shared by the user. 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.

Notify about shared folder (Since 7.8.0, Preliminary)

PUT /ajax/folders?action=notify

Parameters:

  • session – A session ID previously obtained from the login module.
  • tree – The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
  • id – Object ID of the shared folder to notify about.

Request body: A JSON object providing the JSON array entities, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object notification may be included, inside of which an optional message can be passed (otherwise, some default message is used).

Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.

Module "tasks"

The tasks module is used to access task information.

Get all tasks

GET /ajax/tasks?action=all

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for tasks are defined in Common object data, Detailed task and appointment data and Detailed task data.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.

Response with timestamp: An array with task data. Each array element describes one task and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

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:
0 none (single event)
1 daily
2 weekly
3 monthly
4 yearly
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 table.
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.
Participant identifier
Name Type Value
id Number User ID
type Number Type of participant:
1 user
2 user group
3 resource
4 resource group
5 external user
mail String mail address of an external participant
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
0 none
1 accepted
2 declined
3 tentative
confirmmessage String Confirm Message of the participant
Confirming participant
Name Type Value
type Number Type of participant:
1 user
5 external user
mail String email address of external participant
display_name String display name of external participant
status Number
0 none
1 accepted
2 declined
3 tentative
message String Confirm Message of the participant
Detailed task data
ID Name Type Value
300 status Number Status of the task:
1 not started
2 in progress
3 done
4 waiting
5 deferred
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.

Get a list of tasks

PUT /ajax/tasks?action=list

Parameters:

Request body: An array of with object IDs of requested tasks.

Response with timestamp: An array with task data. Each array element describes one task and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Get updated tasks

GET /ajax/tasks?action=updates

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for tasks are defined in Common object data, Detailed task and appointment data and Detailed task data.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • timestamp – Timestamp of the last update of the requested tasks.
  • ignore – Which kinds of updates should be ignored. Omit this parameter or set it to "deleted" to not have deleted tasks identifier in the response. Set this parameter to "false" and the response contains deleted tasks identifier.

Response with timestamp: An array with new, modified and deleted tasks. New and modified tasks are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted tasks would be identified by their object IDs as plain strings, without being part of a nested array.

Get a task

GET /ajax/tasks?action=get

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the requested task.
  • folder – Object ID of the task's folder.

Response with timestamp: An object containing all data of the requested task. The fields of the object are listed in Common object data, Detailed task and appointment data and Detailed task data. The field id is not included.

Update a task

PUT /ajax/tasks?action=update

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Folder Identifier through that the task is accessed. This is necessary for checking the permissions.
  • id – Object ID of the updated task.
  • timestamp – Timestamp of the updated task. If the task was modified after the specified timestamp, then the update must fail.

Request body: Task object as described in Common object data, Detailed task and appointment data and Detailed task data. Only modified fields are present.

Create a task

PUT /ajax/tasks?action=new

Parameters:

  • session – A session ID previously obtained from the login module.

Request body: Task object as described in Common object data, Detailed task and appointment data and Detailed task data. The field id is not present.

Response: A json objekt with attribute id of the newly created task.

Delete task

PUT /ajax/tasks?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the deleted tasks.

Request body: An object in the field “id” and “folder”.

Response: An array with object IDs of tasks which were modified after the specified timestamp and were therefore not deleted.

Delete tasks (since v6.22)

PUT /ajax/tasks?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the deleted tasks.

Request body: An array of objects with the fields “id” and “folder”.

Response: An array with object IDs of tasks which were modified after the specified timestamp and were therefore not deleted.

Confirm task

PUT /ajax/tasks?action=confirm

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the to confirm task.
  • folder – ID of the folder through that the task is accessed.
  • timestamp – Timestamp of the last update of the to confirm task.

Request body: An object with the fields "confirmation" and "confirmmessage" as described in User participant object.

Response: Nothing, except the standard response object with empty data, the timestamp of the confirmed and thereby updated task, and maybe errors.

Search for tasks

PUT /ajax/tasks?action=search

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 appointments are defined in Common object data, Detailed task and appointment data and Detailed task data.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified , then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.

Request Body: A JSON object with attributes described in Search tasks

Search tasks
Name Type Value
pattern String Search pattern to find tasks. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves.
folder Number (optional) Defines the folder to search for tasks in. If this is omitted in all task folders will be searched.
start Date or Time (optional) Inclusive start date for a time range the tasks should end in. If start is omitted end is ignored.
end Date or Time (optional) Exclusive end date for a time range the tasks should end in. If this parameter is omitted the time range has an open end.

Response with timestamp: An array with matching tasks. Tasks are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Module "contacts"

The contacts module is used to access contact information.

Get all contacts

GET /ajax/contacts?action=all

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried (optional from 6.22.2 on: If not set, the contents of all visible folders are used instead).
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for contacts are defined in Common object data and Detailed contact data.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • collation (preliminary, since 6.20) – allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter sort should be set for this to work.

Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Detailed contact data
ID Displayed name Name Type Value
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.
0 independent contact
1 default email field (email1)
2 second email field (email2)
3 third email field (email3)

Get a list of contacts

PUT /ajax/contacts?action=list

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 contacts are defined in Common object data and Detailed contact data.

Request body: An array with objects. Each object contains fields “id” and “folder” of requested contacts.

Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Get a list of users

PUT /ajax/contacts?action=listuser

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 contacts are defined in Common object data and Detailed contact data.

Request body: An array with id

Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Available with SP4

Get updated contacts

GET /ajax/contacts?action=updates

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for contacts are defined in Common object data and Detailed contact data.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • timestamp – Timestamp of the last update of the requested contacts.
  • ignore (mandatory - should be set to "deleted") (deprecated) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.

Response with timestamp: An array with new, modified and deleted contacts. New and modified contacts are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted contacts (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 contact

GET /ajax/contacts?action=get

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the requested contact.
  • folder – Object ID of the contact's folder.

Response with timestamp: An object containing all data of the requested contact. The fields of the object are listed in Common object data and Detailed contact data. The field id is not included.

Get contact by user ID

GET /ajax/contacts?action=getuser

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – User ID (not Object ID) of the requested user.

Response with timestamp: An object containing all data of the requested contact. The fields of the object are listed in Common object data and Detailed contact data.

Available with SP4 package.

Update a contact

PUT /ajax/contacts?action=update

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Folder identifier through that the contact is accessed. This is necessary for checking the permissions.
  • id – Object ID of the updated contact.
  • timestamp – Timestamp of the updated contact. If the contact was modified after the specified timestamp, then the update must fail.

Request body: Contact object as described in Common object data and Detailed contact data. Only modified fields are present.

To remove some contact image send the image attribute set to null.

To change or add some contact image the PUT command must be replaced with a POST command and all data must be provided within a multipart/form-data body. The normal request body must be placed into a form field named json while the image file must be placed in a file field named file. The response is then an HTML page as described in section File uploads.

Create a contact

PUT /ajax/contacts?action=new

Parameters:

  • session – A session ID previously obtained from the login module.

Request body: Contact object as described in Common object data and Detailed contact data. The field id is not included.

Response: A json objekt with attribute id of the newly created contact.

To add some contact image the PUT command must be replaced with a POST command and all data must be provided within a multipart/form-data body. The normal request body must be placed into a form field named json while the image file must be placed in a file field named file. The response is then an HTML page as described in section File uploads.

Delete a contact

PUT /ajax/contacts?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the deleted contacts.

Request body: An object with the fields “id” and “folder”.

Delete contacts (since v6.22)

PUT /ajax/contacts?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the deleted contacts.

Request body: An array of objects with the fields “id” and “folder”.

Search contacts

PUT /ajax/contacts?action=search

Parameters:

  • session – A session ID previously obtained from the login module.
  • columns – The requested fields
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified. In case of use of column 609 (use count depending order for collected contacts with global address book) the parameter "order" ist NOT necessary and will be ignored.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • collation (preliminary, since 6.20) – allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter sort should be set for this to work.

Request body: An Object as described in Search contacts.

Search contacts
Name Type Value
pattern String Search pattern to find contacts. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves. Matching is performed against any substring of the field display_name.
startletter String Search contacts with the given startletter. If this field is present, the pattern is matched against the contact field which is specified by the property contact_first_letter_field on the server (default: last name). Otherwise, the pattern is matched against the display name.
folder Array of Number If a list of folder identifiers or at least a single folder identifier is given, only in that folders will be searched for contacts. This paramenter is optional but searching in all contact folders that are viewable and where objects can be read in is more expensive on that database than searching in a dedicated number of them. The possibility to provide here an array of folder identifier has been added with 6.10.

Alternative request body: An Object as described in Search contacts alternative.

Search contacts alternative
Name Type Value
last_name String Searches contacts where the last name match with the given last name.
first_name String Searches contacts where the first name match with the given first name.
display_name String Searches contacts where the display name match with the given display name.
email1 String Searches contacts where the email1 address match with the given search pattern. (requires version >= 6.12)
email2 String Searches contacts where the email2 address match with the given search pattern. (requires version >= 6.12)
email3 String Searches contacts where the email3 address match with the given search pattern. (requires version >= 6.12)
company String Searches contacts where the company match with the given search pattern. (requires version >= 6.12)
categories String Searches contacts where the categories match with the given search pattern.
orSearch Boolean If set to true, a contact is returned if any specified pattern matches at the start of the corresponding field. Otherwise, a contact is returned if all specified patterns match any substring of the corresponding field.
emailAutoComplete Boolean If set to true, results are guaranteed to contain at least one email adress and the search is performed as if orSearch were set to true. The actual value of orSearch is ignored.
exactMatch Boolean If set to true, contacts are returned where the specified patterns match the corresponding fields exactly. Otherwise, a 'startsWith' or 'substring' comparison is used based on the 'orSearch' parameter. (requires version > 6.22.1)

Response: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Search contacts by filter (since 6.20)

PUT /ajax/contacts?action=advancedSearch

Parameters:

  • session – A session ID previously obtained from the login module.
  • columns – The requested fields
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • collation (preliminary, since 6.20) – allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter sort should be set for this to work.

Request body: An Object as described in Search Filter

Response: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Search contacts by anniversary (Since 6.22.1, Preliminary)

Find contacts whose anniversary falls into a timerange.

GET /ajax/contacts?action=anniversaries

Parameters:

  • session – A session ID previously obtained from the login module.
  • start – The lower (inclusive) limit of the requested time-range.
  • end – The upper (exclusive) limit of the requested time-range.
  • columns – The requested fields.
  • folder (optional) – Object ID of the parent folder that is searched. If not set, all visible folders are used.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If not specified, the results are sorted ascending by their anniversary in the supplied timerange. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • collation (optional) – Allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter sort should be set for this to work.

Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Search contacts by birthday (Since 6.22.1, Preliminary)

Find contacts whose birthday falls into a timerange.

GET /ajax/contacts?action=birthdays

Parameters:

  • session – A session ID previously obtained from the login module.
  • start – The lower (inclusive) limit of the requested time-range.
  • end – The upper (exclusive) limit of the requested time-range.
  • columns – The requested fields.
  • folder (optional) – Object ID of the parent folder that is searched. If not set, all visible folders are used.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If not specified, the results are sorted ascending by their birthday in the supplied timerange. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • collation (optional) – Allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter sort should be set for this to work.

Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Auto-complete contacts (Since 7.6.1, Preliminary)

Find contacts based on a prefix, usually used to auto-complete e-mail recipients while the user is typing.

GET /ajax/contacts?action=autocomplete

Parameters:

  • session – A session ID previously obtained from the login module.
  • query – The query to search for.
  • folder (optional) – Object ID of the parent folder that is searched. If not set, all visible folders are used.
  • email (optional) – Whether to only include contacts with at least one e-mail address. Defaults to "true".
  • columns – The requested fields.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified. Since 7.8.1: If this parameter is missing, response is sorted by a user-specific use count of contacts, ID of contacts' parent folder and display name.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is
  • collation (optional) – Allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter sort should be set for this to work.
  • left_hand_limit (optional) – A positive integer number to specify the "left-hand" limit of the range to return.
  • right_hand_limit (optional) – A positive integer number to specify the "right-hand" limit of the range to return.

Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Module "calendar"

The calendar module is used to access calendar data.

Get all appointments

GET /ajax/calendar?action=all

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder (optional) – Object ID of the folder, whose contents are queried. If not specified, defaults to all calendar folders.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in Common object data, Detailed task and appointment data and Detailed appointment data.
  • start – Lower inclusive limit of the queried range as a Date. Only appointments which start on or after this date are returned.
  • end – Upper exclusive limit of the queried range as a Date. Only appointments which end before this date are returned.
  • recurrence_master – Extract the recurrence to several appointments. The default value is false so every appointment of the recurrence will be calculated.
  • showPrivate (optional) – only works in shared folders: When enabled, shows private appointments of the folder owner. Such appointments are anonymized by stripping away all information except start date, end date and recurrence information (since 6.18)

Response with timestamp: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Appointment sequencies are broken up into individual appointments and each occurrence of a sequence in the requested range is returned separately. The appointments are sorted in ascending order by the field start_date.

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:
1 reserved
2 temporary
3 absent
4 free
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.

Get appointment information

GET /ajax/calendar?action=has

Parameters:

  • session – A session ID previously obtained from the login module.
  • start – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.
  • end – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.

Response is an array of booleans. Array length is the number of days. Each entry in the array corresponds with one day in the range that was queried, explaining whether there is an appointment on this day or not.

Get a list of appointments

PUT /ajax/calendar?action=list

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 appointments are defined in Common object data, Detailed task and appointment data and Detailed appointment data.
  • recurrence_master – Extract the recurrence to several appointments. The default value is false so every appointment of the recurrence will be calculated.

Request body: An array with full object IDs (folder, id and optionally either recurrence_position or recurrence_date_position) of requested appointments.

Response with timestamp: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Full identifier for an appointment
Name Type Value
id String Object ID
pos Number Value of the field recurrence_position, if present in the appointment.

Get updated appointments

GET /ajax/calendar?action=updates

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried. That parameter may be absent in case ignore is set to "deleted", which means all accessible calendar folders are considered. If ignore is not set to "deleted", that parameter is mandatory.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in Common object data, Detailed task and appointment data and Detailed appointment data.
  • timestamp – Timestamp of the last update of the requested appointments.
  • start – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.
    This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (folder not specified)
  • end – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.
    This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (folder not specified)
  • ignore (mandatory - should be set to "deleted") (deprecated) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.
  • recurrence_master – Extract the recurrence to several appointments. The default value is false so every appointment of the recurrence will be calculated.
  • showPrivate (optional) – only works in shared folders: When enabled, shows private appointments of the folder owner. Such appointments are anonymized by stripping away all information except start date, end date and recurrence information (since 6.18)

Response with timestamp: An array with new, modified and deleted appointments. New and modified appointments are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted appointments (should the ignore parameter be ever implemented) would be identified by objects described in Full identifier for an appointment instead of arrays. Appointment sequencies are broken up into individual appointments and each modified occurrence of a sequence in the requested range is returned separately. The appointments are sorted in ascending order by the field start_date.

Get an appointment

GET /ajax/calendar?action=get

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the requested appointment.
  • folder – Folder ID of the requested appointment.
  • recurrence_position (optional) – Recurrence Position requested appointment.

Response with timestamp: An object containing all data of the requested appointment. The fields of the object are listed in Common object data, Detailed task and appointment data and Detailed appointment data. The field id is not included.

Update an appointment

PUT /ajax/calendar?action=update

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the updated appointment.
  • folder - Object ID of the appointment's folder.
  • timestamp – Timestamp of the updated appointment. If the appointment was modified after the specified timestamp, then the update must fail.

Request body: Appointment object as described in Common object data, Detailed task and appointment data and Detailed appointment data. The field recurrence_id is always present if it is present in the original appointment. The field recurrence_position is present if it is present in the original appointment and only this single appointment should be modified. The field id is not present because it is already included as a parameter. Other fields are present only if modified.

Create an appointment

PUT /ajax/calendar?action=new

Parameters:

  • session – A session ID previously obtained from the login module.

Request body: Appointment object as described in Common object data, Detailed task and appointment data and Detailed appointment data. The field id is not present.

Response: If the appointment was created successfully, an object with the attribute id of the newly created appointment. If the appointment could not be created due to conflicts, the response body is an object with the field conflicts, which is an array of appointment objects which caused the conflict. Each appointment object which represents a resource conflict contains an additional field hard_conflict with the Boolean value true. If the user does not have read access to a conflicting appointment, only the fields id, start_date, end_date, shown_as and participants are present and the field participants contains only the participants which caused the conflict.

Delete an appointment

PUT /ajax/calendar?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the deleted appointments.

Request body: The appointment object to delete. The fields for the object are described in Full identifier for an appointment.

Response: An array of objects identifying the appointments which were modified after the specified timestamp and were therefore not deleted. The fields of each object are described in Full identifier for an appointment.

Delete appointments (since v6.22)

PUT /ajax/calendar?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the deleted appointments.

Request body: An array of appointment objects to delete. The fields for the object are described in Full identifier for an appointment.

Response: An array of objects identifying the appointments which were modified after the specified timestamp and were therefore not deleted. The fields of each object are described in Full identifier for an appointment.

Confirm appointment

PUT /ajax/calendar?action=confirm

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the appointment to confirm.
  • occurrence – The numeric identifier of the occurrence to which the confirmation applies (in case "id" denotes a series appointment). Available with v7.6.0
  • folder – ID of the folder through which the appointment is accessed.
  • timestamp – Timestamp of the last update of the to confirmed appointment.

Request body: An object with the fields "confirmation", "confirmmessage" and "id" (optional) as described in User participant object.

Response: Nothing, except the standard response object with empty data, the timestamp of the confirmed and thereby updated task, and maybe errors.

Free & Busy

GET /ajax/calendar?action=freebusy

Parameters:

  • session – A session ID previously obtained from the login module.
  • id - Internal user id. Must be obtained from the contact module.
  • type - Constant for user or resource (1 for users, 3 for resources)
  • start – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.
  • end – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.

Response: An array of objects identifying the appointments which lie between start and end as described.
This objects consist of:

Name Type Value
shown_as Number Describes, how this appointment appears in availability queries:
1 reserved
2 temporary
3 absent
4 free
start_date Date or Time see Detailed task and appointment data
end_date Date or Time see Detailed task and appointment data
id String Object ID
folder_id String Folder ID. Only set, if the user has the right to see the object. (added 2009-08-18/6.12)
full_time Boolean True if the appointment is a whole day appointment, not present otherwise.

Search appointments

PUT /ajax/calendar?action=search

Parameters:

  • session – A session ID previously obtained from the login module.
  • columns – The requested fields

Request body: An Object as described in Search appointments.

Search appointments
Name Type Value
pattern String Search pattern to find appointments. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves.
startletter String Search appointments with the given starting letter.

Request body: An Object as described in Search appointments.

Response: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Get new appointments

GET /ajax/calendar?action=newappointments

Parameters:

  • session – A session ID previously obtained from the login module.
  • columns – The requested fields
  • start – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.
  • end – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified and holds a column number, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • limit – limits the number of returned object to the given value.

Response: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Resolve UID

GET /ajax/calendar?action=resolveuid

Parameters

  • session – A session ID previously obtained from the login module.
  • uid – The UID to be resolved.

Response: An object object with the field "id" containing the ox-object id, if existing, an error message otherwise.

Get all Change Exceptions (Since v7.2.0)

GET /ajax/calendar?action=getChangeExceptions

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object id of the appointment series.
  • folder – Folder ID of the requested appointments.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier.

Response with timestamp: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Module "mail"

The mail module is used to access mail data.

When mails are stored on an IMAP server, some functionality is not available due to restrictions of the IMAP protocol. Such functionality is marked with "not IMAP".

Get mail count

GET /ajax/mail?action=count

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder whose mail count is queried

Response (not IMAP: with timestamp): An integer value representing folder's mail count

Get all mails

GET /ajax/mail?action=all

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in Detailed mail data.
  • sort (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • left_hand_limit - A positive integer number to specify the "left-hand" limit of the range to return
  • right_hand_limit - A positive integer number to specify the "right-hand" limit of the range to return
  • limit - A positive integer number to specify how many items shall be returned according to given sorting; overrides left_hand_limit/right_hand_limit parameters and is equal to left_hand_limit=0 and right_hand_limit=<limit>

Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

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 following values:
1 answered
2 deleted
4 draft
8 flagged
16 recent
32 seen
64 user
128 spam
256 forwarded

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:
0 No priority
5 Very Low
4 Low
3 Normal
2 High
1 Very High
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).
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.

Get all mail conversations (since v7.x)

GET /ajax/mail?action=threadedAll

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in Detailed mail data.
  • sort (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified. Note: Applies only to root-level messages.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified. Note: Applies only to root-level messages.
  • includeSent - A boolean value to signal that conversations also include messages taken from special "sent" aka "sent items" folder
  • left_hand_limit - A positive integer number to specify the "left-hand" limit of the range to return. Note: Applies only to root-level messages.
  • right_hand_limit - A positive integer number to specify the "right-hand" limit of the range to return. Note: Applies only to root-level messages.
  • limit - A positive integer number to specify how many items shall be returned according to given sorting; overrides left_hand_limit/right_hand_limit parameters and is equal to left_hand_limit=0 and right_hand_limit=<limit>. Note: Applies only to root-level messages.

Response (not IMAP: with timestamp): An JSON array consisting of JSON objects, each representing a conversation's root message along with its message thread. The root message's JSON object is filled according to specified columns and is enhanced by special "thread" JSON field representing the full message thread (including the root message itself). The "thread" JSON field is a JSON array of JSON objects; each representing a message in the conversation sorted by time-line, also filled with specified columns. E.g.

{
   "flags":32,
   "color_label":0,
   "unreadCount":0,
   "id":"263852",
   "folder_id":"default0/INBOX",
   "thread":[
      {
         "id":"263852",
         "folder_id":"default0/INBOX",
         "flags":32,
         "color_label":0
      },
      {
         "id":"263853",
         "folder_id":"default0/INBOX",
         "flags":32,
         "color_label":0
      },
      {
         "id":"26323",
         "folder_id":"default0/Sent",
         "flags":32,
         "color_label":0
      },
      {
         "id":"263854",
         "folder_id":"default0/INBOX",
         "flags":32,
         "color_label":0
      }
   ]
}

Search mails

PUT /ajax/mail?action=search

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in Detailed mail data.
  • sort (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.

Request Body: A JSON array of JSON objects each containing the search field and its search pattern: e.g.: [{"col": 612, "pattern": "Joe"}, {"col": 614, "pattern": "Tuesday"}] Supported values for col are 603 to 607 (from, to, cc, bcc and subject) and -1 for full text search.

Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.


Search mails (alternative)

PUT /ajax/mail?action=search

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for mails are defined in Detailed mail data.
  • sort (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.

Request Body: A JSON object containing filters. {"filter":[search term]}

This section describes the syntax of the optional JSON object representing the search term. In general the structure of a search term is in prefix notation; meaning the operator is written before its operands:

[">", 5, 2]

The available operators are:

  • Comparison operators ">", "<", "=", "<=", ">=", "<>"
  • logic operators "not", "and", "or"

Comparison operators have exactly two operands. Each operand can be either a field name or a constant. A field name is an object with the member "field" specifying the field name, e.g. { field: "from" }. The available field names are from, to, cc, bcc, subject, received_date, sent_date, size,flags, content, content_type, disp and priority as defined in Detailed mail data. Primitive JSON types are interpreted as constants. Arrays are not valid operands for comparison 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.

   {"filter":
       ["or",
           ["and",
               ["=", {"field":"to"}, "test1@example.org"],
               ["not",
                   ["=", {"field":"from"}, "test2@example.org"]
               ],
               [">", {"field":"received_date"}, "1458063382000"]
           ],
           ["=", {"field":"subject"}, "TestSubject"]
       ]
   }

Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Get a list of mails

PUT /ajax/mail?action=list

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 mails are defined in Detailed mail data.
  • headers - (preliminary) A comma-separated list of header names. Each name requests denoted header from each mail

Request body: An array with one object for each requested mail. Each object contains the fields folder and id.

Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter followed by requested headers.

Copy mails

PUT /ajax/mail?action=copy

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the requested mail.
  • folder – Object ID of the source folder.

Request Body: A JSON object containing the id of the destination folder inside the "folder_id" field: e.g.: {"folder_id": 1376}

Response: A JSON array containing the ID of the copied mail

Move mails

PUT /ajax/mail?action=update

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the requested mail.
  • folder – Object ID of the source folder.

Request Body: A JSON object containing the id of the destination folder inside the "folder_id" field: e.g.: {"folder_id": 1376}


Response: A JSON array containing the ID of the moved mail

Update mails

PUT /ajax/mail?action=update

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the requested mail.
  • message_id – (Preliminary) The value of "Message-Id" header of the requested mail. This parameter is a substitute for "id" parameter.
  • folder – Object ID of the folder.

Note: If neither parameter "id" nor parameter "message_id" is specified, all folder's messages are updated accordingly. Available with v6.20.

Request Body: A JSON object which carries the new values that ought to be applied to mail as described in Update mail or Update mail extended (available with SP6 v6.10).

Response: A JSON object containing the Object ID of the updated mail and its folder.

Update mail
Name Type Value
color_label Number The color number between 0 and 10.
flags Number A set of flags to add or remove. Note: Flags for "recent" (8) and "user" (64) are ignored.
value Boolean true to add the flags specified by flags (logical OR), false to remove them (logical AND with the inverted value).


Update mail extended (available with SP6 v6.10)
Name Type Value
set_flags Number A set of flags to add. Note: Flags for "recent" (8) and "user" (64) are ignored.
clear_flags Number A set of flags to remove. Note: Flags for "recent" (8) and "user" (64) are ignored.


Mark all mails as seen (available with v7.6.0)

PUT /ajax/mail?action=all_seen

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder.

Request Body: n.a.

Response: true

Not IMAP: Get updated mails

GET /ajax/mail?action=updates

Parameters:

  • session – A session ID previously obtained from the login module.

Response: Just an empty JSON array is going to be returned since this action cannot be applied to IMAP.

Get a mail

GET /ajax/mail?action=get

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the requested mail.
  • message_id – (Preliminary) The value of "Message-Id" header of the requested mail. This parameter is a substitute for "id" parameter.
  • folder – Object ID of the mail's folder.
  • edit (optional) – 1 indicates that this request should fill the message compose dialog to edit a message and thus display-specific date is going to be withheld.
  • hdr (optional) – 1 to let the response contain only the (formatted) message headers as plain text
  • src (optional) – 1 to let the response contain the complete message source as plain text
  • save (optional) – 1 to write the complete message source to output stream. NOTE: This parameter will only be used if parameter src is set to 1.
  • view (optional - available with SP4)
    • "raw" returns the content as it is, meaning no preparation are performed and thus no guarantee for safe contents is given (available with SP6 v6.10).
    • "text" forces the server to deliver a text-only version of the requested mail's body, even if content is HTML.
    • "textNoHtmlAttach" is the same as "text", but does not deliver the HTML part as attachment in case of multipart/alternative content.
    • "html" to allow a possible HTML mail body being transferred as it is (but white-list filter applied).
    • "noimg" to allow a possible HTML content being transferred but without original image src attributes which references external images: Can be used to prevent loading external linked images (spam privacy protection).
    • NOTE: if set, the corresponding gui config setting will be ignored.
  • unseen (optional) – "1" or "true" to leave an unseen mail as unseen although its content is requested
  • max_size (optional - available since v7.6.1) A positive integer number (greater than 10000) to specify how many characters of the message content will be returned. If the number is smaller than 10000 the value will be ignored and 10000 used.
  • attach_src (optional - available since v7.6.1) 1 to let the JSON mail representation being extended by "source" field containing the mail raw RFC822 source data

Response (not IMAP: with timestamp): An JSON object containing all data of the requested mail. The fields of the object are listed in Detailed mail data. The fields id and attachment are not included. NOTE: Of course response is not a JSON object if either parameter hdr or parameter src are set to "1". Then the response contains plain text. Moreover if optional parameter save is set to "1" the complete message source is going to be directly written to output stream to open browser's save dialog.

Get multiple mails as a ZIP file

GET /ajax/mail?action=zip_messages

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – The folder identifier.
  • id – A comma-separated list of Object IDs of the requested mails

Response body: The raw byte data of the ZIP file.

Get a mail attachment

GET /ajax/mail?action=attachment

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – The folder identifier.
  • id – Object ID of the mail which contains the attachment.
  • attachment – ID of the requested attachment OR
  • cid – Value of header 'Content-ID' of the requested attachment
  • save – 1 overwrites the defined mimetype for this attachment to force the download dialog, otherwise 0.
  • filter (optional) – 1 to apply HTML white-list filter rules if and only if requested attachment is of MIME type text/htm* AND parameter save is set to 0.

Response body: The raw byte data of the document. The response type for the HTTP Request is set accordingly to the defined mimetype for this attachment, except the parameter save is set to 1.

Get multiple mail attachments as a ZIP file

GET /ajax/mail?action=zip_attachments

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – The folder identifier.
  • id – Object ID of the mail which contains the attachments.
  • attachment – A comma-separated list of IDs of the requested attachments

Response body: The raw byte data of the ZIP file.

Send a mail

POST /ajax/mail?action=new

Parameters:

  • session – A session ID previously obtained from the login module.
  • lineWrapAfter – An integer value specifying the line-wrap setting (only effective for plain-text content); if absent the setting is taken from user's mail settings. Available with v7.8.1.

Request Body: This method uses the encoding multipart/form-data or multipart/mixed.

  • The form filed json_0 contains the rudimentary mail as JSON object as described in Detailed mail data with just its message body (as html content) defined in nested JSON array "attachments" and its header data (from, to, subject, etc.). The field "content_type" defines whether the mail ought to be sent as plain text ("text/plain"), as html ("text/html") or as multipart/alternative ("ALTERNATIVE"). Sending a mail requires some special fields inside JSON mail object. The field "infostore_ids" defines a JSON array of infostore document ID(s) that ought to be appended to this mail as attachments. The field "msgref" indicates the ID of the referenced original mail. Moreover the field "sendtype" indicates the type of the message:
    • 0 - A normal new mail (optional)
    • 1 - A reply mail. The field "msgref" must be present
    • 2 - A forward mail. The field "msgref" must be present
    • 3 - A draft edit operation. The field "msgref" must be present in order to delete previous draft message since e.g. IMAP does not support changing/replacing a message but requires a delete-and-insert sequence
    • 4 - Transport of a draft mail. The field "msgref" must be present
    • 6 - This type signals that user intends to send out a saved draft message and expects the draft message (referenced by "msgref" field) being deleted after successful transport

Example of a normal new mail which appends user's VCard and requests a read receipt from receiver:

Content-Disposition: form-data; name="json_0"....{"from":"\u0022Muster, Karl\u0022 <karl.muster@somewhere.com>","to":"someone@somewhere.com","cc":"","bcc":"", "subject":"Mail Subject","priority":"3","disp_notification_to":true,"vcard":1, "attachments":[{"content_type":"ALTERNATIVE","content":"Simple Mail Text!<br><br>\u000a\u000a"}]}

  • The request accepts file fields in upload form that denote referenced files that are going to be appended as attachments
  • For "text/plain" mail bodies, the JSON boolean field "raw" may be specified inside the body's JSON representation to signal that the text content shall be kept as-is; meaning to keep all formatting intact

Attach data sources

Moreover the JSON representation may contain data sources which should be appended as file attachments to the mail. Then the mail contains the "datasources" key which is expected to be a JSON array of data source descriptions.

A data source description follows the conversion specification.

For example to attach a file through an URL the field looks like this (available with v6.18.2):

{
 "from": "someone@somewhere.com,
 ...
 "datasources"
 [
  {
   "identifier": "com.openexchange.url.mail.attachment",
   "args":
    {
     "url": <url-string>,
     "timeout": <optional-timeout-millis-int, default is 2500msec>,
     "contentType": <optional-content-type-string>,
     "charset": <optional-charset-string>,
     "size": <optional-size-int>,
     "disposition": <optional-disposition-string>,
     "fileName": <optional-file-name-string>,
    }
  }
 ]
}

Response: Object ID of the newly created mail.

Send/Save mail as MIME data block (RFC822) (added in SP5)

PUT /ajax/mail?action=new

Parameters:

  • session - A session ID previously obtained from the login module.
  • folder (optional) - In case the mail should not be sent out, but saved in a specific folder, the "folder" parameter can be used. If the mail should be sent out to the recipient, the "folder" parameter must not be included and the mail is stored in the folder "Sent Items". Example "folder=default.INBOX/Testfolder"
  • flags (optional) - In case the mail should be stored with status "read" (e.g. mail has been read already in the client inbox), the parameter "flags" has to be included. If no "folder" parameter is specified, this parameter must not be included. For infos about mail flags see Detailed mail data spec.

Request Body: The MIME Data Block

Response: Object ID of the newly created/moved mail.

Import of mails as MIME data block (RFC822) (added with 6.18)

This request can be used to store a single or a lot of mails in the OX mail storage backend. This action should be used instead of action=new because it is faster and tolerant to 8bit encoded emails.

POST /ajax/mail?action=import

Parameters:

  • session - A session ID previously obtained from the login module.
  • folder - For the import this parameter is required to specify the folder into that the emails should be imported. Example "folder=default.INBOX/Testfolder"
  • flags (optional) - In case the mail should be stored with status "read" (e.g. mail has been read already in the client inbox), the parameter "flags" has to be included. For infos about mail flags see Detailed mail data spec.
  • force (optional) - If this parameter is set to true, the server skips checking the valid From-address

Request Body: A multipart/form-data with a single or multiple file parts each having a different name and containing the RFC822 encoded email as binary data like in a file upload.

Response: A JSON object containing the folder identifier and the object identifier of the imported mail or a JSON array of those JSON objects if multiple mails are imported.

Reply/Forward a mail

GET /ajax/mail?action=reply
GET /ajax/mail?action=replyall
GET /ajax/mail?action=forward

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the requested Message.
  • folder - Object ID of the folder, whose contents are queried.
  • view (optional - available with SP6) - "text" forces the server to deliver a text-only version of the requested mail's body, even if content is HTML. "html" to allow a possible HTML mail body being transferred as it is (but white-list filter applied).NOTE: if set, the corresponding gui config setting will be ignored.
  • setFrom (optional - available since v7.6.0) A flag ("true"/"false") that signals if "From" header shall be pre-selected according to a suitable recipient address that matches one of user's E-Mail address aliases; only supported for /ajax/mail?action=replyall and /ajax/mail?action=reply
  • max_size (optional - available since v7.6.1) A positive integer number (greater than 10000) to specify how many characters of the message content will be returned. If the number is smaller than 10000 the value will be ignored and 10000 used.

Response (not IMAP: with timestamp): An object containing all data of the requested mail. The fields of the object are listed in Detailed mail data. The fields id and attachment are not included.

Delete mails

PUT /ajax/mail?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • Not IMAP: timestamp – Timestamp of the last update of the deleted mails.

Request body: An array of objects providing folder IDs and object IDs of the deleted mails.
[
 { "folder":"default0/INBOX", "id":"123" }
 ...
 { "folder":"default0/MyFolder", "id":"134" }
]

Not IMAP: Response: An array with object IDs of mails which were modified after the specified timestamp and were therefore not deleted.

Clear mail folder(s)

PUT /ajax/mail?action=clear

Parameters:

  • session – A session ID previously obtained from the login module.
  • Not IMAP: timestamp – Timestamp of the last update of the deleted mails.

Request body: An array with IDs of the mail folders to clear

Response: An array with IDs of mail folder that could not be cleared; meaning the response body is an empty JSON array if everything went well.

Acknowledge receipt

PUT /ajax/mail?action=receipt_ack

Parameters:

  • session – A session ID previously obtained from the login module.

Request Body: A JSON object containing the "from address", the id of the folder and the mail id: e.g.: {"from":"mymail@domain.com","folder":"default0/INBOX","id":"1234"}

Response: A JSON object with an empty data field if everything went well or a JSON object containing the error information.

Module "groups"

The group module allows to query available groups. It is mainly used by the dialog for the selection of participants.

Get a group

GET /ajax/group?action=get

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – The group id.

Response: A group object as described in Group data.

List groups

PUT /ajax/group?action=list

Parameters:

  • session – A session ID previously obtained from the login module.

Request body: An array with group identifiers.

Response: An array of group objects as described in Group data.

Search for groups

PUT /ajax/group?action=search

Parameters:

  • session – A session ID previously obtained from the login module.

Request body: An object with search parameters as described in Group search.

Group search
Name Type Value
pattern String Search pattern to find groups. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves.

Response with timestamp: An array of group objects as described in Group data.

Group data
Name Type Value
id Number ID
display_name String Display name
name String Name with character restrictions
members Array The array contains identifier of users that are member of the group.

Create a group

introduced 2008-06-12

PUT /ajax/group?action=new

Parameters:

  • session – A session ID previously obtained from the login module.

Request body: Group object as described in Group data. The field id is not present.

Response: A json objekt with attribute id of the newly created group.

Delete a group

introduced 2008-06-12

PUT /ajax/group?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the group to delete.

Request body: An object with the field “id” containing the unique identifier of the group.

Response: An empty json array if the group was deleted successfully.

Change a group

introduced 2008-06-12

PUT /ajax/group?action=update

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the group to update.
  • timestamp – Time stamp of the group to update. If the group was modified after the specified time stamp, then the update must fail.

Request body: Group object as described in Group data. Only modified fields are present and the field id is omitted.

Get updates (since v6.18.1)

introduced 2010-09-13

GET /ajax/group?action=updates

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the requested groups.

Response with timestamp: An array with new, modified and deleted groups. New, modified and deleted groups are represented by JSON objects as described in Group data.

Module "resource"

The resource module allows to query available resources. It is mainly used by the dialog for the selection of participants.

Get all resources

GET /ajax/resource?action=all

Parameters:

  • session – A session ID previously obtained from the login module.

Response: An array of resource identifier.

List resources

PUT /ajax/resource?action=list

Parameters:

  • session – A session ID previously obtained from the login module.


Request body: An array with resources ids.

Response: An array of resource objects as described in Resource response.

Get a resource

GET /ajax/resource?action=get

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – The resource id.

Response: An array of resource objects as described in Resource response.

Search for resources

PUT /ajax/resource?action=search

Parameters:

  • session – A session ID previously obtained from the login module.

Request body: An object with search parameters as described in Participant search.

Participant search
Name Type Value
pattern String Search pattern to find resources. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves.

Response: An array of resource objects as described in Resource response.

Resource Response
Name Type Value
id Number ID
display_name String Display name
name String internal name
mailaddress String email address
availability Boolean can be false to mark the resource currently unavailable
description String description of the resource
last_modified Time Date and time of the last modification.
last_modified_utc Timestamp Date and time of the last modification.

Create a resource

PUT /ajax/resource?action=new

Parameters:

  • session – A session ID previously obtained from the login module.

Request body: Resource object as described in Resource response. The field id is not present.

Response: An object with attribute id of the newly created resource.

Delete a resource

PUT /ajax/resource?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the resource to delete.

Request body: An object with the field “id” containing the unique identifier of the resource.

Response: An empty json array if the resource was deleted successfully.

Delete resources (since v6.22)

PUT /ajax/resource?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the resource to delete.

Request body: An array of objects with the field “id” containing the unique identifier of the resource.

Response: An empty json array if the resources were deleted successfully.

Change a resource

PUT /ajax/resource?action=update

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the resource to update.
  • timestamp – Time stamp of the resource to update. If the resource was modified after the specified time stamp, then the update must fail.

Request body: Resource object as described in Resource response. Only modified fields are present and the field id is omitted.

Get updates (since v6.18.1)

introduced 2010-09-13

GET /ajax/resource?action=updates

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the requested resources.

Response with timestamp: An array with new, modified and deleted resources. New, modified and deleted resources are represented by JSON objects as described in Resource response.

Module "infostore" or "Filestore" or "Files" or "Drive"

This module has been renamed quite often. Whatever its name, it combines the knowledge database, bookmarks and document storage.

Get all infoitems

GET /ajax/infostore?action=all

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for infoitems are defined in Common object data and Detailed infoitem data.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.

Response with timestamp: An array with infoitem data. Each array element describes one infoitem and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

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.
Object Permission flags
Bits Value
0 The numerical value indicating no object permissions.
1 The numerical value indicating read object permissions.
2 The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).

Get a list of infoitems

PUT /ajax/infostore?action=list

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 infoitems are defined in Common object data and Detailed infoitem data.

Request body: An array with object IDs of requested infoitems.

Response with timestamp: An array with infoitem data. Each array element describes one infoitem and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Get updated infoitems

GET /ajax/infostore?action=updates

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for infoitems are defined in Common object data and Detailed infoitem data.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • timestamp – Timestamp of the last update of the requested infoitems.
  • ignore (optional) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.

Response with timestamp: An array with new, modified and deleted infoitems. New and modified infoitems are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted infoitems (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 an infoitem

GET /ajax/infostore?action=get

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the requested infoitem.
  • version (optional) – If present the infoitem data describes the given version. Otherwise the current version is returned

Response with timestamp: An object containing all data of the requested infoitem. The fields of the object are listed in Common object data and Detailed infoitem data. The field id is not included.

Search infoitems

PUT /ajax/infostore?action=search

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder (optional) – The folder ID to restrict the search to. If not specified, all folders are searched.
  • columns – The requested fields as per tables Common object data and Detailed infoitem data.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • start (optional) – The start index (inclusive) in the ordered search, that is requested.
  • end (optional) – The last index (inclusive) from the ordered search, that is requested.

Request body: The search pattern string in a JSON object named "pattern".

Get an infoitem document

GET /ajax/infostore/[filename]?action=document

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the requested infoitem.
  • folder – Object ID of the infoitem's folder.
  • version (optional) – If present the infoitem data describes the given version. Otherwise the current version is returned
  • content_type(optional) – If present the response declares the given content_type in the Content-Type header.

Response body: The raw byte data of the document. The response type for the HTTP Request is set accordingly to the defined mimetype for this infoitem or the content_type given.

Note: The Filename may be added to the customary infostore path to suggest a filename to a Save-As dialog.

Get a ZIP archive containing the infoitems of a denoted folder (available with v7.6.1)

GET /ajax/infostore/[filename]?action=zipfolder

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the infoitem's folder.
  • recursivetrue to also include subfolders and their infoitems respectively; otherwise false to only consider the infoitems of specified folder

Response body: The raw byte data of the ZIP archive. The response type for the HTTP Request is set to application/zip.

Get all versions

GET /ajax/infostore?action=versions

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the infoitem whose versions are requested.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for infoitems are defined in Common object data and Detailed infoitem data.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.

Response with timestamp: An array with infoitem data. Each array element describes one infoitem and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. The timestamp is the timestamp relating to the requested infostore item.

Check if file name is valid (since 7.8.1, Preliminary)

GET /ajax/infostore?action=checkname

Parameters:

  • session – A session ID previously obtained from the login module.
  • name – Name of the file to check.

Response: An empty JSON object when file name is valid.

Get multiple documents as a ZIP archive (available with v7.4.0)

GET /ajax/infostore?action=zipdocuments

Parameters:

  • session – A session ID previously obtained from the login module.
  • body – A URL-encoded JSON array; see below for details

Parameter body: A JSON array of JSON object tuples specifying the documents' versions to include in the requested ZIP archive; e.g

[{"id":"61820","folder":"70303"},{"id":"61821","folder":"70303", "version": "1"}]

The field "version" is optional; if missing it refers to latest/current version.
So, a valid parameter would look like:

...&body=%5B%7B%22id%22%3A%2261820%22%2C%22folder%22%3A%2270303%22%7D%2C%7B%22id%22%3A%2261821%22%2C%22folder%22%3A%2270303%22%2C%22version%22%3A%221%22%7D%5D

Response: The download offer for the requested ZIP archive containing specified document versions

Move one or more infoitems via PUT

PUT /ajax/infostore?action=move

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – ID of the destination folder.

Request body: A JSON array consisting of JSON objects each referencing to an existing infoitem that is supposed to be moved to the destination folder

[
  {"id":"31841/36639", "folder":"31841"},
  {"id":"31841/36641", "folder":"31841"}
]

Response: A JSON array consisting of those identifiers that could not be moved (due to a conflict) or an empty JSON array if everything went fine

Update an infoitem via PUT

PUT /ajax/infostore?action=update

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the updated infoitem.
  • timestamp – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.

Request body: Infoitem object as described in Common object data and Detailed infoitem data. Only modified fields are present. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:

{
  "file":{
    "object_permissions":[
      {
        "bits":403710016,
        "entity":84,
        "group":false
      },
      {
        "type":"guest",
        "email_address":"john.doe@example.com",
        "display_name":"John Doe",
        "bits":1
      }
    ]
  },
  "notification":{
    "transport":"mail",
    "message":"Hi!\nHave a look at this!"
  }
}

Update an infoitem via POST

POST /ajax/infostore?action=update

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the updated infoitem.
  • timestamp – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.
  • offset – Optionally sets the start offset in bytes where to append the data to the document, must be equal to the actual document's length (available with v7.8.1). Only available if the underlying File storage account supports the "RANDOM_FILE_ACCESS" capability.
  • json - Infoitem object as described in Common object data and Detailed infoitem data. Only modified fields are present. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.
  • file – File Metadata as per <input type=”file” />

Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.

Response: The response is sent as a HTML document (see introduction).

Create an infoitem via PUT

PUT /ajax/infostore?action=new

Parameters:

  • session – A session ID previously obtained from the login module.

Request body: Infoitem object as described in Common object data and Detailed infoitem data. The field id is not included. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:

{
  "file":{
    "object_permissions":[
      {
        "bits":403710016,
        "entity":84,
        "group":false
      },
      {
        "type":"guest",
        "email_address":"john.doe@example.com",
        "display_name":"John Doe",
        "bits":1
      }
    ]
  },
  "notification":{
    "transport":"mail",
    "message":"Hi!\nHave a look at this!"
  }
}

Response: Object ID of the newly created infoitem.

Create an infoitem via POST

POST /ajax/infostore?action=new

Parameters:

  • session – A session ID previously obtained from the login module.
  • json - Infoitem object as described in Common object data and Detailed infoitem data. The field id is not included. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.
  • file – File metadata as per <input type=”file” />

Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.

Response: Object ID of the newly created infoitem. The response is sent as a HTML document (see introduction).

Save an attachment in the infostore

PUT /ajax/infostore?action=saveAs

Parameters:

  • session – A session ID previously obtained from the login module.
  • attached – The Object ID of the Object with the attachment
  • folder – The Folder ID of the Object with the attachment
  • module – The Module type of the Object with the attachment.
  • Attachment – The id of the attachement to save.

Request body: Infoitem object as described in Common object data and Detailed infoitem data. The field id is not included. The fields in this infoitem object override values from the attachment. The folder_id must be given. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:

{
  "file":{
    "object_permissions":[
      {
        "bits":403710016,
        "entity":84,
        "group":false
      },
      {
        "type":"guest",
        "email_address":"john.doe@example.com",
        "display_name":"John Doe",
        "bits":1
      }
    ]
  },
  "notification":{
    "transport":"mail",
    "message":"Hi!\nHave a look at this!"
  }
}

Response: Object ID of the newly created infoitem.

Delete infoitems

PUT /ajax/infostore?action=delete

Parameters:

  • session – A session ID previously obtained from the login module.
  • timestamp – Timestamp of the last update of the deleted infoitems.
  • hardDelete - Optional, defaults to \"false\". If set to \"true\", the file is deleted permanently. Otherwise, and if the underlying storage supports a trash folder and the file is not yet located below the trash folder, it is moved to the trash folder.

Request body: An array with objects to delete. The fields for the object are described in Full identifier for an infostore document.

Response: An array with [[]].

Full identifier for an infostore document
Name Type Value
id Number Object ID
folder Number Folder ID

Delete versions of infostore documents

PUT /ajax/infostore?action=detach

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – The ID of the base Object
  • folder – The Folder of the Object
  • timestamp - Timestamp of the infostore object

Request body: A List of arrays with the version numbers of the infoitems to detach.

Response: An array with version numbers that were not deleted.

Note: When the current version of a document is deleted the new current version will be the newest version.

Delete all versions of infostore documents

PUT /ajax/infostore?action=revert

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – The ID of the base Object
  • folder – The Folder of the Object
  • timestamp - Timestamp of the infostore object

Removes all versions of the infostore document leaving only the base object.

Copy an infostore document via PUT

PUT /ajax/infostore?action=copy

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – The ID of the base Object
  • folder – The Folder of the Object
  • timestamp - Timestamp of the infostore object

Request body: Infoitem object as described in Common object data and Detailed infoitem data. Only modified fields are present.

Response: The id of the newly created object

Note: Only the fields (and the file) of the current document will be copied. Those fields present in the request are modified accordingly.

Copy an infostore document via POST

POST /ajax/infostore?action=copy

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the updated infoitem.
  • timestamp – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.
  • json - Infoitem object as described in Common object data and Detailed infoitem data. Only modified fields are present.
  • file – File Metadata as per <input type=”file” />

Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.

Response: The response is sent as a HTML document (see introduction).

Note: Only the fields (and the file) of the current document will be copied. Those fields present in the request are modified accordingly.

Lock an infoitem

GET /ajax/infostore?action=lock

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the infoitem that should be locked.
  • diff (optional) – If present the value is added to the current time on the server (both in ms). The document will be locked until that time. If this parameter is not present, the document will be locked for a duration as configured on the server.

Response with timestamp: Can only include errors.

Unlock an infoitem

GET /ajax/infostore?action=unlock

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the infoitem that should be unlocked.

Response with timestamp: Can only contain errors.

Get shared infoitems (Since 7.8.0, Preliminary)

GET /ajax/infostore?action=shares

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 infoitems are defined in Common object data and Detailed infoitem data.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.

Response: An array with infoitem data. Each array element describes one infoitem and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Notify about shared infoitems (Since 7.8.0, Preliminary)

PUT /ajax/infostore?action=notify

Parameters:

  • session – A session ID previously obtained from the login module.
  • id – Object ID of the shared infoitem to notify about.

Request body: A JSON object providing the JSON array entities, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object notification may be included, inside of which an optional message can be passed (otherwise, some default message is used).

Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.

Module "Attachments"

The Attachment Module allows file attachments to arbitrary objects. An Attachment always belongs to an object (called 'attached') in a certain folder of a certain module.

Get All Attachments for an Object

GET /ajax/attachment?action=all

Parameters:

  • session – A session ID previously obtained from the login module.
  • attached – The Object ID of the Object
  • folder – The Folder ID of the Object
  • module – The Module type of the Object
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for attachment's are defined in Common object data (with only id, created_by and creation_date available) and Attachment object.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.

Response: An array with attachment data. Each array element describes one attachment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Get a list of attachments

PUT /ajax/attachment?action=list

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 attachments are defined in Common object data (with only id, created_by and creation_date available) and Attachment object.
  • attached – The Object ID of the Object
  • folder – The Folder ID of the Object
  • module – The Module type of the Object

Request body: An array of with object IDs of requested tasks.

Response with timestamp: An array with attachment data. Each array element describes one attachment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.

Create an Attachment

POST /ajax/attachment?action=attach

Parameters:

  • session – A session ID previously obtained from the login module.
  • json_[index] – The JSON representation of an attachment object as described in Common object data (with only id, created_by and creation_date available) and Attachment object.
  • file_[index] – The file metadata as per <input type=file /> upload.

Note: The JSON Object and file fields describe the corresponding attachment. For ex.: json_0 contains metadata for file_0, json_1 for file_1 and so on. Indexes start with 0.

Request body: multipart/form-data or multipart/mixed containing the file data of the attached file and the above fields.

Response: HTML page with javascript callback as per introduction. Contains a JSON-Array of ids of the newly created attachments. The order of the ids corresponds to the indexes in the request.

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:
1 Appointment
4 Task
7 Contact
137 Infostore
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).

Delete Attachment

PUT /ajax/attachment?action=detach

Parameters:

  • session – A session ID previously obtained from the login module.
  • attached – The ID of the base Object
  • module – The type of the Object
  • folder – The Folder of the Object

Request body: An array with the ids of the attachments to delete.

Get updated attachments

GET /ajax/attachment?action=updates

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • attached – Object ID of the object to which the attachments are attached.
  • module – Module ID (as per Attachment object) of the attached object.
  • columns – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for attachments are defined in Common object data (with only id, created_by and creation_date available) and Attachment object.
  • sort (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
  • order (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
  • timestamp – Timestamp of the last update of the requested infoitems.

ignore (optional) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.

Response with timestamp: An array with new and deleted attachments for the specified object. New attachments are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted attachments (should the ignore parameter be ever implemented) would be identified by their object IDs as plain numbers, without being part of a nested array.

Get an attachment

GET /ajax/attahment?action=get

Parameters:

  • session – A session ID previously obtained from the login module.
  • folder – Object ID of the folder, whose contents are queried.
  • attached – Object ID of the object to which the attachments are attached.
  • module – Module ID (as per Attachment object) of the attached object.
  • id – Object ID of the requested attachment.

Response with timestamp: An object containing all data of the requested attachment. The fields of the object are listed in