Version 5.2
Applications |
|---|
| ||||||||||
|
|
Version 5.2 |
||||||||||||||||||||||||||||||||
|
|
XML API clients should open clear-text or secure TCP connections to the CommuniGate Pro Server XML module. When a connection is established, both sides can send and receive messages.
Each message is a text string ending with a binary zero byte.
Each message should be formatted as an XML document.
A client asks the Server to take actions and/or to retrieve data by sending a request message. Each request message must contain the id attribute.
When the Server completes the requested operation, it sends back a response message:
A client can send the next request message without waiting for the current request response (pipelining).
The Server can send data messages to the client:Note: a Client must send some command to the Server at least once in 10 minutes, otherwise the Server closes the connection.
When a connection is established, the Server takes the IP Address the client has connected to and selects the Domain this IP address is assigned to.
Operations in this section can explicitly specify an alternative target Domain: if it is found, the new target Domain is set and it is used in the next operations.
If the server returns a positive response, the client should start SSL/TLS negotiations immediately.
If the server returns a positive response, the Account password has been E-mailed.
Note: this operation introduces a delay before returning a response.
If the server returns a positive response, the Account has been created.
Note: this operation does not log user into a newly created Account.
Note: this operation introduces a delay before returning a response.
The Server sends the following data messages:
The Server sends the following data messages:
When the specified SASL method involves sending a challenge to the client,
it is sent as a challenge data message, with the value attribute
containing the base64-encoded SASL protocol challenge data.
The client should respond by sending an auth request with the same id
attribute as one used in the login request, and the value attribute
containing the base64-encoded SASL protocol response data.
The following operations can be used to manage the client-server connection.
The Server can send the following service data messages at any time:
The Server can send the following data messages:
A client can use the following set of operations to manipulate Mailboxes in the authenticated Account, as well as in other Accounts (by specifying the full Mailbox name as ~accountName@domainName/mailboxName).
Note: all non-ASCII Mailbox names are specified using the UTF-8 charset (and not the IMAP UTF-7 encoding method).
The Server sends the following data messages:
A client can use the following operations to process a Mailbox in the authenticated Account, as well as in other Accounts (by specifying the full Mailbox name as ~accountName@domainName/mailboxName).
A session can use several open Folders at the same time.
A client should maintain an internal view of the Folder - an array or a table with one element for each Folder message. A client should keep that view synchronized with the Server view (implemented with that Folder).
When a Folder is opened, the Server sends a folderReport data message containing the total number of messages in the Folder. The client uses this number to create the initial internal view table, filling it with empty elements.
To display the Mailbox content on the screen, the client checks which elements of its internal view table it should use. If some of those elements are empty, the client should ask the Server to send it the information about the Folder messages specified by their index values (positions) in the sorted view (in the Folder).
Some Mailbox operations use a message set to specify the Mailbox messages to apply the operation to. Messages can be specified either by their UIDs, or by their index numbers (their positions in the folder view).
To specify messages by their UIDs, use one or more UID elements.
Each UID element can include one message, in this case the message UID is specified as the element body:
<UID>12377</UID>.
An UID element can include a range of message UIDs specified as the from and till attributes:
<UID from="12377" till="12455" />.
The operation is applied to all Mailbox messages with UIDs not smaller than the from attribute value and not larger than the till attribute value.
Please remember that Folder messages are not sorted by their UIDs, unless the sortField="UID" attribute was used in the folderOpen operation.
To specify messages by index, use one or more index elements.
Each index element can include one message, in this case the message index is specified as the element body:
<index>14</index>.
An index element can include an index range specified as the from and till attributes:
<index from="12" till="10000" />.
The operation is applied to all Folder messages with position (index) not smaller than the from attribute value and not larger than the till attribute value.
A message set can include one or more UID elements, or it can include one or more index elements, but it cannot include both UID and index elements.
The "on demand" client-server synchronization model is used. When a Folder message is modified, added, or deleted, the client gets an asynchronous folderReport data message with the mode attribute value set to notify (a "notify-mode" message).
The newly added messages do not become visible in the logical Folder and the deleted messages are not removed from the logical Folder. Requests to retrieve deleted message data return no data items or empty data items.
When the client application is ready to update its "internal view", it should use the folderSync operation:
The Server sends folderReport data messages with the mode attribute set to the removed, added, or updated value.
After the Server sends a "notify-mode" message to the Client, the Server may choose not to send further "notify-mode" messages for this Folder until the client performs the folderSync operation on this Folder.
The client can send requests to the Server asking for certain update operations (such as message deletion), but it should update its internal view only when the Server sends it a folderReport data message informing the client about actual changes in the Folder.
Note: unlike UIDs, Folder message index can change any time when the folderSync operation is performed. Before you start any operation using an index-based message set, make sure that you have correctly updated the internal view with all folderReport data messages generated with the previously sent folderSync operation.
Note: when a message has been removed from or added to a Mailbox, the Server only sends folderReport data messages with the mode="notify" attribute. The Server-side "view" of the modified Folder (the logical Folder) is not updated, and it is safe to use an index-based message set to start a Folder operation.
This operation can also be used to implement the "encrypt message" functionality: the selected messages should be moved to the same Mailbox using the encrypt operation attribute.
When a client uses this command, the Server sends the folderReport message with the mode attribute set to init,
notifying the client about the new Folder size.
The client should clear its internal Folder view, and re-populate it again.
Note:if a Client receives a folderReport message with the mode attribute set to notify when the Client has already sent the folderReopen command, the Client should use the folderSync command after it receives response for the folderReopen command.
The Server sends the following data messages:
A client can use the following set of operations to retrieve Messages from Mailboxes.
To create messages with file attachments, put the files into the "uploaded file set" first.
Then you can specify them in the MIME elements by using the uploadID attribute.
You can specify the type, subtype, and (for text files) charset attributes.
If you do not explicitly specify them, they are copied from the Content-Type field of the HTTP request used to upload the file.
To create messages with MIME parts (attachments) copied from other messages stored on the Server, use the copyMIME element instead of a MIME element:
You can attach files stored in the Personal File Storage.
Specify the full file name in the MIME elements by using the fileName attribute.
You must explicitly specify type, subtype, and (for text files) charset attributes.
You should specify the disposition-filename attribute, as the fileName attribute is not used to form the attachment name.
Note: if a <MIME /> element has the disposition attribute value none, the Content-Disposition: header field is not created, and the Content-Type field is stored without the name parameter.
Note: the text MIME parts should use a single LineFeed (0x0A, decimal 10) symbol as the line separator.
You can ask the Server to use the "flowed" format for text MIME parts.
Example:To create a signed message, make sure that S/MIME Private key is unlocked, and specify the sign attribute in the topmost EMail element.
This operation adds the following message to the Mailbox:
The Server sends the following data messages:
A client can use the following set of operations to manage Account ACLs.
The Server sends the following data messages:
A client can use the following set of operations to use the Server S/MIME features.
The Server detects all signed message parts and tries to verify that the part body has not been altered since the time it was signed, and that the signature certificates are valid (i.e. issued by known authorities).
The MIME element body for a signed message part contain 2 XML sub-elements: the first element is the signed data (an EMail or MIME element), the second part is the SMIMESignature XML element.
If the Server failed to decode or decrypt the signature data, the MIME element body for a signed message part contains the decryptionError attribute with the error code text.
The SMIMESignature element body contains Certifate sub-elements for all signatures that match the part data. If the Server failed to verify the Certificate, its element contains the validationError attribute with the error code text. If no signature matches the the part data, the SMIMESignature element is empty.
Example:When the Account Private Key is unlocked, the Server tries to decrypt all encrypted message parts.
If decrypting fails, the encrypted part is shown as the MIME or EMail XML sub-element of the encrypted part element.
If decrypting succeeds, the encrypted part element body contains a MIME or EMail XML sub-element with the decypted data.
When the Account Private Key is unlocked, a client can submit a signed E-mail.
Example:
The Client submits a signed text message to the toName@domain address address.
When the Account Private Key is unlocked, a client can submit an encrypted E-mail if there is an Address Book containg records for all E-mail recipients, and each of those records contains a recipient PKI Certificate.
The topmost EMail element should contain the single "inner" EMail element - the content of that element will be encrypted. The inner EMail element header fields can be the same as in the topmost EMail element, or they can be different. For example, the "inner" EMail element Subject element can be different.
Note: you cannot specify both the sign and encrypt attributes for the topmost EMail element. To send an encrypted and signed message, add the sign attribute to the inner EMail element.
Example:
The Client submits an encrypted and signed text message to the toName@domain address. Note unmatching subjects.
The Client requests delivery notification.
Contacts (vCard and vCardGroup) information can be stored as an E-mail item in any Mailbox. A vCard data element can be attached (as a MIME part) to any E-mail message. Each message can contain several MIME parts each containing several vCard objects.
MIME parts with the text type and x-vcard or dictionary subtype contain vCard elements.
MIME parts with the text type and x-vgroup subtype contain one vCardGroup element.
To include vCard data into a message (using the messageAppend, messageSubmit operations) include a MIME element with type="text" and subtype="directory" attributes. The element body should contain one or more vCard elements.
To include vCardGroup data into a message (using the messageAppend, messageSubmit operations) include a MIME element with type="text" and subtype="x-vgroup" attributes. The element body should contain one