XIMSS Protocol

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.

listFeatures

This operation tells the server to return a features message containing available communication and authentication options.

Attributes:

domain

optional target Domain name.

readStrings

This operation reads the vocabulary (words, tags, button names, etc.) stored on the Server. The Server sends a strings data message with the dictionary data (see below).

Attributes:

language

the vocabulary language. If the attribute is missing, the Account Language preference string is used.

starttls

This operation tells the server to establish SSL/TLS security on this connection.

Attributes:

domain

optional target Domain name.

If the server returns a positive response, the client should start SSL/TLS negotiations immediately.

recoverPassword

This operation asks the server to E-mail the password of the specified Account to the E-mail address the Account user has specified.

Attributes:

domain

optional target Domain name.

userName

the Account name.

If the server returns a positive response, the Account password has been E-mailed.
Note: this operation introduces a delay before returning a response.

signup

This operation tells the Server to create a new Account.

Attributes:

domain

optional target Domain name.

userName

the new Account name.

password

the new Account password.

realName

a Real Name of the new Account owner (optional).

recoverPassword

an E-mail address that can be used to recover a forgotten password (optional).

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.

login

Attributes:

domain

optional target Domain name.

method

this attribute specifies the SASL method to use. If this attribute is missing the clear-text (password) method is used.

authData

If the clear-text method is used, this attribute contains the username.
For all other methods, this is a string with base64-encoded SASL protocol data.

password

This attribute is used for the clear-text method only, it contains the user password in the clear-text form.

Example:

C:<login id="A001" authData="user1@example.dom" password="123rtu" />
S:<session id="A001" urlID="12-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith"/>
S:<response id="A001"/>

The Server sends the following data messages:

features

This synchronous data message is sent when the Server processes the listFeatures operation.

Body:

a set of XML elements:

domain

the target Domain name.

sasl

the text body of this element is the name of the SASL mechanism enabled for the target Domain.

starttls

if this element is present, the client can perform the starttls operation.

language

the text body of this element contains the default language selected for the target Domain. If this element is absent, the default (English) language is selected.

signup

if this element is present, the client can perform the signup operation with the target Domain.

session

This message contains information about the newly created session. It is sent before the positive response for the login operation is sent.

Attributes:

urlID

the session ID string. This ID string can be used to access session data via HTTP.

userName

the authenticated Account full name (accountName@domainName).

realName

the authenticated Account user Real Name (this attribute is absent if the Real Name is not specified in the Account Settings).

Examples:

C:<login id="A001" authData="user1@example2.dom" password="rrr123" />
S:<response id="A001" errorCode="account has been moved to a remote system" errorNum="518" />

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.

Example (see RFC2195):

C:<login id="A001" method="CRAM-MD5" />
S:<challenge value="PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+" />
C:<auth id="A001" value="dGltIGI5MTNhNjAyYzdlZGE3YTQ5NWI0ZTZlNzMzNGQzODkw" />
S:<session id="A001" urlID="12-skejlkieuoiuoi-dnciru" userName="user1@example.dom" realName="User J. Smith"/>
S:<response id="A001"/>

noop

This operation does not do anything and it always succeeds.

bye

This operation does not do anything and it always succeeds. After the response message is sent to the client, the Server closes the connection and destroys the current session.

passwordModify

This operation modifies the Account Password and/or the Password Recovery E-mail Address.

Attributes:

oldPassword

the current Account password. The operation verifies this password before attempting any modification.

newPassword

this optional attribute specifies the new password. The password modification operation must be allowed for this Account.

recoveryEMail

this optional attribute specifies the new password recovery E-mail.

SMIMEUnlock

This operation unlocks the Account Private Key stored on the Server.
When the Private Key is unlocked, the Server decrypts encrypted parts of messages retrieved using the folderRead operation.
The Server can also encrypt and/or digitally sign submitted messages.
Note: this operation transfers the unlocking string ("storage password") in clear text. The client application should use this command only over a secure (TLS) connection.
Note: the unlocked Private Key is added to the current session data only, and it is not stored anywhere. If a different session is opened for the same Account, it should unlock the Private Key by itself.

Attributes:

password

the unlocking string (password).

duration

optional attribute - the time (in seconds) to keep the Private Key unlocked; the Private Key is automatically locked aftet this period of time.

SMIMEModifyPassword

This operation changes the password string protecting the Account Private Key in the Server storage. The Account Private Key must be unlocked.
Note: this operation transfers the unlocking string ("storage password") in clear text. The client application should use this command only over a secure (TLS) connection.

Attributes:

password

the new unlocking string (password).

SMIMELock

This operation locks the Account Private Key stored on the Server (it removes the unlocked Private Key from the current session data).
It is recommended to use this operation after a certain period of user inactivity.

clearUploaded

This operation removes one or all files from the "uploaded file set".

Attributes:

uploadID

if this optional parameter is specified, only the file with this fileID is removed from the "uploaded file set".
If this parameter is not specified, all files are removed from the "uploaded file set".

readStrings

This operation reads the vocabulary (words, tags, button names, etc.) stored on the Server. The Server sends a strings data message with the dictionary data (see below).

Attributes:

language

the vocabulary language. If the attribute is missing, the Account Language preference string is used.

readTime

This operation reads the current time from the Server. The Server sends a currentTime message.

readStatus

This operation reads the current Account status. The Server sends a currentStatus message.

listKnownValues

This operation causes the Server to send a knownValues message. This message contains sets of "known values": known Time Zone names, character set names, etc.

cliExecute

This operation executes a Network CLI command.

Body:

the CLI command text

If the CLI command produces a result, the Server sends a cliResult message.

retrieveXML

This operation reads an XML document from a remote server.

Attributes:

url

the URL (http: or https:) of the XML document.

If the document is successfully retrieved, the Server sends a retrievedXML message with the retrieved document content.

spellerList

This operation causes the Server to send speller messages, containing the names of installed spell checkers.

spellerCheck

This operation checks the spelling of an arbitrary text. For each spelling error found, the Server sends a spellerReport message.

Attributes:

speller

the spell checker name.

Body:

the text to check.

The Server can send the following service data messages at any time:

alert

The authenticated account has received an Alert. As soon as the Server sends the Alert data message to the Client, the Alert message is marked as "confirmed".

Body:

the Alert text (in the UTF-8 encoding).

The Server can send the following data messages:

strings

This synchronous data message is sent when the Server processes the readStrings request.

Attributes:

language

the selected langauge.

Body:

a set of string and strings XML elements. Each element has the name attribute - the name (or "key") of the vocabulary element.
String-type vocabulary elements are presented using string elements. The string element body is the vocabulary element value.
Dictionary-type vocabulary elements are presented using strings elements. The strings element body is the set of string XML elements.

Example:
The Client reads the default (english) vocabulary.

C:<readStrings id="A001">
S:<strings id="A001" language="" >
    <string name="AppendButton">Append</string>
    <strings name="AppendModes">
      <string name="simple">Simple Mode</string>
      <string name="advanced">Advanced Mode</string>
    </strings>
  </strings>
S:<response id="A001"/>

currentTime

These messages are sent when the Server processes the readTime request.

Attributes:

gmtTime

the current Server time (GMT).

localTime

the current Server time (in the selected time zone).

currentStatus

These messages are sent when the Server processes the readStatus request.

Body:

a set of XML elements:

messageStore

The information about the Account Message Storage.

Attributes:

used

the currently used storage (in bytes).

limit

the storage quota. This attribute is absent if the quota is set to Unlimited.

PrevLogin

The information about the previous successful login.

Attributes:

gmtTime

the login time (GMT).

localTime

the login time (in the selected time zone).

ip

the network address from which the user logged in.

LastFailedLogin

The information about the last failed login.

Attributes:

gmtTime

the time of the last failed login attempt (GMT).

localTime

the time of the last failed login attempt (in the selected time zone).

ip

the network address from which the failed attempt to log in was made.

RulesAllowed, SignalRulesAllowed, RPOPAllowed, PWDAllowed

