HTTP API
Introduction
This document defines the Open-Xchange HTTP API which is used by the new AJAX GUI. The first chapter describes general definitions and conventions which apply to all server modules. All other chapters describe individual server modules.
Low level protocol
The client accesses the server though HTTP GET, POST and PUT requests. The HTTP API is accessible at URIs starting with /ajax
. Each server module has a unique name and its own sub-namespace with that name below /ajax
, e. g. all access to the module "tasks" is via URIs starting with /ajax/tasks
.
Text encoding is always UTF-8. Data is sent from the server to the client as text/javascript
and interpreted by the client to obtain an ECMAScript object. The HTTP API uses only a small subset of the ECMAScript syntax. This subset is roughly described by the following BNF:
Value ::= "null" | Boolean | Number | String | Array | Object Boolean ::= "true" | "false" Number ::= see NumericLiteral in ECMA 262 3rd edition String ::= \"([^"\n\\]|\\["\n\\])*\" Array ::= "[]" | "[" Value ("," Value)* "]" Object ::= "{}" | "{" Name ":" Value ("," Name ":" Value)* "}" Name ::= [A-Fa-f][0-9A-Fa-f_]*
Numbers are the standard signed integer and floating point numbers. Strings can contain any character, except double quotes, newlines and backslashes, which must be escaped by a backslash. Control characters in strings (other than newline) are not supported. Whitespace is allowed between any two tokens. See JSON and ECMA 262, 3rd edition for the formal definition.
The response body consists of an object, which contains up to four fields as described in Response body. The field data
contains the actual payload which is described in following chapters. The fields timestamp
, error
and error_params
are present when data objects are returned, if an error occurred and if the error message contains conversion specifiers, respectively. Following sections describe the contents of these fields in more detail.
Name | Type | Value | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
data | Value | Payload of the response. | ||||||||||||||||||||||||||
timestamp | Timestamp | Current timestamp on the server. | ||||||||||||||||||||||||||
error | String | English error message. Present in case of errors. | ||||||||||||||||||||||||||
error_params | Array | Replacement parameters for the error message. | ||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||
category | Number | Category to which the error message belongs:
|
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 an array index for error_params as a decimal number. The conversion specifications are replaced from left to right by elements from error_params, starting at index 0. %s is replaced by the element with the current index and the index is incremented. %n$s is replaced by the element with index n and the index is set to n + 1.
Some error message contain data sizes which must be expressed in Bytes or Kilobytes etc., depending on the actual value. Since the unit must be translated, this conversion is performed by the client. Unfortunately, standard printf()-style formatting does not have a specifier for this kind of translation. Therefore, the conversion specification for sizes is the same as for normal strings, and the client has to determine which parameters to translate based on the error code. The current error codes and the corresponding size parameters are listed in Data size parameters
Error code | Parameter indices |
---|---|
AJP-0006 | 1 |
AJP-0020 | 1, 2 |
CON-0101 | 2, 3 |
FLS-0003 | 1, 2, 3 |
MSG-0065 | 1, 3 |
MSG-0066 | 1 |
NON-0005 | 1, 2 |
Detailed Exception Data (Preliminary)
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:
Name | Type | Value | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
code | String | Error code consisting of a three-letter category and a four-digit message number, separated by a dash. | ||||||||||||||||||||||||||
category | Number | Category to which the error message belongs:
| ||||||||||||||||||||||||||
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
Dates without time are transmitted as the number of milliseconds between 00:00 UTC on that date and 1970‑01‑01 00:00 UTC. Leap seconds are ignored, therefore this number is always an integer multiple of 8.64e7.
Because ECMAScript Date objects have no way to explicitly specify a timezone for calculations, timezone correction must be performed on the server. Dates with time are transmitted as the number of milliseconds since 1970‑01‑01 00:00 UTC (again, ignoring leap seconds) plus the offset between the user's timezone and UTC at the time in question. (See the Java method java.util.TimeZone.getOffset(long)). Unless optional URL parameter timezone
is present. Then dates with time are transmitted as the number of milliseconds since 1970‑01‑01 00:00 UTC (again, ignoring leap seconds) plus the offset between the specified timezone and UTC at the time in question.
For some date and time values, especially timestamps, monotonicity is more important than the actual value. Such values are transmitted as the number of milliseconds since 1970‑01‑01 00:00 UTC, ignoring leap seconds and without timezone correction. If possible, a unique strictly monotonic increasing value should be used instead, as it avoids some race conditions described below.
This specification refers to these three interpretations of the type Number as separate data types. The types are described in Date and time types.
Type | Time | Timezone | Comment |
---|---|---|---|
Date | No | UTC | Date without time. |
Time | Yes | User | Date and time. |
Timestamp | Yes | UTC | Timestamp or unique sequence number. |
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 of the form:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> <head> <script type="text/javascript"> parent.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. The content-type of the answer is text/html
.
Documentation conventions
The rest of this document describes all available requests for each module. A module usually supports several different requests, which are differentiated by the used HTTP method, URI path and supplied URI parameters. The description of each method generally contains the following elements:
- the HTTP method followed by the request URI, inclusing the URI parameter action, which is used to differentiate methods,
- a list of URI parameters which can or must be supplied by the client,
- for PUT requests, content of the request body,
- "Response with timestamp:"if the timestamp field is required in the response body or simply "Response:" if not,
- content of the response payload, unless it is supposed to be empty.
Common object data
This table contains common fields which apply for any module's data type and is referenced throughout this document whenever a module's data type is described.
ID | Name | Type | Value |
---|---|---|---|
1 | id | String | Object ID |
2 | created_by | String | User ID of the user who created this object. |
3 | modified_by | String | User ID of the user who last modified this object. |
4 | creation_date | Time | Date and time of creation. |
5 | last_modified | Time | Date and time of the last modification. |
20 | folder_id | String | Object ID of the parent folder. |
100 | categories | String | String containing comma separated the categories. Order is preserved. Changing the order counts as modification of the object. Not present in folder objects. |
101 | private_flag | Boolean | Overrides folder permissions in shared private folders: When true, this object is not visible to anyone except the owner. Not present in folder objects. |
102 | color_label | Number | Color number used by Outlook to label the object. The assignment of colors to numbers is arbitrary and specified by the client. The numbers are integer numbers between 1 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 |
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.
Login
POST /ajax/login?action=login
Parameters:
name
– The login name.password
– The password.authId
(optional) – Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.client
(optional) – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.version
(optional) – Used version of the HTTP/JSON interface client.
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.
Logout
GET /ajax/login?action=logout
Parameters:
session
– A session ID previously obtained from the login module.
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).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.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 reloadserverVersion
- 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 usertasks
– 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)
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)maximumNumberParticipants
– Defines the maximum number of participants for appointments and tasks. (read-only, added 2008-10-20/SP5)showWithoutEmail
- If external participants without email should be shown.showDialog
– Enables participant selection dialog for appointments and tasks. (read-only, added 2008-04-30/SP4)
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 belowmodules/
without amodule
subelement or with a subelement containingtrue
(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 modulemodule
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 moduleinlineattachments
– 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 modulemodule
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 modulemailAddressAutoSearch
– 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)
tasks
gui
GUI settings for the tasks modulemodule
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 modulemodule
interfaces
ical
vcard
syncml
folder
gui
GUI settings for the folder treepublic_folders
read_create_shared_folders
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)
Get configuration data
GET /ajax/config/path
Parameters:
session
– A session ID previously obtained from the login module.
Response: Value of the node specified by path.
Set configuration data
PUT /ajax/config/path
Parameters:
session
– A session ID previously obtained from the login module.
Request body: The new value of the node specified by path.
Module "folders"
The folders module is used to access the OX folder structure.
Special System Folders
Folders with some kind of special.
ID | Type | Description |
---|---|---|
6 | contacts | System Users |
Get root folders
GET /ajax/folders?action=root
Parameters:
session
– A session ID previously obtained from the login module.columns
– A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in Common folder data and Detailed folder data.tree
– (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
Response: An array with data for all folders at the root level of the folder structure. Each array element describes one folder and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
ID | Name | Type | Value |
---|---|---|---|
1 | id | String | Object ID |
2 | created_by | String | User ID of the user who created this object. |
3 | modified_by | String | User ID of the user who last modified this object. |
4 | creation_date | Time | Date and time of creation. |
5 | last_modified | Time | Date and time of the last modification. |
6 | last_modified_utc | Timestamp | Timestamp of the last modification. Note that the type is Timestamp, not Time. See #Date and time for details. (added 2008-10-17, with SP5, temporary workaround) |
20 | folder_id | String | Object ID of the parent folder. |
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:
| ||||||||
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 mail folder capabilites, as described in capabilities. | ||||||||
314 | subscribed | Boolean | Indicates whether this folder should appear in folder tree or not. | ||||||||
315 | subscr_subflds | Boolean | Indicates whether subfolders should appear in folder tree or not. | ||||||||
316 | standard_folder_type | Number | Indicates the default folder type. Zero for non-default folder. See Standard folder types | ||||||||
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. |
Bits | Value | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
0-6 | Folder permissions:
| ||||||||||
7-13 | Read permissions for objects in the folder:
| ||||||||||
14-20 | Write permissions for objects in the folder:
| ||||||||||
21-27 | Delete permissions for objects in the folder:
| ||||||||||
28 | Admin flag:
|
Name | Type | Value |
---|---|---|
bits | Number | For non-mail folders, a number as described in Permission flags. |
rights | String | For mail folders, the rights string as defined in RFC 2086. |
entity | Number | User ID of the user or group to which this permission applies. |
group | Boolean | true if entity refers to a group, false if it refers to a user. |
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. |
Bit | Description |
---|---|
0 | No default folder. |
1 | Task. |
2 | Calendar. |
3 | Contact. |
7 | Inbox. |
8 | Infostore. |
9 | Drafts. |
10 | Sent. |
11 | Spam. |
12 | Trash. |
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.tree
– (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
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.
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.
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 are 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.
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.
Request body: Folder object as described in Common folder data and Detailed folder data. Only modified fields are present.
Create a folder
PUT /ajax/folders?action=new
Parameters:
folder_id
– The parent folder of the newly created foldersession
– 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.
Request body: Folder object as described in Common folder data and Detailed folder data. The field id should not be present.
Provided that permission is granted to create a folder, its module is bound to the limitation, that the new folder's module must be equal to parent folder's module except that:
- Parent folder is one of the system folders
private
,public
, orshared
. Below these folders task, calendar, and contact modules are permitted. - Parent folder's module is one of task, calendar, or contact. Below this kind of folders task, calendar, and contact modules are permitted.
Response: Object ID of the newly created folder.
Delete folders
PUT /ajax/folders?action=delete
Parameters:
session
– A session ID previously obtained from the login module.timestamp
– Timestamp of the last update of the deleted folders.tree
– (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.
Request body: An array with object IDs of the deleted folders.
Response: An array with object IDs of folders which were modified after the specified timestamp and were therefore not deleted.
Clearing a folder's content (preliminary)
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.
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.
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.
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. | ||||||||||
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. | ||||||||||
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. For tasks, the Time value specifies the absolute time when the user should be notified. | ||||||||||
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. | ||||||||||
209 | recurrence_type | Number | Specifies the type of the recurrence for a task sequence:
| ||||||||||
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. | ||||||||||
212 | days | Number | Specifies which days of the week are part of a sequence. The value is a bitfield with bit 0 indicating sunday, bit 1 indicating monday and so on. May be present if recurrence_type > 1. If allowed but not present, the value defaults to 127 (all 7 days). | ||||||||||
213 | day_in_month | Number | Specifies which day of a month is part of the sequence. Counting starts with 1. If the field "days" is also present, only days selected by that field are counted. If the number is bigger than the number of available days, the last available day is selected. Present if and only if recurrence_type > 2. | ||||||||||
214 | month | Number | Month of the year in yearly sequencies. 0 represents January, 1 represents February and so on. Present if and only if recurrence_type = 4. | ||||||||||
215 | interval | Number | Specifies an integer multiplier to the interval specified by recurrence_type. Present if and only if recurrence_type > 0. Must be 1 if recurrence_type = 4. | ||||||||||
216 | until | Date | Inclusive end date of a sequence. May be present only if recurrence_type > 0. The sequence has no end date if recurrence_type > 0 and this field is not present. Note: since this is a Date, the entire day after the midnight specified by the value is included. | ||||||||||
217 | notification | Boolean | If true, all participants are notified of any changes to this object. This flag is valid for the current change only, i. e. it is not stored in the database and is never sent by the server to the client. | ||||||||||
220 | participants | Array | Each element identifies a participant, user group or booked resource as described in Participant identifier. | ||||||||||
221 | users | Array | Each element represents a participant as described in User participant object. User groups are resolved and are represented by their members. Any user can occur only once. | ||||||||||
222 | occurrences | Number | Specifies how often a recurrence should appear. May be present only if recurrence_type > 0. | ||||||||||
223 | uid | String | Can only be written when the object is created. Internal and external globally unique identifier of the appointment. Is used to recognize appointments within iCal files. If this attribute is not written it contains an automatic generated UUID. Not implemented for tasks. | ||||||||||
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. | ||||||||||
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. |
Name | Type | Value | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
id | Number | User ID | ||||||||||
type | Number | Type of participant:
| ||||||||||
String | mail address of an external participant |
Name | Type | Value | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
id | Number | User ID | ||||||||
display_name | String | Displayable name of the participant. | ||||||||
confirmation | Number |
| ||||||||
confirmmessage | String | Confirm Message of the participant |
Name | Type | Value | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
type | Number | Type of participant:
| ||||||||
String | email address of external participant | |||||||||
display_name | String | display name of external participant | ||||||||
status | Number |
| ||||||||
confirmmessage | String | Confirm Message of the participant |
ID | Name | Type | Value | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
300 | status | Number | Status of the task:
| ||||||||||
301 | percent_completed | Number | How much of the task is completed. An integer number between 0 and 100. | ||||||||||
302 | actual_costs | ||||||||||||
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 | ||||||||||||
308 | target_duration | ||||||||||||
309 | priority | Number | 1 = LOW, 2 = MEDIUM, 3 = HIGH | ||||||||||
312 | currency | ||||||||||||
313 | trip_meter | ||||||||||||
314 | companies | ||||||||||||
315 | date_completed |
Get a list of tasks
PUT /ajax/tasks?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 tasks are defined in Common object data, Detailed task and appointment data and Detailed task data.
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
(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 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 are 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 tasks
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.
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
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.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.
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.
ID | Displayed name | Name | Type | Value |
---|---|---|---|---|
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 | Martial 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 | Anniversay | 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 | |
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 assostant | 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 | |
591 | links | Array | An array of objects containing links to other contacts. Each contact is describes by an object as defined in 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 Distribution list member. | |
594 | Number of distributionlists | number_of_distribution_list | Number | |
595 | number_of_links | Number | deprecated | |
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 | ||
524 | internal_userid | Number | ||
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. |
Name | Type | Value |
---|---|---|
id | String | Object ID |
first_name | String | First name |
last_name | String | Last name |
Name | Type | Value | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
id | String | User ID of the member if the member is an existing contact. | ||||||||
first_name | String | First name | ||||||||
last_name | String | Last name | ||||||||
String | Email address | |||||||||
mail_field | Number | Which email field of an existing contact (if any) is used for the mail field.
|
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 are 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 contacts
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”.
Search contacts
PUT /ajax/contacts?action=search
Parameters:
session
– A session ID previously obtained from the login module.columns
– The requested fieldssort
(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.
Request body: An Object as described in 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. |
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.
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, the fields are connected through an OR search habit. |
emailAutoComplete | Boolean | If set to true, results are guaranteed to contain at least one email adress and the search is performed by connecting the relevant fields through an OR search habit. |
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.
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.
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.
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. | ||||||||
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:
| ||||||||
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.
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.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
(optional) – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.end
(optional) – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.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.
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 are 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 appointments
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.
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.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:
| ||||||||
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/appointments?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.
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 contact 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/appointments?action=newappointments
Parameters:
session
– A session ID previously obtained from the login module.columns
– The requested fieldsstart
– 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.
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.
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.
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). | ||||||||||||||||
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 string specifying one sender. | ||||||||||||||||
604 | to | Array | Each element is a string specifying one receiver. | ||||||||||||||||
605 | cc | Array | Each element is a string specifying one carbon-copy receiver. | ||||||||||||||||
606 | bcc | Array | Each element is a string 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:
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:
| ||||||||||||||||
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. | ||||||||||||||||
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. |
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. |
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"}]
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.
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.
Name | Type | Value |
---|---|---|
color_label | Number | The color number between 1 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).
|
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. |
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 textsrc
(optional) – 1 to let the response contain the complete message source as plain textsave
(optional) – 1 to write the complete message source to output stream. NOTE: This parameter will only be used if parametersrc
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. "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
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 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 ORcid
– Value of header 'Content-ID' of the requested attachmentsave
– 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 typetext/htm*
AND parametersave
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 (preliminary)
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.
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
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 form field
attachment
n (optional) – One or more file upload form fields whose referenced file are going to appended as attachments
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.src
- Set to "1" to accept mail message as MIME data block.folder
(optional) - In case the mail should not be sent out, but saved in a specific folder, the "folder" paramter 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.
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.
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 with object IDs of the deleted mails.
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.
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.
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.
Name | Type | Value |
---|---|---|
id | Number | ID |
display_name | String | Display name |
name | String | Name with character restrictions |
members | Array | Array of group member id's |
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.
Module "resource"
The resource module allows to query available resources. It is mainly used by the dialog for the selection of participants.
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.
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.
Name | Type | Value |
---|---|---|
id | Number | ID |
display_name | String | Display name |
Module "infostore"
The infostore module combines the knowledge database, bookmarks and documents.
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.
ID | Name | Type | Value |
---|---|---|---|
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. |
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 are 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.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: An Object as described in Search contacts.
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 returnedcontent_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 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.
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.
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.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).
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.
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.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 attachmentfolder
– The Folder ID of the Object with the attachmentmodule
– 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.
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.
Request body: An array with [[]].
Response: An array with objects to delete. The fields for the object are described in 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 Objectfolder
– The Folder of the Objecttimestamp
- 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 Objectfolder
– The Folder of the Objecttimestamp
- 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 Objectfolder
– The Folder of the Objecttimestamp
- 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.
Module "Links" (deprecated)
The link module provides the ability to connect two objects from any module.
Get All Links from an Object
GET /ajax/link?action=all
Parameters:
session
– A session ID previously obtained from the login module.id
– The Object ID of the Objectfolder
– The Folder ID of the Objectmodule
– The Module type of the Object
Response: An Array with all Links ( Link object) from the given Object ID.
Create a Link
PUT /ajax/link?action=new
Parameters:
session
– A session ID previously obtained from the login module.
Request body: Link object as described in Link object.
Response: An OK.
Field | Name | Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
First Object ID | id1 | Number | The ID of the first Object you want to start to link | ||||||||||||||||
First Module Type | module1 | Number | The Module of this Object Possible Values:
| ||||||||||||||||
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:
| ||||||||||||||||
Second Folder ID | folder2 | String | The Folder of the second Object |
Delete Link
PUT /ajax/link?action=delete
Parameters:
session
– A session ID previously obtained from the login module.id
– The ID of the base Objectmodule
– The type of the Objectfolder
– The Folder of the Object
Request body: A List of arrays with the information of the Links to delete which looks like Delete object.
Response: A List of arrays with object Ids of links which are not readable by the user and were therefore not deleted. See 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 /ajax/attachment?action=all
Parameters:
session
– A session ID previously obtained from the login module.attached
– The Object ID of the Objectfolder
– The Folder ID of the Objectmodule
– The Module type of the Objectcolumns
– 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 Objectfolder
– The Folder ID of the Objectmodule
– 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.
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:
| ||||||||
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 Objectmodule
– The type of the Objectfolder
– 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 are 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 Common object data (with only id, created_by and creation_date available) and Attachment object.
Get an attachments filedata
GET /ajax/attachment/[filename]?action=document
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.content_type
(optional) – If set the responses Content-Type header is set to this value, not the attachements file mime type.
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. Note: The Filename may be added to the customary infostore path to suggest a filename to a Save-As dialog.
Module "reminder"
The reminder module provides the ability to fetch all active reminders for a user between two dates.
Get reminder range
GET /ajax/reminder?action=range
Parameters:
session
– A session ID previously obtained from the login module.end
– The End date of the reminder range
Response: An Array with all reminders which are scheduled until the specified time. Each reminder is described in Reminder response.
Field | Type | Description |
---|---|---|
id | Number | The ID of the reminder. |
target_id | Number | The target_id where this reminder is attached to |
alarm | Time | The time of the alarm |
module | Number | The module of the reminder |
servertime | Time | The time on the server |
user_id | Number | The ID of the user. |
last_modified | Time | The last modification timestamp of the reminder |
recurrence_position | Number | The recurrence position for series appointments or 0 if no series |
folder | Number | The ID of the folder through that the object can be read |
Delete Reminder
PUT /ajax/reminder?action=delete
Parameters:
session
– A session ID previously obtained from the login module.
Request body: An object with the field “id”.
Response body: An JSON array with the id that was not deleted.
Module "multiple"
The multiple module allows to bundle multiple requests to most other modules in a single request. Not supported are:
- modules login, config and multiple,
- POST requests with a multipart encoding (uploads),
- GET requests which do not use an object as described in Response body as response body (downloads).
Multiple requests
PUT /ajax/multiple
Parameters:
session
– A session ID previously obtained from the login module.continue
– Specifies whether processing of requests should stop when an error occurs, or whether all request should be processed regardless of errors.
Request body: An array with request objects. Each request object contains all URI parameters of the "normal" request as fields. The module name of the "normal" request is included in the field module. The parameter session is not included. If the "normal" request has a request body, the object which is represented by that request body is includes as the value of the field data.
Response: An array with reply objects as described in Response body. The order of reply objects corresponds to the order of requests in the request body. Unlike with all other modules, this response is itself not part of a response object as described in Response body.
Module "quota"
The filestore module allows accesssing information about the use and quota of the filestore.
Get the filestore usage data
GET /ajax/quota?action=filestore
Parameters:
session
– 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 /ajax/quota?action=mail
Parameters:
session
– 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.
Import CSV
POST /ajax/import?action=CSV
Parameters:
session
– A session ID previously obtained from the login module.folder
– ObjectID of the folder into which data should be imported. This must be a Contact folder.
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.
Response: An array of JSON-Objects, one for each entry in the list, containing: The Object ID of the entry, the Object ID of the folder the data was written into, a timestamp of the modification (in case of error, of modification attempt) and an error in case the data could not be entered.
Import Outlook CSV
POST /ajax/import?action=OUTLOOK_CSV
Parameters:
session
– A session ID previously obtained from the login module.folder
– ObjectID of the folder into which data should be imported. This must be a Contact folder.
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.
Response: An array of JSON-Objects, one for each entry in the list, containing: The Object ID of the entry, the Object ID of the folder the data was written into, a timestamp of the modification (in case of error, of modification attempt) and an error in case the data could not be entered.
Import iCAL
POST /ajax/import?action=ICAL
Parameters:
session
– A session ID previously obtained from the login module.folder
– 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.
Request body: An iCalendar file.
Response: An array of JSON-Objects, one for each entry in the list, containing: The Object ID of the entry, the Object ID of the folder the data was written into, a timestamp of the modification (in case of error, of modification attempt) and an error in case the data could not be entered, and warnings (under the key "warnings") containing an Array of objects with the warning data, containing all customary error fields.
Import vCard
POST /ajax/import?action=VCARD
Parameters:
session
– A session ID previously obtained from the login module.folder
– ObjectID of the folder into which data should be imported. This must be a Contact folder.
Request body: An vCard file, maybe of the formats: vCard 2.1, vCard 3.0 or vCalendar 1.0
Response: An array of JSON-Objects, one for each entry in the list, containing: The Object ID of the entry, the Object ID of the folder the data was written into, a timestamp of the modification (in case of error, of modification attempt) and an error in case the data could not be entered.
Module "export"
The module export allows to export specific module data (like Contacts, Tasks or Appointments) from a folder in several formats (iCal, vCard, CSV).
Exporting CSV
GET /ajax/export?action=CSV
Parameters:
session
– A session ID previously obtained from the login module.folder
– ObjectID of the folder whose contents are to be exported. This must be a Contact folder.columns
– (optional) Columns to be imported from the given file, given as an array of column numbers. See Detailed contact data for numbers.
Response: An InputStream containing the file of the MIME type text/csv
.
Exporting iCAL
GET /ajax/export?action=ICAL
Parameters:
session
– A session ID previously obtained from the login module.folder
– ObjectID of the folder whose contents are to be exported. This must be a Calendar folder.
Response: An InputStream containing the file, of the MIME type text/calendar
.
Exporting vCard
GET /ajax/export?action=VCARD
Parameters:
session
– A session ID previously obtained from the login module.folder
– ObjectID of the folder whose contents are to be exported. This must be a Contact folder.
Response: An InputStream containing the file, of the MIME type text/x-vcard
.
Module "sync"
The module sync delivers several core API extensions to support common operations used in a mobile synchronization environment.
Clearing a folder's content
PUT /ajax/sync?action=refresh_server
Parameters:
session
– A session ID previously obtained from the login module.
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.
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.
A detailed description can be found here Mail Filter HTTP API
Module "ajax file upload"
This module offers to store files in server's dedicated download directory for a configureable amount of time. The files are then accessible for further operations like inline images in (html) mails
Uploading a file
POST /ajax/file?action=new
Parameters:
session
– A session ID previously obtained from the login module.module
– The module for which the file is uploaded to determine proper upload quota constraints (e.g. "mail", "infostore", etc.).type
– The file type filter to define which file types are allowed during upload. Currently supported filters are:file=all, text=text/*, media=image OR audio OR video, image=image/*, audio=audio/*, video=video/*, application=application/*
Request body: A common POST request body of MIME type "multipart/*" which holds the file(s) to upload
Response: A JSON array containing the IDs of the uploaded files. The files are accessible through the returned IDs for future use.
Updating a file's last access timestamp (keep alive)
By updating the last access timestamp it's prevented from being deleted from both session and disk storage.
GET /ajax/file?action=keepalive
Parameters:
session
– A session ID previously obtained from the login module.id
– The ID of the uploaded file whose timestamp should be updated
Response: The string "null" in response's data element
Requesting a formerly uploaded file
GET /ajax/file?action=get
Parameters:
session
– A session ID previously obtained from the login module.id
– The ID of the uploaded file
Response: The content of the requested file is directly written into output stream
Module "image"
This module allows to download images from Open-Xchange server without providing a session ID in request's URL parameters.
Requesting an image
GET /ajax/image
Parameters:
uid
– The unique ID referring to the desired 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 /ajax/conversion?action=convert
or
POST /ajax/conversion?action=convert
Parameters: <no parameters required>
Request body: A conversion request JSON object containing nested JSON objects for data source and data handler
Field | Type | Description |
---|---|---|
datasource | JSON object | The data source object. |
datahandler | JSON object | The data handler object. |
Field | Type | Description |
---|---|---|
identifier | String | The identifier of the data source. |
args | JSON array | The optional name-value-pairs as JSON objects for data source |
Field | Type | Description |
---|---|---|
identifier | String | The identifier of the data handler. |
args | JSON array | The optional name-value-pairs as JSON objects for data handler |
Response: The result of converted data ready as an appropriate JSON response
Saving an ICal email attachment
If an ICal file is attached to an email, its content can be saved as appointments and tasks into given calendar and task folder.
Data source's JSON object
{
"identifier":"com.openexchange.mail.ical"
"args":
[
{"com.openexchange.mail.conversion.fullname":"<folder-fullname>"}
{"com.openexchange.mail.conversion.mailid":"<mail-id>"}
{"com.openexchange.mail.conversion.sequenceid":"<attachment-sequence-id>"}
]
}
Data handler's JSON object
{
"identifier":"com.openexchange.ical"
"args":
[
{"com.openexchange.groupware.calendar.folder":"<calendar-folder-id>"}
{"com.openexchange.groupware.task.folder":"<task-folder-id>"}
]
}
Response: A JSON array of JSON objects each providing folder and object ID of added appointment/task; e.g. [{"folder_id":2567, "id":7689}, ...]
Converting an ICal email attachment into JSON objects
If an ICal file is attached to an email, its content can converted to JSON appointments and tasks.
Data source's JSON object
{
"identifier":"com.openexchange.mail.ical"
"args":
[
{"com.openexchange.mail.conversion.fullname":"<folder-fullname>"}
{"com.openexchange.mail.conversion.mailid":"<mail-id>"}
{"com.openexchange.mail.conversion.sequenceid":"<attachment-sequence-id>"}
]
}
Data handler's JSON object.
Note that both arguments are optional: Default is user time zone and zero recurrence position
{
"identifier":"com.openexchange.ical.json"
"args":
[
{"com.openexchange.groupware.calendar.timezone":"<timezone-id>"}
{"com.openexchange.groupware.calendar.recurrencePosition":"<recurrence-position>"}
]
}
Response: A JSON array of JSON objects for each appointment/task as described in Common object data, Detailed task and appointment data and Detailed task data/ Detailed appointment data
Saving a VCard email attachment
If a VCard file is attached to an email, its content can be saved as contacts into given contact folder.
Data source's JSON object
{
"identifier":"com.openexchange.mail.vcard"
"args":
[
{"com.openexchange.mail.conversion.fullname":"<folder-fullname>"}
{"com.openexchange.mail.conversion.mailid":"<mail-id>"}
{"com.openexchange.mail.conversion.sequenceid":"<attachment-sequence-id>"}
]
}
Data handler's JSON object
{
"identifier":"com.openexchange.contact"
"args":
[
{"com.openexchange.groupware.contact.folder":"<contact-folder-id>"}
]
}
Response: A JSON array of JSON objects each providing folder and object ID of added contact; e.g. [{"folder_id":2567, "id":7689}, ...]
Contact(s) attached to a new email as a VCard file
Obtain VCard data from specified contact object(s).
Data source's JSON object
{
"identifier":"com.openexchange.contact"
"args":
[
{"folder":"<folder-id1>","id":"<id1>"}
...
{"folder":"<folder-idn>","id":"<idn>"}
]
}
Get a new email's JSON object with specified VCard data source attached.
Data handler's JSON object
{
"identifier":"com.openexchange.mail.vcard"
"args":[]
}
Response: A mail JSON object.
Module "search" (preliminary)
The search module is an enhancement to each search request as an optional JSON object via PUT method to filter elements; e.g.
PUT /ajax/contacts?action=all&...
{"filter":{search-term-object}}
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:
{"operation":"equals","operands":[...]}
Moreover there are two different types of a search terms:
- A single search term
- A composite search term
A single search term reflects an operation which cannot hold nested search terms as operands; e.g. "equals". In opposite to this a composite search term holds one or more nested search terms as operands; e.g. "not" or the logical junctors "and"/"or".
By now the following operations are supported:
- composite operations
- "and" - The AND junctor
- "or" - The OR junctor
- "not" - Negation
- single operations
- "equals" - Equals comparison
- "lt" - Less-than comparison
- "gt" - Greater-than comparison
Furthermore following operand types are supported for single search terms:
- Column - Providing a name referring to a field/column
- Constant - A constant
Example of an EQUALS search term:
{"operation":"equals","operands":[{"type":"column","value":"first_name"},"Jane"]}
Example of an OR search term:
{"operation":"or","operands":
[
{"operation":"equals","operands":[{"type":"column","value":"first_name"},"Jane"]},
{"operation":"gt","operands":[{"type":"column","value":"birthday"},"1975-05-01"]}
]
}
Refer to object data tables introduced by different modules to know which field names are supported; e.g. for tasks it is Common object data, Detailed task and appointment data, and Detailed task data.
Module "mail account" (preliminary: available with v6.12)
The mail account module is used to manage multiple mail accounts held by a user.
Get a mail account
GET /ajax/account?action=get
Parameters:
session
– A session ID previously obtained from the login module.id
– The ID of the account to return.
Response: A JSON object representing the desired mail account. See mail account data.
ID | Name | Type | Value |
---|---|---|---|
1001 | id | Number | Account ID |
1002 | login | String | The login. |
1003 | password | String | The (optional) password. |
1004 | mail_url | String | The mail server URL; e.g. "imap://imap.somewhere.com:143". URL is preferred over single fields (like mail_server, mail_port, etc.) |
1005 | transport_url | String | The transport server URL; e.g. "smtp://smtp.somewhere.com:25". URL is preferred over single fields (like transport_server, transport_port, etc.) |
1006 | name | String | Account's display name. |
1007 | primary_address | String | User's primary address in account; e.g. "someone@somewhere.com" |
1008 | spam_handler | String | The name of the spam handler used by account. |
1009 | trash | String | The name of the default trash folder. |
1010 | sent | String | The name of the default sent folder. |
1011 | drafts | String | The name of the default drafts folder. |
1012 | spam | String | The name of the default spam folder. |
1013 | confirmed_spam | String | The name of the default confirmed-spam folder. |
1014 | confirmed_ham | String | The name of the default confirmed-ham folder. |
1015 | mail_server | String | The mail server's hostname or IP address. |
1016 | mail_port | Number | The mail server's port. |
1017 | mail_protocol | String | The mail server's protocol. Always use basic protocol name. E.g. use "imap" instead of "imaps" |
1018 | mail_secure | Boolean | Whether to establish a secure connection to mail server (SSL, TLS). |
1019 | transport_server | String | The transport server's hostname or IP address. |
1020 | transport_port | Number | The transport server's port. |
1021 | transport_protocol | String | The transport server's protocol. Always use basic protocol name. E.g. use "smtp" instead of "smtps" |
1022 | transport_secure | Boolean | Whether to establish a secure connection to transport server (SSL, TLS). |
1023 | transport_login | String | The transport login. If empty "login" is taken as transport login as well. |
1024 | transport_password | String | The transport password. If empty "password" is taken as transport password as well. |
1025 | unified_inbox_enabled | Boolean | If enabled for Unified INBOX |
1026 | trash_fullname | String | Path to default trash folder. Preferred over "trash" |
1027 | sent_fullname | String | Path to default sent folder. Preferred over "sent" |
1028 | drafts_fullname | String | Path to default drafts folder. Preferred over "drafts" |
1029 | spam_fullname | String | Path to default spam folder. Preferred over "spam" |
1030 | confirmed_spam_fullname | String | Path to default confirmed-spam folder. Preferred over "confirmed_spam" |
1031 | confirmed_ham_fullname | String | Path to default confirmed-ham folder. Preferred over "confirmed_ham" |
1032 | pop3_refresh_rate | Number | The interval in minutes the POP3 account is refreshed |
1033 | pop3_expunge_on_quit | Boolean | Whether POP3 messages shall be deleted on actual POP3 account after retrieval or not |
1034 | pop3_delete_write_through | Boolean | If option "pop3_expunge_on_quit" is disabled, this property defines whether a delete in local INBOX also deletes affected message in actual POP3 account |
1035 | pop3_storage | String | The name of POP3 storage provider, default is "mailaccount" |
1036 | pop3_path | String | Path to POP3's virtual root folder in storage, default is name of the POP3 account beside default folders |
1037 | personal | String | The customizable personal part of email address |
Create a new mail account
PUT /ajax/account?action=new
Parameters:
session
– A session ID previously obtained from the login module.
Request: A JSON object describing the new account to create. See mail account data.
Response: A JSON object representing the inserted mail account. See mail account data.
Update a mail account
PUT /ajax/account?action=update
Parameters:
session
– A session ID previously obtained from the login module.
Request: A JSON object identifiying (field ID is present) and describing the account to update. See mail account data.
Response: A JSON object representing the updated mail account. See mail account data.
Delete a mail account
PUT /ajax/account?action=delete
Parameters:
session
– A session ID previously obtained from the login module.
Request body: An array with the ID of the mail account to delete.
Validate a mail account (which shall be created)
PUT /ajax/account?action=validate
Parameters:
session
– A session ID previously obtained from the login module.tree
- An optional boolean parameter which indicates whether on successful validation the folder tree shall be returned (NULL on failure) or if set to "false" or missing only a boolean is returned which indicates validation result
Request: A JSON object describing the new account to validate. See mail account data.
Response: Dependent on optional "tree" parameter a JSON folder object or a boolean value indicating the validation result
The JSON folder object corresponding to Common folder data and Detailed folder data. Additionally a field "subfolder_array" is added which contains possible subfolders. This field is missing if a folder contains no subfolders.
Module "user" (preliminary: available with v6.14)
The user module is used to access user information.
Get all users
GET /ajax/user?action=all
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 users are defined in Common object data, Detailed contact data and Detailed user 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 user data. Each array element describes one user and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
ID | Displayed name | Name | Type | Value |
---|---|---|---|---|
610 | Aliases | aliases | Array | The user's aliases |
611 | Time zone | timezone | String | The time zone ID. |
612 | Locale | locale | String | The name of user's entire locale, with the language, country and variant separated by underbars. E.g. "en", "de_DE" |
613 | Groups | groups | Array | The IDs of user's groups |
614 | Contact ID | contact_id | Number | The contact ID of the user |
615 | Login info | login_info | String | The user's login information |
Get a list of users
PUT /ajax/user?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 users are defined in Common object data, Detailed contact data and Detailed user data.
Request body: An array of numbers. Each number is the ID of requested user.
Response with timestamp: An array with user data. Each array element describes one user and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.
Get a user
GET /ajax/user?action=get
Parameters:
session
– A session ID previously obtained from the login module.id
– Object ID of the requested user.
Response with timestamp: An object containing all data of the requested user. The fields of the object are listed in Common object data, Detailed contact data and Detailed user data.
Update a user
PUT /ajax/user?action=update
Parameters:
session
– A session ID previously obtained from the login module.id
– Object ID of the updated user.timestamp
– Timestamp of the updated user. If the user was modified after the specified timestamp, then the update must fail.
Request body: User object as described in Common object data, Detailed contact data and Detailed user data. Only modified fields are present.
Note: "timezone" and "locale" are the only fields from Detailed user data which are allowed to be updated.
Response with timestamp: An empty object.
Search users
PUT /ajax/user?action=search
Parameters:
session
– A session ID previously obtained from the login module.columns
– The requested fieldssort
(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 users 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.
Request body: An Object as described in Search users.
Name | Type | Value |
---|---|---|
pattern | String | Search pattern to find users. 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 users with the given startletter. If this field is present, the pattern is matched against the user 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. |
Alternative request body: An Object as described in Search users alternative.
Name | Type | Value |
---|---|---|
last_name | String | Searches users where the last name match with the given last name. |
first_name | String | Searches users where the first name match with the given first name. |
display_name | String | Searches users where the display name match with the given display name. |
orSearch | Boolean | If set to true, the fields are connected through an OR search habit. |
emailAutoComplete | Boolean | If set to true, results are guaranteed to contain at least one email adress and the search is performed by connecting the relevant fields through an OR search habit. |
Response: An array with user data. Each array element describes one user and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.