The effective Account settings data. These elements do not have attributes, and their text body is the setting value.

option

zero, one, or several XML elements. The element body is a string, specifying an option enabled for the current Account:

S/MIME

Secure Mail services are enabled.

SMIMEActive

Secure Mail services are unlocked.

SMIMEInactive

Secure Mail services are locked (but the Account does have a Private PKI key).

WebCAL

Calendaring services are enabled.

WebSite

Web access to File Storage is enabled.

knownValues

These messages are sent when the Server processes the listKnownValues request.

Body:

a set of XML elements:

tzid

the element name attribute specifies a known Time Zone name;

charset

the element name attribute specifies a known character set name;

mailRuleAllowed

the element name attribute specifies a supported Allowed Mail Rule mode. Each mode defines which Mail Rule actions the user is allowed to modify; Elements are sorted, with the "most restrictive" mode listed first.

mailRuleCondition

the element name attribute specifies a supported Mail Rule condition.

mailRuleAction

the element name attribute specifies a supported Mail Rule action; the element allowedSet attribute specifies the enabling Allowed Mail Rule name. The user can modify a Rule containing this operation only if the user Account RulesAllowed setting value is the specified or a less restrictive Allowed Mail Rule mode.

signalRuleAllowed, signalRuleCondition, signalRuleAction

the same elements as the mailRuleAllowed, mailRuleCondition, mailRuleAction elements, but for the Signal Rules.

cliResult

These messages are sent when the Server processes the cliExecute request.

Body:

text presentation of the CLI command output.

retrievedXML

These messages are sent when the Server processes the retrieveXML request.

Attributes:

url

the document URL.

Body:

one XML element with the retrieved document.

speller

These messages are sent when the Server processes the spellerList request.

Attributes:

speller

the spell checker name; usually - the language name or the dialect name (such as English-US or French-CA).

spellerReport

These messages are sent when the Server processes the spellerCheck request and detects a spelling error.

Attributes:

position

the misspelled word position in the supplied text.

size

the misspelled word size in the supplied text (in bytes).

Body:

zero, one, or more guess XML elements. The text body of each element is a suggested replacement for the misspelled word.

Note: the supplied text is XML-decoded first, and the attributes specify the word position and size in the resulting decoded text (which must use UTF-8 character set).

mailboxCreate

This operation creates a new Mailbox.

Attributes:

mailbox

this attribute specifies the new Mailbox name.

mailboxClass

this optional attribute specifies the Mailbox class.

mailboxRename

This operation renames a Mailbox.

Attributes:

mailbox

this attribute specifies the existing Mailbox name.

newName

this attribute specifies the new Mailbox name.

children

if this optional attribute is present, all Mailbox "children" (nested Mailboxes) are renamed, too.

mailboxRemove

This operation removes a Mailbox.

Attributes:

mailbox

an existing Mailbox name.

children

if this optional attribute is present, all Mailbox "children" (nested Mailboxes) are removed, too.

mailboxList

This operation makes the Server send a mailbox data message (see below) for each visible Mailbox (the Mailboxes for which the authenticated Account has the lookup access right).

Attributes:

filter

this optional attribute specifies the filter string in the IMAP protocol format.

mailboxClass

if this optional attribute is specified, only the Mailboxes of the specified class are listed. Specify an empty string value to list only "mail"-class Mailboxes.

mailboxSubList

This operation makes the Server send a mailboxSubscription data message (see below) for each element in the Account mailbox subscription set. Note that Mailboxes in this set may or may not exist.

Attributes:

filter

this optional attribute specifies the filter string in the IMAP protocol format.

mailboxSubUpdate

This operation modifies Account mailbox subscription set.

Body:

a set of mailboxSubscription elements.

Attributes:

mailbox

a Mailbox name in the UTF-8 character set.

mode

if this attribute value is add the mailbox name is added to the mailbox subscription set (unless the set already contains this name).
otherwise, the mailbox name is removed from the mailbox subscription set.

mailboxRightsGet

This operation makes the Server send a mailboxRight data message (see below) with the user access rights for the specified Mailbox.

Attributes:

mailbox

an existing Mailbox name.

mailboxACLList

This operation makes the Server send a mailboxACL data message (see below) with the Mailbox Access Control List data.

Attributes:

mailbox

an existing Mailbox name.

mailboxACLUpdate

This operation modifies the Mailbox Access Control List for the specified Mailbox.

Attributes:

mailbox

an existing Mailbox name.

Body:

A set of aclElem XML elements:

Attributes:

pattern

the ACL element "name". It can be an Account name, a name with "+" or "-" prefix, etc. See the Mailbox Access Control Lists section for more details.

mode

if this optional attribute value is add, the specified rights are added to the right set already specified for this ACL element. If the ACL element did not exist, it is created.
if this optional attribute value is sub, the specified rights are removed from the right set specified for this ACL element.
if this optional attribute value is clear, this ACL element is removed.
if this optional attribute has any other value, or if this attribute is absent, the specified rights replace the right set already specified for this ACL element. If the ACL element did not exist, it is created.

Body:

a string; each symbol specifies a Mailbox Access Right.

The Server sends the following data messages:

mailbox

These synchronous data messages are sent when the Server processes the mailboxList request.

Attributes:

mailbox

the Mailbox name in the UTF-8 character set.

UIDVALIDITY, MESSAGES, UIDNEXT, UNSEEN, INTERNALSIZE, OLDEST, CLASS, MEDIA, UNSEENMEDIA

standard and extended IMAP Mailbox attributes

pureFolder

this attribute exists and has the YES value if the Mailbox is a pure folder - i.e. it cannot contain messages, but it can contain sub-Mailboxes.

mailboxSubscription

These messages are sent when the Server processes the mailboxSubList request.

Attributes:

mailbox

the Mailbox name in the UTF-8 character set.

mailboxRights

This message is sent when the Server processes the mailboxRightsGet request.

Attributes:

mailbox

the Mailbox name.

Body:

a string; each symbol specifies an effective Mailbox Access Right granted to the current user.

mailboxACL

This message is sent when the Server processes the mailboxACLList request.

Attributes:

mailbox

the Mailbox name.

Body:

A set of aclElem XML elements, one element for each Mailbox Access Control List element:

Attributes:

pattern

the ACL element "name". It can be an Account name, a name with "+" or "-" prefix, etc. See the Mailbox Access Control Lists section for more details.

Body:

a string; each symbol specifies a Mailbox Access Right granted to or revoked from the "name".

• A001: the Client asks the Server to create the MyNotes Notes-type Mailbox.
• A002: the Client asks the Server to rename the MyNotes Mailbox into SharedNotes.
• A003: the Client asks the Server to grant the Lookup and Select rights for the SharedNotes Mailbox to users user1 and user2.
• A004: the Client asks the Server to add the Delete and Insert rights for the SharedNotes Mailbox to user user1 and to revoke the Select right from the user user2.
• A005: the Client asks the Server to retrieve the ACL data for the SharedNotes Mailbox.

folderOpen

This operation opens the specified Mailbox as a "Folder".
A Folder represents a Server Mailbox, with all messages being sorted and, optionally, filtered.
Each folder has a name, and one session cannot have two folders with the same name. On the other hand, the same session can open the same Mailbox as two different folders (with different names). For example, an application may use one folder to show the Mailbox content sorted by the Date field, while maintaining a separate window where it shows the same Mailbox, but only the messages containing the Business tag in the Keywords field, with all these messages sorted by the From field.
When Mailbox messages are added, removed, or updated, the Server reports these updates to all clients that have opened that Mailbox as a Folder.
Each folder sends its update notifications independently, so the client does not need to know that two folders are presenting different views on the same Server Mailbox.

Attributes:

folder

the name for the new Folder to be opened. A client can use an arbitrary string as a Folder name.

mailbox

the Mailbox name. If this attribute is not specified, the folder name is used.

mailboxClass

an optional attribute. If the specified Mailbox does not exist and this optional attribute is specified, the specified Mailbox is created.
If this attribute value is a non-empty string, that value is assigned as the Mailbox Class to the newly created Mailbox.

sortField

the name of a message header field to use for Mailbox sorting.

sortOrder

if this optional attribute is specified and it has the desc value, the sorting order is reversed.

filter

if this optional attribute is specified, only the Mailbox messages matching this attribute value are included into the folder.

filterField

if this optional attribute is specified, its value specifies the message header field to compare with the filter attribute. Only the messages containing the specified field and with the field value matching the filter attribute value are included into the folder.
If this attribute value is FLAGS, the filter attribute value should contain a comma-separated list of message flags names and/or negative names. Only the messages with the specified flags set and the specified negative flags not set are included into the Server view. For example, the filter="Media,Unseen" attribute will tell the Server to build a view using only the messages with the Media flags set and the Seen flag not set.
If this attribute value is body, messages containing the filter attribute value in any message body part are included into the server view.
If this attribute is missing, messages containing the filter attribute value in message body part, or in any message header field are included into the server view.

Body:

the request body should contain one or more <field> elements.
Each element body should contain a name of a header field to be retrieved for each message.
These fields are called viewer fields.

The following sortField and viewer fields can be specified:

• From, To, Cc, Bcc, Reply-To, Sender, Return-Path, or other Email-field name. If a message header contains the specified Email-field, it is parsed. If the field contains a "comment" (i.e. a "real name"), it is used. Otherwise, the parsed E-mail address is used.
• Date, Resent-Date. The field date value is converted to GMT. When elements with these field values are sent within a folderReport message, they contain the localTime attribute specifying the field value in the Time Zone selected for the current user.
• any other E-mail header field name (Subject, X-Mailer, etc). The field MIME-decoded value is used.
• E-From, E-To, or other E-Email-field name. If a message header contains the specified Email-field, it is parsed, and the parsed E-mail address is used.
• Pty. The X-Priority field value is converted to the strings High, Low, or to an empty string.
• UID. The message metadata - its UID (unique ID) in the Mailbox.
• SIZE. The message metadata - its "raw" size in the Mailbox.
• INTERNALDATE. The message metadata - its "timestamp". It is formatted in the same way as the Date element.
• FLAGS the message metadata attribute values are used.
  See the Mailboxes section for more information on the Mailbox message flags.

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 element, or it can include one or more index elements, but it cannot include both UID and index elements.

folderBrowse

This operation makes the Server send data messages for the specified index (position) interval in an open Folder.

Attributes:

folder

the Folder name.

Body:

a message set (see above). Only index elements are allowed in this message set.

The Server sends a folderReport data message for each index in the specified range. The data message attributes specify the message index (position) in the Folder and the message UID.
The folderReport data message body contains the viewer fields values.

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:

folderSync

This operation tells the Server to send all pending Folder modifications to the client.

Attributes:

folder

the Folder name.

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.

messageCopy

This operation copies messages from an open Folder to a target Mailbox.
Note: the target is specified as a Mailbox, not as a Folder.

Attributes:

folder

the source Folder name.

targetMailbox

the target Mailbox name.

encrypt

an optional parameter. If set to yes, the messages are copied encrypted, using the current user S/MIME certificate.

Body:

a message set (see above).

messageMove

This operation is the same as the messageCopy operation, but if the messages have been copied successfully, the operation deletes the original messages.

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.

messageMark

This operation modifies Mailbox message flags in an open Folder.

Attributes:

folder

the Folder name.

flags

this attribute specifies the Mailbox message flags to add or delete. Several operations can be specified, separated with the comma symbol. See the Mailbox section for more details.

Body:

a message set (see above).

messageRemove

This operation removes messages from an open Folder.

Attributes:

folder

the Folder name.

Body:

a message set (see above).

The operation checks the DeleteMode Account preference and acts depending on its value:

• Immediately - the messages are physically removed from the Folder Mailbox.
• Move To Trash - the messages are moved to the Trash Mailbox (its name is specified with the TrashBox Account preference). If the specified Folder is the Trash Mailbox itself, the messages are physically removed.
• Mark - the messages are marked with the Deleted flag.

folderExpunge

This operation removes all messages marked with the Deleted flag from the Folder Mailbox.
Note: it removes ALL marked Mailbox messages, not only the messages visible in this Folder.

Attributes:

folder

the Folder name.

folderClose

This operation closes an open Folder.

Attributes:

folder

the Folder name.

folderReopen

This operation re-builds an open Folder by re-scanning its Mailbox using different sorting and filtering parameters.

Attributes:

folder

the Folder name.

sortField, sortOrder, filter, filterField

these attributes have the same meaning as the same folderOpen operation attributes.

Body:

the request body should contains at least one <field> element, these elements specify the new viewer fields set. If no <field> element is specified, the viewer fields set is not modified.

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:

folderReport

These messages are sent synchronously when a Folder is being opened or re-opened, and when the client sends a folderBrowse or a folderSync request.
These messages are sent asynchronously when a Folder status changes (messages are added, removed, or updated), in this case its mode attribute is set to notify.

Attributes:

folder

the Folder name.

mode

this optional attribute specifies the type of notification.

• If the attribute value is init then the messages attribute specifies the total number of messages in the Folder.
  This is a synchronous data message sent when a Folder is being opened or re-opened.
• If the attribute value is notify some Mailbox messages have been added, modified, or deleted.
  This message is sent as an asynchronous data message.
  The client is expected to send the folderSync request for this Folder.
• If the attribute value is removed then the index and UID attributes specify the message removed from the Folder.
  This data message is sent only in response to the folderSync request.
  The client should immediately update its internal view: for all messages with the index value larger than the specified index attribute value, the index value is decreased by 1.
• If the attribute value is added then the index and UID attributes specify the message added to the Folder.
  This data message is sent only in response to the folderSync request.
  The client should immediately update its internal view: for all messages with the index value equal or larger than the specified index attribute value, the index value is increased by 1.
• If the attribute value is updated or the attribute is missing, then the index and UID attributes specify a Mailbox message and the body contains the message viewer field values.

index

the message index in this Folder.
This attribute is not present when the mode attribute value is init.

UID

the message UID (unique ID).
This attribute is not present when the mode attribute value is removed, updated, or added.

messages

the total number of messages in the Folder.
This attribute is present when the mode attribute value is init, removed, or added.

Body:

The body is present when the mode attribute value is updated or added.
It contains a set of elements with viewer field values.

• A001: the Client asks the Server to open the INBOX Mailbox as Folder "INBOX" and to sort it by the INTERNALDATE 'field' (this is not an actual message field, but a message metadata element - it specifies the time when the message was added into the Mailbox). The Client informs the Server that it needs to retrieve the FLAGS, From, and Subject fields of Mailbox messages.
• the Server opens the INBOX Mailbox and sorts it; the Server informs the Client that the Folder has 234 messages.
• A002: the Client asks the Server to send it data from the first 4 Folder messages, and the Server sends that information to the Client.
• while the Server was processing this request, one message was added to the Mailbox.
• after the Server has sent the response message, the Folder messages number 2 and 35 were deleted.
• A003: the Client asks the Server to send it data from the first 4 messages in the sorted view (again).
• A004: the Client asks the Server to send it all Folder modifications.
• The Server informs the Client about the message number 35 being removed. The Client should remove the element number 35 from its internal view table and update the information on its screen if necessary. The total number of Folder messages has changed to 233.
• The Server informs the Client about the message number 2 being removed. The Client should remove the element number 2 from its internal view table. The message number 3 becomes the message number 2, the message number 4 becomes the message number 3, etc.
• The Server adds a newly added message to the Folder and informs the Client that it has inserted the message as the message number 1. The Client should update its internal view table by inserting a new element as the element number 1. The element number 1 becomes the element number 2, the element number 2 becomes the element number 3, etc.
• A005: the Client asks the Server to send it data from the first 4 messages in the Folder (again).

Example 2:

• A010: the Client asks the Server to copy 3 messages from the already opened INBOX Mailbox to the Archive Mailbox
• The Archive Mailbox appears to be opened, and the Server sends a Mailbox notification message to the Client

Example 3:

• A020: the Client asks the Server to mark 3 messages (UIDs 512, 123, and 976) with the Deleted flag.
• The Server sets these flags, and it sends a Mailbox notification message to the Client.
• A021: the Client asks the Server to send it all Mailbox modifications.
• The Server sends the updated information for the messages with UID 512 and 976. The message with the UID 123 already had the Deleted flag set, so this request has not modified that message and the Server does not send information for this message.
• A022: the Client asks the Server to expunge the Mailbox.
• The Server deletes the messages with UIDs 512, 123, and 976, as well as message with UIDs 446 and 756 which also happened to have the Deleted flag set. The Server sends a Mailbox notification message to the Client.
• A023: the Client asks the Server to send it all Mailbox modifications.
• The Server sends data messages informing the client that it has removed the messages with UIDs 512, 123, 976, 446, and 756 from its sorted Mailbox view.
• A024: the Client closes the INBOX Mailbox.

folderRead

This operation tells the Server to retrieve a Message or its part.

Attributes:

folder

the Folder name.

UID

the message UID.

totalSizeLimit

the maximum total size of all message parts returned.

messageAppend

This operation tells the Server to compose a Message and append it to an open folder or to an arbitrary Mailbox.

Attributes:

folder

the target Folder name. If specified, the targetMailbox attribute is ignored.

targetMailbox

the target Mailbox name. It must be specified if the folder attribute is absent.

mailboxClass

this optional attribute can be specified if the targetMailbox attribute is specified.
If the target Mailbox does not exist and this optional attribute is specified, the target Mailbox is created. If this attribute value is a non-empty string, the value is assigned as the Mailbox Class to the newly created Mailbox.

flags

this optional attribute specifies the message flags the newly created message will have in the Mailbox. Several flags can be specified, separated with the comma symbol. See the Mailbox section for more details.

internalDate

this optional attribute specifies the "internal timestamp" for the newly created message. If this parameter is not specified, the current time is used.

replacesUID

this optional attribute can be specified if the folder attribute is specified.
If the message has been successfully composed and appended to the Folder, the message with the replacesUID UID is removed from the Folder Mailbox.

report

this optional attribute can be specified if the folder attribute is specified. If this attribute is specified, it should have the uid value.
If the message has been successfully composed and appended to the Folder, the Server sends the synchronous messageAdded message containing the UID of the newly appended message.

Body:

The XML presentation of the Message (the EMail data).
The text parts of the message XML presentation should use the Line Feed (0x0A) symbol as the EOL (end of line) symbol.
If the XML presentation does not include the Message-ID or Date fields, the server creates these message fields itself.

Example:
The Client appends a simple text message to the Mailbox "Sent", with the Seen and Answered flags. If the Mailbox does not exist, it is created.

C:<messageAppend id="A001" targetMailbox="Sent" flags="Seen,Answered" mailboxClass="" >
    <EMail>
      <From realName="Sender Name">fromName@domain</From><Subject>I'll be there!</Subject>
      <To realName="Recipient Name">toName@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
      <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
    </EMail>
  </messageAppend>
S:<response id="A001"/>

This operation adds the following message to the Mailbox:

From: "Sender Name" <fromName@domain>
Subject: I'll be there!
To: "Recipient Name" <toName@domain>
X-Mailer: SuperClient v7.77
Date: Wed, 21 Jun 2006 21:51:24 -0800
Message-ID: <ximss-38150012@this.server.dom>
Content-Type: text/plain; charset="utf-8"

Dear Susan,

I will come to your place tomorrow, thank you for the invitation!
Mary.

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. If you do not explicitly specify the type and subtype attributes, they are copied from the Content-Type field of the HTTP request used to upload the file.

Example:
The client first uploads 2 files - test.gif (using uploadID att01) and sample.pdf (using uploadID att02). Then the client appends a message to the "Drafts" Folder, with the "Draft" message flag, replacing the existing message with the 578 UID.
The message contains some text in the alternative (plain and html) formats, and the uploaded files as attachments.
The client requests the Server to send the UID of the newly created message (756).
While the client was adding the new message, a different process added some other message (with UID=755) to the "Drafts" Folder Mailbox.
The client then clears the "uploaded file set", and re-syncs its state with the "Drafts" Folder.

C:<messageAppend id="A001" folder="Drafts" flags="Draft" replacesUID="578" report="uid" >
    <EMail>
      <From realName="Sender Name">fromName@domain</From><Subject>Text with attachments</Subject>
      <To realName="Recipient Name">toName@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
      <MIME type="multipart" subtype="mixed">
        <MIME type="multipart" subtype="alternative">
          <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
          <MIME type="text" subtype="html">&lt;html&gt;&lt;body&gt;&lt;i&gt;Dear Susan,&lt;/i&gt;&lt;p&gt;I will come to your place tomorrow, thank you for the invitation!&lt;p&gt;&lt;i&gt;Mary.&lt;/i&gt;</MIME>
        </MIME>
        <MIME uploadID="att01" />
        <MIME uploadID="att02" type="application" subtype="pdf" />
      </MIME>
    </EMail>
  </messageAppend>
S:<folderReport folder="Drafts" mode="notify" />
S:<messageAdded id="A001" folder="Drafts" UID="756" />
S:<response id="A001"/>
C:<clearUploaded id="A002" />
S:<response id="A002"/>
C:<folderSync id="A003" folder="Drafts"/>
S:<folderReport id="A003" folder="Drafts" index="17" UID="578" mode="removed" messages="301"/>
S:<folderReport id="A003" folder="Drafts" index="127" UID="755" mode="added" messages="302">
    <UID>755</UID>
    <From>Other Name</From>
  </folderReport>
S:<folderReport id="A003" folder="Drafts" index="17" UID="756" mode="added" messages="303">
    <UID>756</UID>
    <From>Sender Name</From>
  </folderReport>
S:<response id="A003"/>

This operation adds the following message to the Mailbox:

From: "Sender Name" <fromName@domain>
Subject: Text with attachments
To: "Recipient Name" <toName@domain>
X-Mailer: SuperClient v7.77
Date: Wed, 21 Jun 2006 21:59:55 -0800
Message-ID: <ximss-38330025@my.server.domain>
Content-Type: multipart/mixed; boundary="_===38330025====my.server.domain===_"

--_===38330025====my.server.domain===_
Content-Type: multipart/alternative; boundary="_===38330025-X====my.server.domain===_"


--_===38330025-X====my.server.domain===_
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

Dear Susan,

I will come to your place tomorrow, thank you for the invitation!
Mary.

--_===38330025-X====my.server.domain===_
Content-Type: text/html; charset="utf-8"
Content-Transfer-Encoding: 8bit

<html><body><i>Dear Susan,</i><p>I will come to your place tomorrow, thank you for the invitation!<p><i>Mary.</i>
--_===38330025-X====my.server.domain===_--

--_===38330025====my.server.domain===_
Content-Type: image/gif; name="test.gif"
Content-Disposition: attachment; filename="test.gif"
Content-Transfer-Encoding: base64

R0lGODlhCgAMAPf/AP//////zP//mf//Zv//M///AP/M///MzP/Mmf/MZv/MM//MAP+Z//+Z
zP+Zmf+ZZv+ZM/+ZAP9m//9mzP9mmf9mZv9mM/9mAP8z//8zzP8zmf8zZv8zM/8zAP8A//8A
zP8Amf8AZv8AM/8AAMz//8z/zMz/mcz/Zsz/M8z/AMzM/8zMzMzMmczMZszMM8zMAMyZ/8yZ
zMyZmcyZZsyZM8yZAMxm/8xmzMxmmcxmZsxmM8xmAMwz/8wzzMwzmcwzZswzM8wzAMwA/8wA
zMwAmcwAZswAM8wAAJn//5n/zJn/mZn/Zpn/M5n/AJnM/5nMzJnMmZnMZpnMM5nMAJmZ/5mZ
zJmZmZmZZpmZM5mZAJlm/5lmzJlmmZlmZplmM5lmAJkz/5kzzJkzmZkzZpkzM5kzAJkA/5kA
zJkAmZkAZpkAM5kAAGb//2b/zGb/mWb/Zmb/M2b/AGbM/2bMzGbMmWbMZmbMM2bMAGaZ/2aZ
zGaZmWaZZmaZM2aZAGZm/2ZmzGZmmWZmZmZmM2ZmAGYz/2YzzGYzmWYzZmYzM2YzAGYA/2YA
zGYAmWYAZmYAM2YAADP//zP/zDP/mTP/ZjP/MzP/ADPM/zPMzDPMmTPMZjPMMzPMADOZ/zOZ
zDOZmTOZZjOZMzOZADNm/zNmzDNmmTNmZjNmMzNmADMz/zMzzDMzmTMzZjMzMzMzADMA/zMA
zDMAmTMAZjMAMzMAAAD//wD/zAD/mQD/ZgD/MwD/AADM/wDMzADMmQDMZgDMMwDMAACZ/wCZ
zACZmQCZZgCZMwCZAABm/wBmzABmmQBmZgBmMwBmAAAz/wAzzAAzmQAzZgAzMwAzAAAA/wAA
zAAAmQAAZgAAM+4AAN0AALsAAKoAAIgAAHcAAFUAAEQAACIAABEAAADuAADdAAC7AACqAACI
AAB3AABVAABEAAAiAAARAAAA7gAA3QAAuwAAqgAAiAAAdwAAVQAARAAAIgAAEe7u7t3d3bu7
u6qqqoiIiHd3d1VVVURERCIiIhEREQAAACH+HUdpZkJ1aWxkZXIgMC40IGJ5IFl2ZXMgUGln
dWV0ACH5BAUEALkALAAAAAAKAAwAAAg1AHPlG0gw379cAgEoXHgw4UKFDfM9hIhQ4sSIEwFg
vCiQ4L+PIC1m/Cfx34qQGkVeBMkSZEAAOw==

--_===38330025====my.server.domain===_
Content-Type: application/pdf; name="sample.pdf"
Content-Disposition: attachment; filename="sample.pdf"
Content-Transfer-Encoding: base64

JVBERi0xLjIgDSXi48/TDQogDTggMCBvYmoNPDwNL0xlbmd0aCA5IDAgUg0vRmlsdGVyIC9G
bGF0ZURlY29kZSANPj4Nc3RyZWFtDQpIic2X3VLjuBaFn6DfQXfDuaCP5X9fJiQEpkNI2eFQ
[......skipped......]
Ug0vSUQgWzxjNjIyNzFiYzY4YmFlYjY3YzBkM2ViNTk4MjJiZTA4Nz48YzYyMjcxYmM2OGJh
ZWI2N2MwZDNlYjU5ODIyYmUwODc+XQ0+Pg1zdGFydHhyZWYNODc1NA0lJUVPRg0=

--_===38330025====my.server.domain===_--

To create messages with MIME parts (attachments) copied from other messages stored on the Server, use the copyMIME element instead of a MIME element:

copyMIME

Attributes:

folder or calendar

the name of an open Folder or an open Calendar.

UID

the message UID.

partID

this optional attribute specifies the message part to copy. If it is not specified, the entire message is copied.

Example:
The Client stores a note in the "Notes" Mailbox, appending parts 3 and 4 (attachments) of the message 156 stored in the INBOX folder:

C:<messageAppend id="A001" targetMailbox="Notes" flags="Seen">
    <EMail>
      <From realName="Sender Name">fromName@domain</From>
      <Subject>Vacation Pictures</Subject>
      <MIME type="multipart" subtype="mixed">
        <MIME type="text" subtype="plain">The first part of the underwater shots.</MIME>
        <copyMIME folder="INBOX" UID="156" partID="3"/>
        <copyMIME folder="INBOX" UID="156" partID="4"/>
      </MIME>
    </EMail>
  </messageAppend>
S:<response id="A001"/>

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 the type and subtype attributes, and you should specify the disposition-filename attribute, as the fileName attribute is not used to form the attachment name.

Example:
The Client stores a note in the "Notes" Mailbox, appending the file private/MyFile.jpg as the photo.jpg attachment:

C:<messageAppend id="A001" targetMailbox="Notes" flags="Seen">
    <EMail>
      <From realName="Sender Name">fromName@domain</From>
      <Subject>Vacation Pictures</Subject>
      <MIME type="multipart" subtype="mixed">
        <MIME type="text" subtype="plain">Atatched please find the images I have stored as files.</MIME>
        <MIME type="image" subtype="jpeg" fileName="private/MyFile.jpg" disposition-filename="photo.jpg" />
      </MIME>
    </EMail>
  </messageAppend>
S:<response id="A001"/>

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:

C:<messageAppend id="A001" targetMailbox="Notes" flags="Seen">
    <EMail>
      <Subject>Test text</Subject>
      <MIME type="text" subtype="plain" format="flowed">This is a very long long long long long long long long long long superlong long long long long long long line, followed with a shorter line:
This is a shorter line.</MIME>
    </EMail>
  </messageAppend>
S:<response id="A001"/>

This operation adds the following message to the Mailbox:

Subject: Test text
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; format="flowed"; charset="utf-8"

This is a very long long long long long long long long long long superlong
long long long long long long line, followed with a shorter line:
This is a shorter line.

(there is a trailing space after the "superlong" word)

To create a signed message, make sure that S/MIME Private key is unlocked, and specify the sign attribute in the topmost EMail element.

C:<messageAppend id="A001" targetMailbox="Sent" flags="Seen,Answered" >
    <EMail sign="yes">
      <From realName="Sender Name">fromName@domain</From><Subject>I'll be there!</Subject>
      <To realName="Recipient Name">toName@domain</To><X-Mailer>SuperClient v7.77</X-Mailer>
      <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
    </EMail>
  </messageAppend>
S:<response id="A001"/>

This operation adds the following message to the Mailbox:

From: "Sender Name" <fromName@domain>
Subject: I'll be there!
To: "Recipient Name" <toName@domain>
X-Mailer: SuperClient v7.77
Content-Type: multipart/signed; protocol="application/x-pkcs7-signature"; micalg="SHA1"; boundary="_===signed==2610002====my.server.domain===_"

This is a signed S/MIME message

--_===signed==2610002====my.server.domain===_
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

Dear Susan,

I will come to your place tomorrow, thank you for the invitation!
Mary.

--_===signed==2610002====my.server.domain===_
Content-Type: application/x-pkcs7-signature; name="smime.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime.p7s"

MIIE6wYJKoZIhvcNAQcCoIIE3DCCBNgCAQExCzAJBgUrDgMCGgUAMAsGCSqGSIb3DQEHAaCC
ArkwggK1MIICX6ADAgECAgcAk9RF+n/7MA0GCSqGSIb3DQEBBAUAMIG6MQswCQYDVQQGEwJV
UzELMAkGA1UECBMCQ0ExFDASBgNVBAcTC01pbGwgVmFsbGV5MSIwIAYDVQQKExlDb21tdW5p
.............
gIbXNT64QJ+gEYkI9mnePiS1TUOOzGYfXaLy1pqm6jmzBUt7/3UY8ZNHVIwM0Fzj7NwzqM1U
Esbkyi3WHNxTZ4HSCs8J2enGQEZjNWHOuX96xQojYGLV0m5Z/FatV9GQ8jNVBmQ9xYGKxmlY
jT9ze/oHyKuj7KR8QrgQSYiJVnn7

--_===signed==2610002====my.server.domain===_--

messageSubmit

This operation tells the Server to compose a Message and submit it to the Queue for delivery. A message copy can be stored in a Mailbox.

Attributes:

useDSN

if this optional attribute is present, and its value is yes, delivery reports are generated when a message is delivered, or if delivery fails.
If this attribute is absent, delivery reports are generated only when message delivery fails.

targetMailbox, mailboxClass, flags, internalDate

if the optional targetMailbox attribute is specified, then the composed message is appended to the specified Mailbox. These attributes have the same meaning as for the messageAppend operation.

Body:

The XML presentation of the Message (the EMail element), and zero, one, or several Envelope-To elements. Each Envelope-To element should have a text body - the E-mail address to send the message to.
If no Envelope-To element is specified, the message is sent to the addresses specified in all addresses specified in the To, Cc, and Bcc elements inside the EMail element.
When the message MIME text is generated, all addresses from the Bcc elements are skipped.

Example:
The Client sends a simple text message to the toName@domain address and the Bcc copy is sent to bccName@domain address. The Client requests delivery notification.

C:<messageSubmit id="A001" useDSN="yes" >
    <EMail>
      <From realName="Sender Name">fromName@domain</From>
      <Subject>I'll be there!</Subject>
      <To realName="Recipient Name">toName@domain</To>
      <X-Mailer>SuperClient v7.77</X-Mailer>
      <Bcc>bccName@domain</Bcc>
      <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
    </EMail>
  </messageSubmit>
S:<response id="A001"/>

Example:
The Client sends a simple text message to the a1@domain and a2@domain addresses (different from the addresses specified in the To and Cc elements).
The message copy should be stored in the "Sent Items" Mailbox with the "Seen" flag.
The Client requests delivery notification.

C:<messageSubmit id="A001" targetMailbox="Sent Items" flags="Seen" >
    <Envelope-To>a1@domain address</Envelope-To>
    <Envelope-To>a2@domain address</Envelope-To>
    <EMail>
      <From realName="Sender Name">fromName@domain</From>
      <Subject>I'll be there!</Subject>
      <To realName="Recipient Name">toName@domain</To>
      <X-Mailer>SuperClient v7.77</X-Mailer>
      <Cc>ccName@domain</Cc>
      <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;I will come to your place tomorrow, thank you for the invitation!&#x0A;Mary.&#x0A;</MIME>
    </EMail>
  </messageSubmit>
S:<response id="A001"/>

Example:
The Client forwards the message 156 stored in the INBOX folder to the a1@domain address:

C:<messageSubmit id="A001">
    <EMail>
      <From realName="Sender Name">fromName@domain</From>
      <Subject>Fwd: Sorry, I cannot make it :-(</Subject>
      <To realName="Recipient Name">a1@domain</To>
      <X-Mailer>SuperClient v7.77</X-Mailer>
      <MIME type="multipart" subtype="mixed">
        <MIME type="text" subtype="plain">Dear Susan,&#x0A;&#x0A;Attached please find the message I received this morning...&#x0A;Mary.&#x0A;</MIME>
        <copyMIME folder="INBOX" UID="156" />
    </EMail>
  </messageSubmit>
S:<response id="A001"/>

This operation adds the following message to the Mailbox:

From: "Sender Name" <fromName@domain>
Subject: Fwd: Sorry, I cannot make it :-(
To: "Recipient Name" <toName@domain>
X-Mailer: SuperClient v7.77
Date: Wed, 21 Jun 2006 22:55:24 -0800
Message-ID: <ximss-38150012@this.server.dom>
Content-Type: multipart/mixed; boundary="_===38330025====my.server.domain===_"

--_===38330025====my.server.domain===_
Content-Type: text/plain; charset="utf-8"

Dear Susan,

Attached please find the message I received this morning...
Mary.

--_===38330025====my.server.domain===_
Content-Type: message/rfc822

From: "Barbara Smith" <barbara@domain>
Subject: Sorry, I cannot make it :-(
To: "Sender Name" <fromName@domain>
X-Mailer: OtherClient v8.88
Date: Wed, 21 Jun 2006 21:51:24 -0800
Message-ID: <zzzzzzzzz@other.server.dom>
Content-Type: text/plain; charset="utf-8"

Mary,

Sorry, but I will be out of town tomorrow...

Barbara.

--_===38330025====my.server.domain===_--

messageRedirect

This operation tells the Server to compose a copy of a message stored in a Mailbox, and to submit it to the Queue for delivery.

Attributes:

folder

the Folder name.

UID

the message UID.

Body:

A set of one or more To elements specifying the recipient address(es).

Example:
The Client redirects the message 156 stored in the INBOX folder to the a1@domain and a2@domain addresses:

C:<messageRedirect id="A001" folder="INBOX" UID="156">
    <To realName="Recipient Name">a1@domain</To>
    <To realName="Recipient-2">a2@domain</To>
  </messageRedirect>
S:<response id="A001"/>

messageForward

This operation tells the Server to compose a copy of a message stored in a Mailbox, and to submit it to the Queue for delivery. The operation uses the same attributes as the messageRedirect operation.

messageConfirm

This operation tells the Server to compose an MDN (Message Disposition Notification) report for a message stored in a Mailbox, and to submit it to the Queue for delivery.
Client applications should use this operation when:

• the message has been displayed to the user, and
• the message has the Disposition-Notification header field, and
• the message does not have the $MDNSent Message Flag, and
• the user Preference SendMDNMode is set to Automatically or it is set to Manually and the user has explicitly requested to send a confirmation.

Attributes:

folder

the Folder name.

UID

the message UID.

type

this attribute should be set to auto (if the confirmation is generated automatically) or to manual (if the user has explicitly requested to send a confirmation).

The Server sends the following data messages:

folderMessage

This synchronous data message is sent when the Server processes the folderRead request.

Attributes:

folder

the Folder name.

UID

the message UID.

Body:

The XML presentation of the Message.

messageAdded

These synchronous data messages are sent when the Server processes the messageAppend and contactAppend requests with the report attributes set.

Attributes:

folder

the Folder name.

UID

the newly added message UID.

Note: even if this data message is sent, the Server will still send asynchronous folderReport data message notifying the client about a new message added to the Folder. The client SHOULD use the folderSync operation to synchronize its internal view with the Server view, otherwise the newly added message will not be "seen" in the Folder.

MIME parts with the text type and x-vcard or dictionary subtype contain vCard elements.

To include vCard data into a message (using the messageAppend, messageSubmit operations) include a MIME element with type="text" and subtype="directory". The element body should contain one or more vCard elements.

• the Subject field contains the vCard FN property.
• the To field contains the vCard EMAIL property.
• the X-Has-Certificate field exists and contains the true value if the vCard contains a KEY property.

Use the following operations to compose and store such a special message:

contactAppend

This operation composes a special E-mail message containing the vCard data as its body, forms all necessary E-mail message header fields and stores the resulting message in the specified Mailbox.

Attributes:

folder

the target Folder name. If specified, the targetMailbox attribute is ignored.

targetMailbox

the target Mailbox name. It must be specified if the folder attribute is absent.
if the target Mailbox does not exist, it is created.

flags, replacesUID, report

these optional attributes have the same meaning as the same messageAppend attributes. If the flags attribute is not specified, its value assumed to be Seen.

Body:

exactly one vCard element.

The operation adds the vCard UID and FN attributes if they are missing.

Example 1:
The Client appends a vCard object to the Contacts Mailbox.

C:<contactAppend id="A011" targetMailbox="Contacts" >
    <vCard>
      <NAME>Bjorn Jensen</NAME>
      <N><FAMILY>Jensen</FAMILY><GIVEN>bjorn</GIVEN>
        <MIDDLE>A</MIDDLE><PREFIX>Mr.</PREFIX><SUFFIX>II</SUFFIX></N>
      <EMAIL><INTERNET /><USERID>bjorn@domain.dom</USERID></EMAIL>
      <TEL><WORK /><VOICE /><MSG /><NUMBER>+1 313 747-4454</NUMBER></TEL>
      <KEY><x509 /><BINVAL>dGhpcyBjb3VsZCBiZSAKbXkgY2VydGlmaWNhdGUK</BINVAL></KEY>
    </vCard>
  </contactAppend>
S:<response id="A011"/>

calendarOpen

This operation opens the specified Mailbox as a "Calendar".
A Calendar represents a Server Mailbox, with all messages being parsed and all calendaring information retrieved.
Each calendar has a name, and one session cannot have two calendars with the same name. On the other hand, the same session can open the same Mailbox as two different calendars (with different names).

Attributes:

calendar

the name for the new Calendar to be opened. A client can use an arbitrary string as a Calendar name.

mailbox

the Mailbox name. If this attribute is not specified, the calendar name is used.

A session can use several open Calendars at the same time.

findEvents

This operation retrieves the VEVENT objects from the specified Calendar. Only the Events that fall into the specified time interval are retrieved.

Attributes:

calendar

the Calendar name.

timeFrom, timeTill

the beginning and the end of the time interval (time values should be specified for the selected time zone).

limit

this optional numeric attribute limits the number of the Events returned.

skip

this optional numeric attribute specifies how many "to be returned" Events should be skipped. Using this attribute, a client can retrieve a large Event set in smaller "chunks".

The Server sends an events data message if at least one event is found in the specified time interval.

calendarClose

This operation closes an open Calendar.

Attributes:

calendar

the Calendar name.

calendarRead

This operation tells the Server to retrieve a Message or its part.

Attributes:

calendar

the Calendar name.

UID

the message UID.

totalSizeLimit

the maximum total size of all message parts returned.

calendarPublish

This operation places a calendaring item into a Calendar. The existing items(s) with the same UID are removed.

Attributes:

calendar

the Calendar name.

sendRequests

if this optional attribute exists and its value is no, the item is stored without notifying participants.
Otherwise, a meeting or task request is sent to all participants, and, if there was an existing item with the same UID, Cancel requests are sent to all participants existing in the old item, but excluded from the new item.

Body:

The iCalendar element to place into the selected Calendar, and optionalMIME and/or copyMIME elements to add (the same as elements used with the messageAppend operation).

The iCalendar element should contain optional vtimezone elements and exactly one calendaring item element.
It is possible not to include the vtimezone element for the time zone used in the calendaring item element if this time zone is one of the standard time zones known to the Server.
It is possible not to specify the time zone name in the properties containing date values without the Z suffix. In this case, the TimeZone selected for the current user is used.
If the item does not contain an UID element, the Server generated a unique one and adds it to the item.

Example 1:
The Client published an iCalendar object to the Calendar calendar.

C:<calendarPublish id="A021" calendar="Calendar">
   <iCalendar xmlns="urn:ietf:params:xml:ns:xcal">
    <vCalendar method="PUBLISH" prodid="CommuniGate Pro 5.1.7" version="2.0">
     <vevent>
      <organizer CN="Big Boss">MAILTO:boss@company.dom</organizer>
      <attendee CN="Small Boy">MAILTO:boy@company.dom</attendee>
      <rrule>FREQ=WEEKLY;BYDAY=MO,TH</rrule>
      <dtstamp>20061022T091143Z</dtstamp>
      <uid>18927897984@kjjkjkjk-123444</uid>
      <sequence>0</sequence>
      <summary>Report Meeting</summary>
      <dtstart tzid="NorthAmerica/Pacific">20060515T100000</dtstart>
      <dtend tzid="NorthAmerica/Pacific">20060515T110000</dtend>
      <busystatus>BUSY</busystatus>
      <last-modified>20060516T034850Z</last-modified>
      <created>20060516T034850Z</created>
      <priority>5</priority>
      <description>A twice-a-week meeting to discuss the progress of the assigned projects.</description>
     </vevent>
    </vCalendar>
   </iCalendar>
   <MIME uploadID="att01" />
   <copyMIME folder="INBOX" UID="156" partID="3"/>
  </calendarPublish>
S:<response id="A021"/>

Note: If a time value is specified without the "Z" suffix, it is assumed to be a local time in the Time Zone selected for the current user.

calendarCancel

This operation removes a calendaring item from a Calendar. Cancel requests are sent to all participants.

Attributes:

calendar

the Calendar name.

UID

optional; the message UID (numeric).

sendRequests

if this optional attribute is no, cancel request messages are not sent to the item attendees.

Body:

• optional iCalendar element to cancel.
  If this element is not specified, the item with the specified message UID (this is a number, and it is not the calendar item UID) is taken from the Calendar. Then all items with the same item UIDs are removed.
• optional requestComment element containing a text body - a comment to include into the cancel request message.

calendarUpdate

This operation updates a calendaring item in a Calendar using a reply-type iCalendar object. This item specifies if a particular attendee has accepted or rejected the invitation.

Attributes:

calendar

the Calendar name.

Body:

The iCalendar reply-type item.

calendarAccept

This operation places a calendaring item into a Calendar. The existing items(s) with the same UID are removed.

Attributes:

calendar

the Calendar name.

PARTSTAT

the acceptance status: ACCEPTED, TENTATIVE, IN-PROCESS (Tasks only), COMPLETED (Tasks only).

sendReply

if this optional attribute is no, no reply message is send to the item organizer.

Body:

• The iCalendar element to place into the selected Calendar;
• optionalMIME and/or copyMIME elements to add (the same as elements used with the messageAppend operation);
• optional replyComment element containing a text body - a comment to include into the reply message.

If the item is placed successfully, the iCalendar reply message is sent to the item organizer. Replies are not sent for Event items specifying the current user as an attendee with RSVP=FALSE parameter, or if the request sendReply attribute is set to no.

calendarDecline

This operation rejects a calendaring item.

Attributes:

calendar

the Calendar name. This parameter is optional. If specified, the items with the same UID are removed from this Calendar.

sendReply

if this optional attribute is no, no reply message is send to the item organizer.

Body:

• The iCalendar element to decline.
• optional replyComment element containing a text body - a comment to include into the reply message.

Use this operation when a user decides not to attend a meeting stored as a published item in a Calendar. (if the current user is the meeting origanizer, use the calendarCancel operation instead).
Specify the published item itself and the calendar attribute to remove the item from the Calendar.
The operation sends a negative reply message to the item organizer (unless the sendReply attribute is set to no).

Use this operation when a user opens a request item (in an incoming E-mail) and decides to decline that request.
Specify the request item, and do not specify any calendar attribute.
The operation sends a negative reply message to the item organizer (unless the sendReply attribute is set to no).

Use this operation when a user opens a cancellation request item (in an incoming E-mail), and decides to remove the cancelled item from the Calendar.
Specify the cancellation request item and the calendar attribute (usually - the Main Calendar name), to remove the corresponding item(s) from that calendar.
The operation does not send any reply message.

If the specified item is a request, the operation sends a negative reply message to the item organizer.
If the specified item is a cancel request item, the operation does not send a reply message to the item organizer; specify the calendar attribute to remove the corresponding item from the calendar.

The Server sends the following data messages:

events

These synchronous data messages are sent when the findEvents operation is used.

Attributes:

calendar, timeFrom, timeTill, skip

the same as in the findEvents request.

items

the total number of Events found.

Body:

a set of the event elements for each Event found.

Attributes:

UID

the Event message UID.

timeFrom

the time when this Event starts (in the selected time zone). This attribute is not included for "all-day" Events.

duration

the Event duration (in seconds). This attribute is not included for "all-day" Events.

busyStatus

the Event busy status (BUSY, TENTATIVE, UNAVAILABLE, FREE).

Body:

Event fields: summary

calendarReport

These messages are sent when the Calendar data is modified.

Attributes:

calendar

the Calendar name.

mode

this optional attribute specifies the type of notification.

• If the attribute value is notify some calendar messages have been added, modified, or deleted.
  The client is expected to re-send the findEvents request for this Calendar.

After the Server sends a "notify-mode" calendarReport message to the Client, the Server may choose not to send further "notify-mode" messages for this Calendar until the client performs the findEvents operation on this Calendar.

signalBind

This operation allows the current XIMSS session to receive signals directed to the authenticated user.

Attributes:

deviceName

an optional parameter specifying the device used.

presence

an optional parameter. If set to yes, the client starts to receive Roster and Presence notifications.

Body (optional):

the XML presentation of the client SDP descriptor.
The descriptor is used to specify the client capabilities (ability to accept audio/video calls) and to detect "far-end NAT" configurations.
Note: to detect "far-end NAT" configurations, the SDP descriptor must contain the ip attribute with the default media IP address used by the client (see below).

signalUnbind

After this operation is complete, the current XIMSS session does not receive signals directed to the authenticated user.

callKill

Use this operation to end the call and release all associated resources.
If the call was in the 'calling' state, the outgoing call is cancelled.
If the call was in the 'alerting' state, the incoming call is rejected.
If the call was in the 'connected' state, the disconnect signal is sent to the peer.

Attributes:

callLeg

the call identifier.

After this operation succeeds, it is possible to create a new call with the same identifier.

callStart

Use this operation to start an outgoing call.

Attributes:

callLeg

the new call identifier. The current XIMSS session should have no other call with this identifier.

peer

an E-mail address or a SIP URI to call.

Body:

the XML presentation of the client SDP descriptor.

If this operation succeeds, the new call object is created and an outgoing call is initiated. The server may send zero, one, or several callProvisioned messages, followed by a callDisconnect or callConnected message.
Note: the client should be ready to process these Server messages even before the client receives the positive response for this callStart request.
Note: to process "behind-the-NAT" calls correctly, the SDP descriptor must contain the ip attribute with the default media IP address used with the client (see below).
Note: if the call fails (the callDisconnected message is received), the client still needs to use the callKill operation to release the resources associated with the call and to allow itself to reuse the call identifier.

callProvision

Use this operation to provision an incoming call.

Attributes:

callLeg

the incoming call identifier.

body (optional):

the XML presentation of the client SDP descriptor.

callRedirect

Use this operation to redirect an incoming call.

Attributes:

callLeg

the incoming call identifier.

Body:

one or more XML To elements. Each element should have a text body specifying a URI to redirect the call to.

Note: the client still needs to use the callKill operation to release the resources associated with the call and to allow itself to reuse the call identifier.

Example:
Redirecting an incoming call inp003 to the user1@example.com and user2@example.com.

C:<callRedirect id="A018" callLeg="inp003" >
    <To>user1@example.com</To><To>user2@example.com</To>
  </callRedirect>
S:<response id="A018"/>

callReject

Use this operation to reject an incoming call. You can also use the callKill operation, but this operation allows you to specify an error code.

Attributes:

callLeg

the incoming call identifier.

signalCode

a numeric code (defined with the SIP standards) to pass to the Signal component as an error code.
Use the 486 code ("Busy here") to signal that this device is "busy" (but other devices registered for this user will continue to ring).
Use a 6xx code (600 - "Busy Everywhere" or 603 - "Declined") to signal that the user does not want to accept this call on any device (all other devices will stop ringing, too).

Note: the client still needs to use the callKill operation to release the resources associated with the call and to allow itself to reuse the call identifier.

Example:
Rejecting an incoming call inp004 with the 603 "Declined" code:

C:<callReject id="A020" callLeg="inp004" signalCode="603" />
S:<response id="A020"/>

callAccept

Use this operation to accept an incoming call.

Attributes:

callLeg

the incoming call identifier.

Body:

the XML presentation of the client SDP descriptor.

callSendDTMF

Use this operation to send a DTMF signal via the signaling path.

Attributes:

callLeg

the call identifier.

Body:

a string with the DTMF code to send (10 for '*', 11 for '#').

callUpdate

Use this operation to update a call (to modify the call SDP descriptor).

Attributes:

callLeg

the call identifier.

Body:

the XML presentation of the new client SDP descriptor.

If the operation succeeds, the server sends a callOpCompleted message.

If the operation fails, the server sends a callOpFailed message.

The client should not attempt any other operations (except callKill) with this call before a callOpCompleted or callOpFailed message is received.

callTransfer

Use this operation to transfer the connected peer to a different party.

Attributes:

callLeg

the call identifier.

peer

an E-mail address or a SIP URI to transfer the call to. Use this attribute to initiate a "blind transfer" operation.

otherLeg

the call identifier. It should specify some other "call" in this session. Both calls should be in the 'connected' state. Use this attribute to complete an "attended transfer" operation. The remote peer of the "callLeg" call is connected to the remote peer of the "otherLeg" call.

If the otherLeg attribute is specified, the peer attribute is ignored.

If the call transfer operation succeeds, the "callLeg" call is disconnected (the callDisconnected message is sent to the client). Additionally, if the operation was the "attended transfer" one, the client receives the callDisconnected message for the "otherLeg" call, too.

If the call transfer operation fails, the server sends a callOpFailed message.

makeCall

Use this operation to establish a call using any registered device or client. The Server initiates a call to the autneticated Account, causing all its registred devices to ring. When any device answers the call, that device is instructed to call the specified address (or telephone number).

Attributes:

peer

an E-mail address or a SIP URI to call.

makeCallReport messages are sent to the client informing it about the call progress. This operation completes when the call is established, or when the operation fails, or after a time-out (15 seconds). If the call is not established before time-out, the operation completes, but the call establishing process proceeds.

The Server can send the following data messages:

callProvisioned

These asynchronous data messages are sent when there is an outgoing call in progress (after the callStart was received by the Server):

Attributes:

callLeg

the call identifier.

Body (optional):

the XML presentation of the provisioning response SDP.

callDisconnected

These asynchronous data messages are sent when an outgoing call fails, when an incoming call is cancelled, or when an established call disconnects:

Attributes:

callLeg

the call identifier.

errorText

this optional attribute specifies the call disconnect reason.

signalCode

this optional attribute specifies the numeric signaling error code.

Note: the client still needs to use the callKill operation to release the resources associated with the call and to allow itself to reuse the call identifier.

callConnected

These asynchronous data messages are sent when an outgoing call succeeds and the call is established:

Attributes:

callLeg

the call identifier.

Body:

The XML presentation of the remote party SDP.

callIncoming

These messages are sent when new incoming calls are received (you need to use the signalBind operation to receive incoming calls):

Attributes:

callLeg

the call identifier. The Server generates these identifiers itself.

peer

the remote peer E-mail address.

peerName

optional; the remote peer real name.

Body:

The XML presentation of the request SDP.

callUpdated

These messages are sent when an extsting call is updated (placed on hold, switched to a different remote peer, etc.):

Attributes:

callLeg

the call identifier.

peer

optional; the remote peer E-mail address. It is sent when a call has been transferred.

peerName

optional; the remote peer real name.

Body:

The XML presentation of the updated peer SDP.

callOpCompleted

These messages are sent when in-call operations (such as callUpdate) are completed.

Attributes:

callLeg

the call identifier.

callOpFailed

These messages are sent when in-call operations (such as callUpdate, callSendDTMF) fail.

Attributes:

callLeg

the call identifier.

errorText

the error message.

callDTMF

These messages are sent when a DTMF signal is received via the signaling path.

Attributes:

callLeg

the call identifier.

Body:

A string with the numeric DTMF code received.

makeCallReport

These messages are sent during the makeCall operation.

Body:

A string containing the current operation status.

The Roster and Presence model resembles that of the XMPP protocol.

A Roster is a set of items, each item describing a "contact" - some other local or remote user. The user can monitor the presence information of a "contact", and a "contact" can be granted a right to monitor the user's presence information.

rosterList

This operation retrieves all active Roster items.

Attributes:

The Server sends rosterItem data messages for all currently active Roster "contacts".

rosterSet

This operation modifies a Roster "contact".

Attributes:

peer

the contact E-mail address.

subscription

an optional attribute:

• remove: remove the contact from the Roster.
• subscribed: confirm the contact request to monitor the user's presence information.
• unsubscribed: reject the contact request to monitor the user's presence information, or revoke the already granted right to monitor.
• subscribe: send a request to monitor the contact's presence information.
• s