CommuniGate Pro
Version 5.2
Applications
 
 
XIMSS

XIMSS Protocol

The CommuniGate Pro Server implements the XML Interface to Messaging, Scheduling and Signaling (XIMSS) protocol.

The Interface is implemented with the XIMSS module supporting TCP/IP networks.

The protocol session examples use the S: marker to show the data sent by the Server, and the C: marker to show the data sent by a Client.

Protocol and Message Syntax

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:

response

Attributes:
id
the same as the id attribute of the request message.
errorText
this optional attribute is present only if the operation has failed. It contains the error message text.
errorNum
this optional attribute is present only if the operation has failed. It contains the numeric error code.
Example:
C:<noop id="A001"/>
S:<response id="A001"/>
C:<myCommand id="A002" myParam="user1@example.dom" />
S:<response id="A002" errorText="unknown command" errorNum="500" />

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:
Example:
C:<noop id="A001"/>
S:<alert gmtTime="20070502T083313" localTime="20070502T003313">Account is over quota</alert>
S:<response id="A001"/>
S:<alert gmtTime="20070502T083500" localTime="20070502T003500">Please logout, as we are shutting down.</alert>

Note: a Client must send some command to the Server at least once in 10 minutes, otherwise the Server closes the connection.


Pre-Login Operations

After a connection with the Server is established, and before the client performs the login operation, the client can perform only the operations listed in this section.

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 in the current Domain Skin. The Server sends a strings data message with the dictionary data.
Attributes:
skinName
the Skin name. If not specified, the unnamed Skin is used.
language
the vocabulary language. If the attribute is missing, the Account Language preference string is used.
timeModified
if this attribute is specified, it should contain a date and time value (GMT time). If this attribute is specified, the strings data message does not have any body element if the requested vocabulary modification time is not newer than this attribute value.
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.

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.
connect
if this element is present, it specifies the connection method the client should use for the login and session requests. It is based on the Recommended XIMSS Method Domain Setting for the target Domain.
The element has the following attributes:
protocol
the protocol to use: http or ximss. The recommended protocol should be a secure one (such as https) if the listFeatures operation was issued over a secure protocol.
port
the TCP port number to use. If not specified, the client should use the same port as it used to send this listFeatures operation.

Login Operations

The client should perform the login operation to authenticate the user and to create a XIMSS session.
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:

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

Service Operations

The following operations can be used to manage the client-server connection.

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.
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.
timeModified
if this attribute is specified, it should contain a date and time value (GMT time). If this attribute is specified, the strings data message does not have any body element if the requested vocabulary modification time is not newer than this attribute value.
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.
skinList
This operation lists Skins in the current Domain.
Attributes:
filter
an optional attribute specifies a picture with the star (*) symbol used as wildcards. Only the Skin names matching this picture are reported.
The Server returns one skinInfo message for each Skin found.
skinFileList
This operation provides a list of the selected Skin file names.
Attributes:
skinName
the Skin name. If not specified, the unnamed Skin is used.
filter
an optional attribute specifies a picture with the star (*) symbol used as wildcards. Only the file names matching this picture are reported.
The Server returns one skinFileInfo message for each file found.
skinFileRead
This operation reads a file from the specified Skin in the current Domain.
Attributes:
skinName
the Skin name. If not specified, the unnamed Skin is used.
fileName
the name of file to read.
type
If this optional attribute exists and its value is binary, the file data is returned base64-encoded.
The Server returns a skinFileData message.
cliExecute
This operation executes a Network CLI command.
Attributes:
report
if this attribute is present, and its value is xml, the resulting obejct will be sent as its XML presentation.
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. The current user must have the HTTP Service enabled.
Attributes:
url
the XML document URL (http: or https:).
timeout
the operation time-out (in seconds).
If the document is successfully retrieved, the Server sends a retrievedXML message with the retrieved document content.
retrieveURL
This operation reads a document from a remote server. The current user must have the HTTP Service enabled.
Attributes:
url
the document URL (http: or https:).
Content-Type
the request body content type.
Content-Subtype
the request body content subtype. This attribute is used only when the Content-Type attribute is specified.
method
the request method. If this attribute is absent, the GET method is used if no request body is specified, otherwise the POST method is used.
Cookie
the Cookie field data.
authName, authPassword
when present, these attributes are used to authenticate the request.
timeout
a number in the 0..30 range, used as the transaction timeout value (in seconds). If not specified, a 30 sec timeout is used.
Body:
one of the following formats:
  • the request body text
  • one base64 element containing base64-encoded binary request body data
  • a set of XML field elements. Each field element has a name attribute and a text body. These elements are used to compose the form-type request, specifying the form input values.
When the transaction completes, the Server sends a retrievedURL message with the transaction results.
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".
Attributes:
gmtTime
the time when the Alert was posted (GMT).
localTime
the time when the Alert was posted (in the selected time zone).
Body:
the Alert text (in the UTF-8 encoding).
bye
The Server has decided to close a session (time-out, administrator action, etc.)
The client is supposed to close its Server connection (if it has one), and to inform the user.

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.
timeModified
the vocabulary modification date and time (GMT time).

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.
Array-type vocabulary elements are presented using strings elements. The strings element body is the set of string XML elements without the name attribute.
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 name="KnownFields">
      <string>From</string>
      <string>Subject</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.
Signal
Signaling services are enabled.
PBX
PBX services are enabled.
HTTP
HTTP transaction Services are 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.
skinInfo
This synchronous data message is sent when the Server processes the skinList request.
Attributes:
skinName
the Skin name.
skinFileInfo
This synchronous data message is sent when the Server processes the skinFileList request.
Attributes:
skinName
the Skin name.
fileName
the file name.
size
the file size in bytes.
timeModified
an optional attribute with the file modification date and time (local time).
skinFileData
This message is sent when the Server processes the skinFileRead request.
Attributes:
fileName
the name of read file.
timeModified
the file modification date and time (local time).

Body:
Either a text with file data, or the base64 element. The text body of this XML element is base64-encoded file data (base64 encoding allows you to retrieve binary data).
cliResult
These messages are sent when the Server processes the cliExecute request.
Body:
text or XML presentation of the CLI command output.
Example:
The Client reads some Account aliases.
C:<cliExecute id="A001">GETACCOUNTALIASES user@domain.com<cliExecute/>
S:<cliResult id="A001">(alias1,alias2)</strings>
S:<response id="A001"/>
C:<cliExecute id="A002" report="xml">GETACCOUNTALIASES user@domain.com<cliExecute/>
S:<cliResult id="A002"><subValue>alias1</subValue><subValue>alias2</subValue></strings>
S:<response id="A002"/>
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.
retrievedURL
These messages are sent when the Server processes the retrieveURL request.
Attributes:
url
the document URL.
responseCode
the HTTP numeric response code.
Content-Type
the response body content type (optional).
Content-Subtype
the response body content subtype (optional).
charset
the response body charset (optional).
Date, Last-Modified, Expires
the response header field values in the iCalendar date-time format (optional).
Server, Location, Set-Cookie
the response header field values (optional).

Body:
one of the following formats:
  • an XML element if the response Content-Type is text/xml and XML parsing is successful.
  • a text if the response Content-Type is any non-xml text/*.
  • a base64 element containing base64-encoded response data for all other Content-Type values.
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).

Mailbox Management

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

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.
pureFolder
if this optional attribute exists, and its value is yes, then the result includes "pure" folders, if the value is no, "pure" folders are not included.
See the mailbox data message description for the details.
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.
mailboxAliasList
This operation makes the Server send a mailboxAlias data message (see below) for each Mailbox Alias in the current Account.
mailboxAliasUpdate
This operation modifies the Account Mailbox Aliases set.
Body:
a set of mailboxAlias elements.
Attributes:
name
the Mailbox Alias name in the UTF-8 character set.
mode
if this attribute value is add the name Alias is added to the Mailbox Aliases set. If the set already contains an Alias with this name, it is replaced.
otherwise, the name Alias is removed from the Mailbox Aliases set.

Body:
a string: the target Mailbox name in the UTF-8 character 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, OLDEST, CLASS, MEDIA, UNSEENMEDIA
standard and extended IMAP Mailbox attributes
SIZE
mailbox size (internal, same as INTERNALSIZE in IMAP).
pureFolder
this attribute exists and it has the yes value if the Mailbox is a pure folder - i.e. it cannot contain messages, but it can contain sub-Mailboxes.
Note: a Mailbox is seen as a pure folder if it can contain messages, but the Mailbox class does not match the class specified in the mailboxList request.
isFolder
this attribute exists and it has the yes value if the Mailbox is a mailbox and a folder - i.e. it can contain messages, and it can contain sub-Mailboxes.
rights
the effective access rights for the Mailbox. If this attribute is absent, access to the Mailbox is not restricted.
mailboxSubscription
These messages are sent when the Server processes the mailboxSubList request.
Attributes:
mailbox
the Mailbox name in the UTF-8 character set.
mailboxAlias
These messages are sent when the Server processes the mailboxSubList request.
Attributes:
name
the Mailbox Alias name in the UTF-8 character set.

Body:
a string; the target 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".
Example:
C:<mailboxCreate id="A001" mailbox="MyNotes" mailboxClass="IPF.StickyNote" />
S:<response id="A001"/>

C:<mailboxRename id="A002" mailbox="MyNotes" newName="SharedNotes" />
S:<response id="A002"/>

C:<mailboxACLUpdate id="A003" mailbox="SharedNotes">
    <aclElem pattern="user1">lr</aclElem>
    <aclElem pattern="user2">lr</aclElem>
  </mailboxACLUpdate>

S:<response id="A003"/>

C:<mailboxACLUpdate id="A004" mailbox="SharedNotes">
    <aclElem pattern="user1" mode="add">di</aclElem>
    <aclElem pattern="user2" mode="sub">r</aclElem>
  </mailboxACLUpdate>

S:<response id="A004"/>

C:<mailboxACLList id="A005" mailbox="SharedNotes"/>
S:<mailboxACL id="A005" mailbox="SharedNotes">
    <aclElem pattern="user1">lrdi</aclElem>
    <aclElem pattern="user2">l</aclElem>
  </mailboxACL>

S:<response id="A005"/>

Mailbox Operations

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

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.
UIDValidity, UIDMin
If these optional numeric attributes are present, and the Folder Mailbox UIDValidity value is equal to the UIDValidity request attribute value, then only the messages with UID not smaller than the UIDMin value are included into the Folder.

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 elements, 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.
mailboxClass
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.
encrypt
if this optional attribute exists, and its value is 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, UIDValidity, UIDMin
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.

emptyTrash
This operation physically removes all messages from the Trash Mailbox (if it is specified).

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, and the unseen attribute specifies the total number of unseen messages (messages without the Seen flag) 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.
unseen
the total number of unseen messages in the Folder.
This attribute is present when the mode attribute value is init, removed, updated, or added.
rights
the effective access rights for the Folder.
This attribute is present when the mode attribute value is init. If this attribute is absent, access to the Folder is not restricted.
UIDValidity
the Folder Mailbox UIDValidity value.
This attribute is present when the mode attribute value is init.

Body:
The body is present when the mode attribute value is updated or added.
It contains a set of elements with viewer field values.
Example 1:
C:<folderOpen id="A001" folder="INBOX" mailbox="INBOX" sortField="INTERNALDATE" sortOrder="asc">
   <field>FLAGS</field><field>From</field><field>Subject</field>
  </folderOpen>

S:<folderReport id="A001" folder="INBOX" mode="init" messages="234" unseen="12" />
S:<response id="A001"/>

C:<folderBrowse id="A002" folder="INBOX"><index from="0" till="3" /></folderBrowse>
S:<folderReport id="A002" folder="INBOX" index="0" UID="123">
    <FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From>
    <Subject>Hello - just a test</Subject>
  </folderReport>

S:<folderReport id="A002" folder="INBOX" index="1" UID="543">
    <FLAGS>Seen,Answered</FLAGS><From>Jim Spammer</From>
    <Subject>This is the best offer!</Subject>
  </folderReport>

S:<folderReport id="A002" folder="INBOX" index="2" UID="343">
    <FLAGS>Seen,Media</FLAGS><From>user@example.com</From>
    <Subject>Meeting reminder</Subject>
  </folderReport>

S:<folderReport folder="INBOX" mode="notify" />
S:<folderReport id="A002" folder="INBOX" index="3" UID="512">
    <FLAGS>Seen,Flagged</FLAGS><From>Admin@hq.example.com</From>
    <Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>

S:<response id="A002" />

S:<folderReport folder="INBOX" mode="notify" />

C:<folderBrowse id="A003" folder="INBOX"><index from="0" till="3" /></folderBrowse>
S:<folderReport id="A003" folder="INBOX" index="0" UID="123">
    <FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From>
    <Subject>Hello - just a test</Subject>
  </folderReport>

S:<folderReport id="A003" folder="INBOX" index="1" UID="543">
    <FLAGS>Seen,Answered</FLAGS><From>Jim Spammer</From>
    <Subject>This is the best offer!</Subject>
  </folderReport>

S:<folderReport id="A003" folder="INBOX" index="2" UID="343">
    <FLAGS>Seen,Media</FLAGS><From></From>
    <Subject></Subject>

  </folderReport>

S:<folderReport id="A003" folder="INBOX" index="3" UID="512">
    <FLAGS>Seen,Flagged</FLAGS><From>Admin@hq.example.com</From>
    <Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>

S:<response id="A003" />

C:<folderSync id="A004" folder="INBOX" />
S:<folderReport id="A004" folder="INBOX" index="35" UID="117" mode="deleted" messages="233" unseen="11" />
S:<folderReport id="A004" folder="INBOX" index="2" UID="343" mode="deleted" messages="232" unseen="11" />
S:<folderReport id="A004" folder="INBOX" index="1" UID="976" mode="added" messages="233" unseen="12" >
    <FLAGS>Recent</FLAGS><From>CGatePro Discussions</From>
    <Subject>[CGP] Re: Session Timer?</Subject>
  </folderReport>

S:<response id="A004" />

C:<folderBrowse id="A005" folder="INBOX"><index from="0" till="3" /></folderBrowse>
S:<folderReport id="A005" folder="INBOX" index="0" UID="123">
    <FLAGS>Seen,Deleted</FLAGS><From>John H. Smith</From>
    <Subject>Hello - just a test</Subject>
  </folderReport>

S:<folderReport id="A005" folder="INBOX" index="1" UID="976">
    <FLAGS>Recent</FLAGS><From>CGatePro Discussions</From>
    <Subject>[CGP] Re: Session Timer?</Subject>
  </folderReport>

S:<folderReport id="A005" folder="INBOX" index="2" UID="543">
    <FLAGS>Seen,Answered</FLAGS><From>Jim Spammer</From>
    <Subject>This is the best offer!</Subject>
  </folderReport>

S:<folderReport id="A005" folder="INBOX" index="3" UID="512">
    <FLAGS>Seen,Flagged</FLAGS><From>Admin@hq.example.com</From>
    <Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>

S:<response id="A005" />

Example 2:

C:<messageCopy id="A010" folder="INBOX" targetMailbox="Archive">
    <UID>512</UID><UID>123</UID><UID>976</UID>
  </messageCopy>

S:<folderReport folder="Archive" mode="notify" />
S:<response id="A010"/>

Example 3:

C:<messageMark id="A020" folder="INBOX" flags="Deleted">
    <UID>512</UID><UID>123</UID><UID>976</UID>
  </messageMark>

S:<folderReport folder="INBOX" mode="notify" />
S:<response id="A020"/>

C:<folderSync id="A021" folder="INBOX" />
S:<folderReport id="A021" folder="INBOX" index="1" UID="976" mode="updated" unseen="12" >
    <FLAGS>Recent,Deleted</FLAGS><From>CGatePro Discussions</From>
    <Subject>[CGP] Re: Session Timer?</Subject>
  </folderReport>

S:<folderReport id="A021" folder="INBOX" index="3" UID="512" mode="updated" unseen="12" >
    <FLAGS>Seen,Deleted,Flagged</FLAGS><From>Admin@hq.example.com</From>
    <Subject>Shutdown @ 4:45AM</Subject>
  </folderReport>

S:<response id="A021"/>

C:<folderExpunge id="A022" folder="INBOX" />
S:<folderReport folder="INBOX" mode="notify" />
S:<response id="A022"/>

C:<folderSync id="A023" folder="INBOX" />
S:<folderReport id="A023" folder="INBOX" index="0" UID="123" mode="deleted" messages="232" unseen="12" />
S:<folderReport id="A023" folder="INBOX" index="0" UID="976" mode="deleted" messages="231" unseen="11" />
S:<folderReport id="A023" folder="INBOX" index="29" UID="446" mode="deleted" messages="230" unseen="11" />
S:<folderReport id="A023" folder="INBOX" index="123" UID="756" mode="deleted" messages="229" unseen="11" />
S:<folderReport id="A023" folder="INBOX" index="1" UID="512" mode="deleted" messages="228" unseen="11" />
S:<response id="A023"/>

C:<closeMailbox id="A024" folder="INBOX" />
S:<response id="A024"/>

Message Operations

A client can use the following set of operations to retrieve Messages from Mailboxes.

folderRead
This operation tells the Server to retrieve a Message or its part. It is sent to the client as a folderMessage data message.
Attributes:
folder
the Folder name.
UID
the message UID.
partID
this optional attribute specifies the message part to read. If it is not specified, the entire message is read.
mode
if this optional attribute is set to replyFrom or replyAll, the partID attribute should either be absent or it should specify an EMail subpart element. The folderMessage response message body is an EMail element with a pre-composed reply E-mail.
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.
checkOld
this optional attribute can be specified if the replacesUID attribute is specified. If this attribute exists, it should have the yes value.
If this attribute is specified, the operation fails if the Folder Mailbox does not contain a message with replacesUID UID. This check and the append/delete operations are executed atomically.
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.
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.

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,Seen" 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" unseen="0"/>
S:<folderReport id="A003" folder="Drafts" index="127" UID="755" mode="added" messages="302" unseen="1">
    <FLAGS>Recent,Drafts</FLAGS>
    <From>Other Name</From>
  </folderReport>

S:<folderReport id="A003" folder="Drafts" index="17" UID="756" mode="added" messages="303" unseen="1" >
    <FLAGS>Recent,Drafts,Seen</FLAGS>
    <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 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.

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">Attached 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 exists, 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, UID, partID, mode
copies of the folderRead request attributes.

Body:
The XML presentation of the Message or its part.
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.

Account Management

A client can use the following set of operations to manage Account ACLs.

accountRightsGet
This operation makes the Server send an accountRight data message (see below) with the user access rights for the current or specified Account.
Attributes:
userName
an optional account specifying the target Account name. If this attribute is absent, the current Account is used.
accountACLList
This operation makes the Server send an accountACL data message (see below) with the Mailbox Access Control List data.
Attributes:
userName
an optional account specifying the target Account name. If this attribute is absent, the current Account is used.
accountACLUpdate
This operation modifies the Account Access Control List.
Attributes:
userName
an optional account specifying the target Account name. If this attribute is absent, the current Account is used.

Body:
A set of aclElem XML elements. These elements are the same as those used with the mailboxACLUpdate operation, but their body strings use symbols that specify Account Access Rights.

The Server sends the following data messages:

accountRights
This message is sent when the Server processes the accountRightsGet request.
Attributes:
userName
the Account name (if specified in the request).

Body:
a string; each symbol specifies an effective Account Access Right granted to the current user.
accountACL
This message is sent when the Server processes the accountACLList request.
Attributes:
userName
the Account name (if specified in the request).

Body:
A set of aclElem XML elements, one element for each Account Access Control List element, same as used in the mailboxACL data messages, but the element body strings contain symbols representing Account Access Rights.

Secure Messaging (S/MIME)

A client can use the following set of operations to use the Server S/MIME features.

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 after this period of time.
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.
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).

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:
The Client retrieves a signed message:

C:<folderRead id="A001" folder="INBOX" UID="55" totalSizeLimit="100000" />
S:<folderMessage id="A001" folder="INBOX" UID="55">
  <EMail>
    <Return-Path>fromName@domain</Return-Path>
    <From realName="Sender Name">fromName@domain</From>
    <Subject>Re: I'll be there!</Subject>
    <To realName="Recipient Name">a1@domain</To>
    <X-Mailer>SuperClient v7.77</X-Mailer>
    <Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
    <Message-ID>web-40721383@domain.dom</Message-ID>
    <MIME digesterName="SHA1" estimatedSize="5171" subtype="signed" type="multipart"
           Type-micalg="SHA1" Type-protocol="application/x-pkcs7-signature" />
      <MIME estimatedSize="3032" partID="01" subtype="mixed" type="multipart">
        <MIME charset="utf-8" estimatedSize="86" partID="01-01" subtype="plain" type="text">Dear Susan,&#x0A;&#x0A;Attached please find a file I received this morning...&#x0A;Mary.&#x0A;
        </MIME>
        <MIME disposition="attachment" Disposition-filename="logo.gif" estimatedSize="1929" partID="01-02" subtype="gif" type="image" />
      </MIME>
      <SMIMESignature>
        <x509 subject="fromName@domain" validationError="presented certificate is issued by an unknown authority" version="2">
          <subject><cn>Sender Name</cn><contact>fromName@domain</contact></subject>
          <issuer><c>US</c><cn>issuer.dom</cn><contact>postmaster@issuer.dom</contact><l>Mill Valley</l>
                  <o>Issuer Company, Inc.</o><ou>Issuer Department</ou><st>CA</st></issuer>
          <validFrom>20040924T231857Z</validFrom>
          <validTill>20170923T231857Z</validTill>
        </x509>
      </SMIMESignature>
    </MIME>
  </EMail>
  </folderMessage>

S:<response id="A001"/>

When the Account Private Key is unlocked, the Server tries to decrypt all encrypted message parts.

If decrypting fails, the encrypted part element contains an additional attribute:
decryptionError
the decrypting error message text.

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.

The encypted part element contains additional attributes:
cipherName
the name of cryptographic cipher used to encrypt the decrypted part.
keyLength
the length of cryptographic cipher key (in bits) used to encrypt the decrypted part.

Example:
The Client retrieves an encrypted message, then unlocks the Account Private Key and then retrieves the same message again:

C:<folderRead id="A001" folder="INBOX" UID="55" totalSizeLimit="100000" />
S:<folderMessage id="A001" folder="INBOX" UID="55">
  <EMail>
    <Return-Path>fromName@domain</Return-Path>
    <From realName="Sender Name">fromName@domain</From>
    <Subject>Re: I'll be there!</Subject>
    <To realName="Recipient Name">a1@domain</To>
    <X-Mailer>SuperClient v7.77</X-Mailer>
    <Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
    <Message-ID>web-40721383@domain.dom</Message-ID>
    <MIME disposition="attachment" Disposition-filename="smime.p7m" estimatedSize="4536"
           subtype="x-pkcs7-mime" type="application" Type-name="smime.p7m" Type-smime-type="enveloped-data" />
  </EMail>
  </folderMessage>

S:<response id="A001"/>
C:<SMIMEUnlock id="A002" password="smime-password" />
S:<response id="A002"/>
C:<folderRead id="A003" folder="INBOX" UID="55" totalSizeLimit="100000" />
S:<folderMessage id="A003" folder="INBOX" UID="55">
  <EMail>
    <Return-Path>fromName@domain</Return-Path>
    <From realName="Sender Name">fromName@domain</From>
    <Subject>Re: I'll be there!</Subject>
    <To realName="Recipient Name">a1@domain</To>
    <X-Mailer>SuperClient v7.77</X-Mailer>
    <Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
    <Message-ID>web-40721383@domain.dom</Message-ID>
    <MIME cipherName="RC2" disposition="attachment" Disposition-filename="smime.p7m" estimatedSize="4536" keyLength="40"
          subtype="x-pkcs7-mime" type="application" Type-name="smime.p7m" Type-smime-type="enveloped-data" >
      <EMail partID="E">
        <From realName="Sender Name">fromName@domain</From>
        <Subject>Re: I'll be there!</Subject>
        <To realName="Recipient Name">a1@domain</To>
        <X-Mailer>SuperClient v7.77</X-Mailer>
        <Date localTime="20070830T204318" timeShift="-25200">20070830T184318Z</Date>
        <Message-ID>web-40721383@domain.dom</Message-ID>
        <MIME estimatedSize="3275" partID="E" subtype="mixed" type="multipart">
          <MIME charset="utf-8" estimatedSize="329" partID="E-01" subtype="plain" type="text" Type-format="flowed">
            This is an encrypted E-mail with an attachment.

            On Thu, 30 Aug 2007 20:40:49 -0800
            &quot;Sender Name&quot; &lt;fromName@domain&gt; wrote:
            &gt; Dear Susan,
            &gt;
            &gt; I will come to your place tomorrow, thank you for the invitation!
            &gt; Mary.
          </MIME>
          <MIME disposition="attachment" Disposition-filename="logo.gif" estimatedSize="1929" partID="E-02"
                subtype="gif" type="image" />
        </MIME>
      </EMail>
    </MIME>
  </EMail>
</folderMessage>

S:<response id="A003"/>

When the Account Private Key is unlocked, a client can submit a signed E-mail.

The EMail element should contain an additional attribute:
sign
if this optional attribute exists, and its value is yes, the message body is signed.

Example:
The Client submits a signed text message to the toName@domain address address.

C:<messageSubmit id="A001">
    <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>
  </messageSubmit>

S:<response id="A001"/>

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 additional attributes:
encrypt
if this optional attribute exists, and its value is yes, the message body is encrypted.
addressBook
the name of the Address Book to look the recipient certificates in.

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.

C:<messageSubmit id="A001" useDSN="yes" >
    <EMail encrypt="yes" addressBook="Contacts" >
      <From realName="Sender Name">fromName@domain</From>
      <Subject>A message regarding your request</Subject>
      <To realName="Recipient Name">toName@domain</To>
      <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>
    </EMail>
  </messageSubmit>

S:<response id="A001"/>

Contacts Operations

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 vCardGroup element.

The Contact-class Mailboxes are used to store special messages ("items") containing only vCard or vCardGroup data. In a properly composed vCard item:

In a properly composed vCardGroup item:

Use the following operations to compose, store, and retrieve these special messages:

contactAppend
This operation composes a special E-mail message containing the vCard or vCardGroup data as its body, forms all necessary E-mail message header fields and stores the resulting message in the specified Folder or 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, checkOld, 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 or vCardGroup 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"/>
contactsImport
This operation parses an uploaded file, which should contain vCard items. The resulting items are copied into the specified Folder.
Attributes:
folder
the Folder name.
uploadID
a string identifying a file in the "uploaded file set".
contactFind
This operation searches the open Folder for a vCard message with an E-mail or Telephone number matching the specified address.
Only the E-mail message header fields (To and X-Telnum) are checked, not the actual vCard data.
The operation stops when it finds the first matching message. The found E-mail message content is sent to the client as the folderMessage data message.
Attributes:
folder
the Folder name.
totalSizeLimit
same as for the folderRead operation.
peer
the address to search for.

Calendar Operations

A client can use the following operations to process a Calendar in the authenticated Account, as well as in other Accounts (by specifying the full Mailbox name as ~accountName@domainName/mailboxName).

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).
byAlarm
if this optional attribute exists, and its value is yes, the operation looks not for the Events in the specified time interval, but for the Events that have an Alert element set within the specified time interval.
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. It is sent to the client as a calendarMessage data message.
This operation is the same as the folderRead operation, but instead of the folder attribute it uses the calendar to specify the open Calendar name.
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, 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. A meeting or task request is sent to all participants, or, if this attribute value is new, to all newly added participants.

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.
calendarImport
This operation parses an uploaded file, which should contain iCalendar/vCalendar items. The resulting items are copied into a Calendar. The existing items(s) with the same UID are removed.
Attributes:
calendar
the Calendar name.
uploadID
a string identifying a file in the "uploaded file set".
freeBusyRead
This operation retrieves the FreeBusy information for the specified Account.
Attributes:
userName
the target Account name. If this attribute is not specified, the current Account FreeBusy information is retrieved.
timeFrom, timeTill
the beginning and the end of the time interval (time values should be specified for the selected time zone).
The Server sends a freeBusyData data message.

The Server sends the following data messages:

events
This synchronous data message is sent when the Server processes the findEvents request.
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.
dateFrom
the date when this Event starts (in the selected time zone). This attribute is included for "all-day" Events only.
duration
the Event duration (in seconds).
alarmTime
this attribute is included only if the request contained the byAlarm attribute. The attribute value specifies the time (in the selected time zone) when the Event Alarm should take place.
busyStatus
the Event busy status (BUSY, TENTATIVE, UNAVAILABLE, FREE).
organizer
this attribute is present and it has the yes value if the current user is the organizer of the Event.
recurrence
this attribute is present and it has the yes value if the Event is a recurrent one.
attendees
this attribute is present if the Event has attendees. The attribute value is the number of attendees.

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.

calendarMessage
This synchronous data message is sent when the Server processes the calendarRead request.
This message is the same as folderMessage, but instead of the folder attribute it contains the calendar attribute with the Calendar name.
freeBusyData
This synchronous data message is sent when the Server processes the freeBusyRead request.

Attributes:
userName
the copy of the same freeBusyRead request attribute.

Body:
the vfreebusy object containing a set of freebusy elements. All time values returned are specified as the local time in the Time Zone selected for the current user.

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.


Signaling

A client should use the "bind" operation to start receiving signals directed to the authenticated user.

A client can maintain one or several concurrent communication sessions ("calls"). Each call is identified with its callLeg identifier.

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
if this optional attribute exists, and its value is 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.
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 '#').

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

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

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.

callSendInfo
Use this operation to send an INFO signal to the connected peer.
Attributes:
callLeg
the call identifier.

Body:
a MIME XML element:
Attributes:
type
INFO content Content-Type.
subtype
INFO content subtype (optional).

Body:
a string with INFO content data.

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

If the 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 ("self-call"), 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.
callerParams
an optional attribute containing SIP URI parameters to use for the "self-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 existing 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 (optional).
Note:This message can be received while an ougoing call is still in progress, indicating that a different party has intercepted ("picked up") the call.
callOpCompleted
These messages are sent when in-call operations (such as callUpdate, callSendDTMF, callSendInfo) are completed.
Attributes:
callLeg
the call identifier.
callOpFailed
These messages are sent when in-call operations (such as callUpdate, callSendDTMF, callSendInfo) 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.
callInfo
These messages are sent when an INFO signal is received:
Attributes:
callLeg
the call identifier.

Body:
the same as in the callSendInfo operation.
makeCallReport
These messages are sent during the makeCall operation.
Body:
A string containing the current operation status.

Instant Messaging

The Instant Messaging (IM) model assumes that a client maintains a separate window for each "peer", where a "peer" is some other IM user taking part in an IM conversation.

sendIM
This operation sends an Instant Message to the specified user. The Server sends a XIMSS response without waiting till the Instant Message is actually delivered (or failed).
There is no explicit IM session opening operation. If the Server does not have an open IM session with the specified peer, a new session is created.
Attributes:
peer
the E-mail address of the user to send this message to.

Body:
the Instant Message text (in the UTF-8 encoding) or the composing element.
This element should be sent when the user is preparing the message but has not sent it yet.
closeIM
A request to close all IM sessions with the specified user.
A client application should send this request when it closes an IM conversation window.
Attributes:
peer
the user E-mail address.

The Server sends the following data messages:

readIM
These asynchronous data messages are sent when the Server receives an Instant Message for the client user.
Attributes:
peer
the sender E-mail address.
peerName
optional; the sender real name.

Body:
Either the Instant Message text (in the UTF-8 encoding) or a composing XML element.
This element is sent when the remote peer is preparing the message but has not sent it yet.

There is no explicit session opening operation. If the client has no open conversation window for the specified user, it should open a new one.
errorIM
These asynchronous data messages are sent when the Server fails to deliver an Instant Message.
Attributes:
peer
the recipient E-mail address.
errorText
the error message text.
errorNum
the error message numeric code.
sendid
the id attribute of the sendIM operation that sent the failed Instant Message.

Roster and Presence

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:
accountName
if this optional attribute is specified, the operation reads the Roster items from the specified Account.

The Server sends rosterItem data messages for all currently active Roster "contacts".
rosterSet
This operation modifies a Roster "contact".
Attributes:
accountName
if this optional attribute is specified, the operation updates the Roster in the specified Account.
peer
the contact E-mail address.
subscription
an optional attribute:
  • update or no attribute: update the contact information.
  • 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.
  • subBoth: confirm the contact request to monitor the user's presence information, and send a request to monitor the contact's presence information.
  • unsubscribe: stop monitoring the contact's presence information.
name
an optional attribute specifying the Contact real name.

Body:
a set of group XML elements; each element body specifies the name of a Group this contact belongs to.

The update, subscribed, and subscribe operations create a new Roster item if the item with the specified E-mail address does not exist.

rosterGroupSet
This operation manages Roster "contact groups".
Attributes:
accountName
if this optional attribute is specified, the operation updates the Roster in the specified Account.
group
the group name.
mode
  • add: create a new contact group with the specified name.
  • delete: remove the exiting contact group with the specified name from the Roster.
  • rename: rename the exiting contact group.
newName
the new contact group name (used only with the mode attribute set to rename).
presenceSet
This operation sets the user presence information. The Server aggregates the presence information reported by all currently connected clients (XIMSS, XMPP, SIP) and distributes it to all network entities subscribed to that information.
Attributes:
type
this optional element may have the unavailable value. It indicates that the user is "virtually offline".
If this attribute is absent, the user is online.

Body:
an optional show XML element; its text body specifies the XMPP-style user presence status:
  • dnd - do not disturb, busy, on-the-phone.
  • away - will be right back, in a meeting, out-to-lunch.
  • xa - away ("extended away").
Alternatively, you can use a presence XML element instead of the show XML element. The presence XML element text body specifies the more detailed user presence status:
  • offline - "virtually offline".
  • online - online.
  • on-phone - user is engaged into a real-time conversation.
  • in-meeting - user is in a middle of a meeting.
  • busy - generic form "cannot chat right now".
  • be-back - user will be right back
  • out-lunch - user is out for a break/meal.
  • away - extended away.

When a session starts, the user is "virtually offline". The client should use this operation to indicate that the user is online.

When the user disconnects, its session status is automatically changed to unavailable (offline).

The Server sends the following data messages:

rosterItem
These data messages are sent synchronously when the Server processes the rosterList request. One message is sent for each Roster item ("Contact").
These data messages can also be sent sent asynchronously (see below).
Attributes:
peer
the contact E-mail address.
subscription
  • to: the user can monitor the contact.
  • from: the contact can monitor the user.
  • both: the user and the contact can monitor each other.
  • none: the user and the contact do not monitor each other.
ask
this optional attribute has the subscribe value if the user has requested a subscription to the contact's presence information, but this request has not been confirmed yet.
name
an optional attribute specifying the Contact real name.

Body:
a set of group XML elements; each element body specifies the name of a Group this contact belongs to.

If the signalBind operation was used to enable Roster and Presence notifications:
  • Every time a Roster item is added or updated, the Server sends rosterItem messages with the new or updated data.
  • Every time a Roster item is deleted, the Server sends the rosterItem message with the subscription attribute set to remove.
  • The Server sends the presence data messages.
presence
These asynchronous data messages are sent when a presense state of some Roster "contact" (item) is changed, and Presence notifications are enabled.
Attributes:
peer
the Contact E-mail address.
type
an optional attribute:
  • unavailable: the contact is offline.
  • subscribe: the contact is requesting subscription to the user's presence information.
  • absent: the contact is online.

Body:
a presence XML element; its text body specifies the detailed contact presence status (see above);
an optional show XML element; its text body specifies the XMPP-style contact presence status (see above).

Preferences

A client can retrieve and update the authenticated user Preferences and Public Info data.

prefsRead
This operation retrieves authenticated user Preferences or Public Info data.
Attributes:
type
this is an optional parameter.
If the specified value is default, the default Preferences for the Account Domain are retrieved.
If the specified value is custom, the explicitly specified Account Preferences are retrieved.
If the specified value is publicInfo, the Account Public Info settings are retrieved.
If the attribute is not specified, the effective Account Preferences are retrieved.
Body:
Zero or more XML name elements. These elements body specify the names of elements to retrieve; If no name element is specified, all Preference or Public Info elements are retrieved.
prefsStore
This operation updates authenticated user Preferences or Public Info data.
Attributes:
type
this is an optional parameter.
If the specified value is publicInfo, the Account Public Info settings are updated.
If the attribute is not specified, the custom Account Preferences are updated.
Body:
XML elements with the names equal to the Preference element names. An element body contains the new Preference element value. If the value is the default string, the Public Info or custom Preference value is removed, and the default value becomes the effective element value.
If the value is an array, it should be presented using the array XML presentation.
If the value is a dictionary, it should be presented using the dictionary XML presentation.

If the body contains the UserFromAddr element, the Server uses this element and an optional UserFromName element to compose the UserFrom element with an E-mail address value (in the "UserFromName_value" <UserFromAddr_value> format).

The Server sends the following data messages:

prefs
This synchronous data message is sent when the Server processes the prefsRead request.
Attributes:
type
an optional attribute, the same as the request attribute.

Body:
XML elements, with the names equal to Preference or Public Info element names. An element body contains the element value.
If the value is an array, it is presented using the array XML presentation.
If the value is a dictionary, it is presented using the dictionary XML presentation.

If the prefs data contains the UserFrom string, the Server tries to parse that E-mail address. If the address is parsed, the UserFromAddr element (with the pure userName@domainName address) and, optinally, UserFromName element (with the address comment) are added to the data message body.

prefsModified
These asynchronous data messages are sent when the Account Preferences are modified (by this session, some other session, or some other CommuniGate Pro Server component. It it recommended that the client re-reads the Account Preferences in response to this message.

File Storage Operations

A client can manage the Account File Storage.
If the authenticated user has the CanAccessWebSites Domain Administrator right, this client can manage files in someone else's Account by using the prefix when specifying file names: ~accountName/fileName.

fileList
This operation provides a list of stored files.
Attributes:
directory
an optional attribute with the File Storage subdirectory name. If absent, the content of the Account top File Storage directory is returned.
The Server returns one fileInfo message for each file or directory in the specified File Storage directory.
fileDirInfo
This operation provides information about all Account files or all files in the specified directory.
Attributes:
directory
an optional attribute with the File Storage subdirectory name. If absent, the information about all Account File Storage files is returned.
The Server returns one fileDirInfo message.
fileDirList
This operation provides a list of all File Storage folder. The Server returns one fileDirName message for each File Storage directory.
fileWrite
This operation stores data in a file.
Attributes:
fileName
the name of file to write to.
position
If this attribute is absent, then this operation completely rewrites the specified file. If the file did not exist, it is created.
If this attribute value is append, this operation adds the data to the file end (atomically).
If this attribute value is new, this operation first checks that the specified file does not exist, and then creates the file and stores the data in it.
If this attribute value is a number, the file must exist, and the operation rewrites the file from the byte position specified with this number.
type
If this optional attribute exists and its value is binary, the request body is base64 XML element, its body is base64-decoded before being written to the file.
If this optional attribute exists and its value is object, the request body is an XML representation of a data Object; the text representation of this Object is written to the file. If this value is used, the position attribute must not be specified.
If this optional attribute exists and its value is xml, the request body must be a single XML element. Its text representation is written to the file. If this value is used, the position attribute must not be specified.

Body:
Either a text with file data, or a base64 XML element, or an XML representation of an object, or an XML element to write to the file.
fileStore
This operation stores an uploaded file or a message MIME part as a File Storage file.
Attributes:
fileName
the name of file to be created.
uploadID
a string identifying a file in the "uploaded file set".
folder, UID, partID
these attributes have the same meaning as for the fileRead operation. They identify a message MIME part to retrieve, decode, and store as a file.
calendar
use this attribute instead of the folder attribute to copy a MIME part from an open Calendar, rather than a E-mail folder.
position
If this optional attribute exists and its value is new, this operation first checks that the specified file does not exist, and then creates the file and copies the uploaded file or MIME part data into it.
If a file under this name already exists, the old file is removed first.
Either a uploadID attribute should be specified, or the folder is specified, or the calendar attribute should be specified. No two of these atttributes should be specified together in the same fileStore operation.
fileRead
This operation reads data from a file.
Attributes:
fileName
the name of file to read from.
position
This numeric attribute specifies the file position to start reading from. If this attribute is absent, then the file is read from its start (from the file position 0).
limit
This numeric attribute specifies the maximum size of the file data portion to read. If specified, it should not exceed 3MB. If not specified, the 3MB limit is used.
type
If this optional attribute exists and its value is binary, the file data is returned base64-encoded, as the base64 XML element body.
If this optional attribute exists and its value is object, the file data is parsed as a text presentation of an Object, and the Object XML representation is returned. If this value is used, the position and length attributes must not be specified, and the file size should not exceed 3MB.
If this optional attribute exists and its value is xml, the file data is parsed as an XML document, and its XML content is returned. If this value is used, the position and length attributes must not be specified, and the file size should not exceed 3MB.
The Server returns a fileData message.
fileRename
This operation renames a file in the File Storage.
Attributes:
fileName
the name of file to rename.
newName
the new name for the file.
fileRemove
This operation removes a file from the File Storage.
Attributes:
fileName
the name of file to remove.
fileCopy
This operation copies file or message contents into a File Storage file.
Attributes:
newName
the name of file to create (copy target). If file with this name already exists, it is removed.
fileName
optional: the name of File Storage file to copy.

Body:
one optional copyMIME element. It specified a message part to decode and copy into the specified file.
The operation must contain either a fileName attribute or one copyMIME body element.
fileDirCreate
This operation creates a file directory in the File Storage.
Attributes:
fileName
the name of file directory to create.
fileDirRename
This operation renames a file directory in the File Storage.
Attributes:
fileName
the name of file directory to rename.
newName
the new name for the file directory.
fileDirRemove
This operation removes a file directory from the File Storage.
Attributes:
fileName
the name of file directory to remove. Only empty directories can be removed.

The Server sends the following data messages:

fileInfo
This synchronous data message is sent when the Server processes the fileList request.
Attributes:
fileName
the file or subdirectory name.
directory
an optional attribute, the same as the directory attribute in the fileList request.
type
an optional attribute exists and contains the directory value, if this message describes a subdirectory.
size
an optional attribute with the file size in bytes (absent if this message describes a subdirectory).
timeModified
an optional attribute with the file modification date and time (local time).
fileDirInfo
This synchronous data message is sent when the Server processes the fileDirInfo request.
Attributes:
directory
an optional attribute, the same as the directory attribute in the fileDirInfo request.
files
the total number of files in the Account or in the specified subdirectory (and all nested directories).
size
the total size of all files (in bytes).
fileDirName
This synchronous data message is sent when the Server processes the fileDirList request.
Attributes:
directory
the File Storage directory name.
fileData
This message is sent when the Server processes the fileRead request.
Attributes:
fileName
the name of read file.
position
the file position of the read data.
slice
the size of read data (in bytes). To read the next portion of the file, add the position and slice values to get the new position value.
size
the file total size.
timeModified
an optional attribute with the file modification date and time (local time).
type
a copy of the request type attribute.

Body:
Either a text with file data, or the base64 (its body is base64-encoded file data), or an XML representation of the file content Object.

Examples:

C:<fileRead id="A001" fileName="test.txt" />
S:<fileData id="A001" fileName="test.txt"position="0" slice="22" size="22" timeModified="20061018T115836">This is not your file!</fileData>
S:<response id="A001"/>

C:<fileRead id="A002" fileName="test.txt" limit="15" />
S:<fileData id="A002" fileName="test.txt"position="0" slice="15" size="22" timeModified="20061018T115836">This is not you</fileData>
S:<response id="A002"/>

C:<fileRead id="A003" fileName="test.txt" limit="15" position="15" />
S:<fileData id="A003" fileName="test.txt"position="15" slice="7" size="22" timeModified="20061018T115836">r file!</fileData>
S:<response id="A003"/>

C:<fileRead id="A004" fileName="test.txt" limit="15" position="15" type="binary" />
S:<fileData id="A004" fileName="test.txt"position="15" slice="7" size="22" timeModified="20061018T115836"><base64>ciBmaWxlIQ==</base64></fileData>
S:<response id="A004"/>

C:<fileRead id="A005" fileName="test.txt" position="25" />
S:<response id="A005" errorText="reading beyond the EOF mark" errorNum="500" />

Automated Rule Management

A client can manage the Account Automated Rules. Rules sets are addressed using the type parameter. The following parameter values are supported:

Each Rule in a set has name and priority attributes. Signal Rules also have a stage attribute, specifying when the Rule should be applied.

Each Rule contains zero or more condition elements, zero or more action elements, and zero or one comment elements:

condition
See the Rules section for more information.
Attributes:
opCode
the Rule condition data.
operator
the Rule condition operation.

Body:
the Rule condition parameter.
action
See the Rules section for more information.
Attributes:
opCode
the Rule action operation.

Body:
the Rule action parameter.
comment
Body:
the Rule comment text.

Example:
a Mail Rule storing all messages with the X-Junk: 5 header field in the Junk Mailbox. Exception is made for messages coming from authenticated users.
<rule type="mailIn" name="Junk Filter" priority="2" >
  <condition opCode="Header Field" operator="is">X-Junk: 5*</condition>
  <condition opCode="Source" operator="is not">authenticated</condition>
  <action opCode="Store in">Junk</action>
  <action opCode="Discard"></action>
  <comment>This is my test Rule&#x21;</comment>
</rule>
ruleList
This operation tells the Server to send one rule message for each Account Rule of the specified type. These messages do not have a body.
Attributes:
type
the Rule set.
ruleRead
This operation tells the Server to send one rule message for the specified Rule. This message body contains XML elements with the Rule condition(s), action(s), and an optional comment.
Attributes:
type
the Rule set.
name
the Rule name.
ruleSet
This operation stores a new Rule. If there is an existing Rule with the same name, it is removed.
The user should have a right to specify conditions and actions used in both new and old Rules.
Attributes:
type
the Rule set.
name
the Rule name.
priority
the Rule priority.
stage
the Rule stage (for Signal Rules).

Body:
the same XML elements as used in the rule message: zero or more condition elements, zero or more action elements, and zero or one comment element.
ruleUpdate
This operation modifies the existing Rule priority and/or its stage (for Signal Rules).
The user should have a right to specify conditions and actions used in the Rule to be modified.
Attributes:
type
the Rule set.
name
the Rule name.
priority
the Rule priority.
stage
the Rule stage (for Signal Rules).
ruleRename
This operation renames an existing Rule.
The user should have a right to specify conditions and actions used in the Rule to be renamed.
Attributes:
type
the Rule set.
name
the existing Rule name.
newName
the new Rule name.
ruleRemove
This operation removes an existing Rule.
The user should have a right to specify conditions and actions used in the Rule to be removed.
Attributes:
type
the Rule set.
name
the existing Rule name.

The Server sends the following data messages:

rule
This synchronous data message is sent when the Server processes the ruleList request or the ruleRead request. See above for the rule message format.

Remote POP Management

RPOP records are presented using the following XML elements:

rpopRecord
Attributes:
UID
the unique numeric record ID.
host
the domain name or the IP address of the remote mail system.
account
the mail account name in the remote mail system.
password
the mail account password in the remote mail system.
leave
the attribute is present and it has the yes value, if mail messages must not be deleted from the remote mail system after they have been retrieved.
TLS
the attribute is present and it has the yes value, if connection to the remote mail system must be established securely, using the SSL/TLS protocol.
APOP
the attribute is present and it has the yes value, if the APOP login method should be used with the remote mail system.

A client can manage the Account RPOP Account records.

rpopList
This operation tells the Server to send one rpopRecord message for each Account RPOP record.
Attributes:
none
rpopUpdate
This operation updates the Account RPOP record set.
The user should have a right to modify the Account RPOP records.
Attributes:
none

Body:
one or more rpopRecord elements. These elements must have an additional attribute:
mode
if this attribute value is delete, the only the UID attribute is used. The PROP record with the same UID attribute is removed from the Account RPOP record set.
if this attribute value is add, the RPOP record is added to the PROP record set. If the UID attribute is present, the old RPOP record with the same UID is removed from the RPOP record set. If the UID attribute is absent, the new unique UID is generated and added to the record.

The Server sends the following data messages:

rpopRecord
This synchronous data message is sent when the Server processes the rpopList request. See above for the rpopRecord message format.

Real-Time Application Management

A client can interact with the Real-Time Applications running on the CommuniGate Pro Server or Cluster.

A XIMSS session can communicate with Tasks by sending them Events. Tasks see a XIMSS session as a yet another Task, so they can send Events back to it.

Each XIMSS session maintains a list of Tasks Handles for the Tasks it communicates with. Each handle in the list is associated with an taskID string. The XIMSS client uses these taskID strings to address the Tasks in the list.

taskFindMeeting
This operation implements the FindMeeting operation. See the CG/PL section for more information.
Attributes:
meetingSet
the optional Meeting set name. If the parameter value is missing or it is an empty string, the Default Meeting Set is used.
meetingName
the unique ID or name for the Meeting.
If this operation succeeds, the Server returns a taskMeeting message with the found meeting data.
taskCreateMeeting
This operation implements the CreateMeeting operation. See the CG/PL section for more information.
Attributes:
meetingSet
the optional Meeting set name. If the parameter value is missing or it is an empty string, the Default Meeting Set is used.
meetingName
the unique ID or name for the Meeting.

Body:
The text to add to the Meeting Event as a parameter.
taskRemoveMeeting, taskClearMeeting, taskActivateMeeting, taskDeactivateMeeting
These operations implement the Meeting operations. See the CG/PL section for more information.
Attributes:
meetingSet
the optional Meeting set name. If the parameter value is missing or it is an empty string, the Default Meeting Set is used.
meetingName
the unique ID or name for the Meeting.
taskSendEvent
This operation send an Event to a Task.
Attributes:
taskRef
the internal taskID of the Task to send an Event to.
eventName
the name of the Event to send.

Body:
optional text or an XML presentation of a data object to be sent as the Event parameter.
taskStart
This operation starts a Real-Time Application Task.
If this operation succeeds, the server sends a taskCreated data message.
Attributes:
programName
the application name.
entryName
this optional attribute specified the program entry name; if not specified, the main entry is started.

Body:
a set of param XML elements. These element text bodies are placed into the Task startParameter array.
taskClose
There are some session resources associated with each internal taskID. If your client works with many different Tasks, it is recommended that it uses the taskClose operation when it ends communication with a particular Task, so its session-internal taskID is released.
If the same Task sends an Event to this session, or its Task Handle is discovered using other mechanisms, the new taskID is assigned to this Task in this session.
Attributes:
taskRef
the internal taskID to release.

The Server sends the following data messages:

taskMeeting
This synchronous data message is sent when the Server processes the taskFindMeeting request.
Attributes:
meetingSet, meetingName
copies of the taskFindMeeting request attributes.
taskRef
an optional attribute: the internal taskID of the Task that has activated this Meeting.
expires
an optional attribute with the Meeting expiration date and time (GMT).

Body:
The XML presentation of the Meeting parameters.
taskCreated
This synchronous data message is sent when the Server processes the taskStart request.
Attributes:
taskRef
the internal taskID of the created Task.
taskEvent
This asynchronous data message is sent when some Task or the Server itself sends an Event to the current XIMSS session.
Attributes:
taskRef
the internal taskID of the Task that has sent this Event. If this attribute is absent, then the Event was generated and sent by the Server itself.
eventName
the name of the received Event.

Body:
The text or the XML presentation of the Event parameter.

Directory

A client can access the global Directory.

listDirectory
This operation retrieves data from the Directory.
Attributes:
baseDN
the directory record DN to start the search from. If the attribute value is $, the baseDN is set to the Directory subtree containing records for the current Account Domain.
filter
this optional attribute specifies a search filter in the RFC2254 format.
scope
this optional attribute specifies the search type:
  • base - the baseDN record is retrieved (the filter attribute is ignored)
  • one (default) - the baseDN immediate subtree is searched (one-level search)
  • sub - the entire baseDN subtree is searched (multi-level search)
limit
this optional attribute specifies the maximum number of directory records to retrieve.

Body (optional):
a set of field XML elements. Each element should have a text body containing the name of an attribute to retrieve. If no field element is specified, all non-service Directory record attributes are retrieved.
Note: if the mail attribute is explicitly specified, the Server will compose this attribute value for all CommuniGate Pro Object records without this attribute.
The Server sends a directoryData message for each record found.

The Server sends the following data messages:

directoryData
This synchronous data message is sent for each Directory record retrieved with the listDirectory request.
Attributes:
name
the record DN.

Body:
The XML presentation of the Record attributes.

Datasets

A client can manage the Account Datasets (such as the RepliedAddresses Dataset).

To access Datasets in other Accounts, the dataset name should be specified as ~accountName/datasetName or ~accountName@domainName/datasetName

datasetRemove
This operation removes an Account dataset.
Attributes:
dataset
the name of the dataset to remove.
ifExists
if this optional attribute exists, and its value is yes, no error is generated when the specified dataset does not exist.
datasetAddAddress
This operation adds an address to an Account dataset.
Attributes:
dataset
the name of the dataset to add an E-mail address to.
realName
this optional attribute specified the E-mail "real name".

Body:
The E-mail address string.
datasetList
This operation retrieves entries from an Account dataset.
Attributes:
dataset
the name of the dataset to read.
filterField, filter
these optional attributes specify an entry attribute name and value. If specified, the operation returns only the entries that have the specified attribute with the specified value.
The Server sends a datasetData message for each record found.
datasetSet
This operation modifies entries in an Account dataset.
Attributes:
dataset
the name of the dataset to modify.

Body:
The datasetData element. Its name attribute specifies the name of the dataset entry to modify or create. If not specified, a random name is selected for a new entry.
The element body should be an XML presentation of the entry attributes to modify.
datasetDelete
This operation removes an entry from an Account dataset.
Attributes:
dataset
the name of the dataset to modify.
name
the name of the dataset entry to remove.

The Server sends the following data messages:

datasetData
This synchronous data message is sent for each dataset entry retrieved with the datasetList request.
Attributes:
name
the dataset entry name.

Body:
The XML presentation of the dataset entry attributes.

Billing

A client can manage the Account Balances.

balance
This operation performs a Billing operation.
Attributes:
accountName
the target account name (optional). If not specified, the operation is applied to the session owner Account.

Body:
The XML presentation of a dictionary. The dictionary contains the Billing operation (the op element) and the operation parameters.
If the operation produces any result, the Server sends a balanceData message.

The Server sends the following data messages:

balanceData
This synchronous data message is sent when a balance operation produces a result.
Attributes:
accountName
the target account name (optional, the same as specified with the balance operation request.

Body:
The XML presentation presentation of the result dictionary.

Banner Retrieval

A client can employ an External Banner System.

bannerRead
This operation retrieves banner info. If the operation produces any result, the Server sends a banner message.
Attributes:
type
the banner type to retrieve (application-specific, such as prontoEmailTop, myClientLeftBanner).

Body:
(optional) the XML presentation of the External Banner System parameter object.

The Server sends the following data messages:

banner
This synchronous data message is sent when a bannerRead operation produces a result.
Attributes:
type
the same value as in the bannerRead operation.

Body:
(optional) the XML presentation of the External Banner System resulting object.

XML Data Formats

Data elements are presented in the XML format using the following conventions.

EMail

This XML element represents an E-mail message or its message/rfc822 MIME subpart.

Body:
a set of XML elements containing E-mail message header fields, such as From, Date, etc., and not including MIME content-related fields (such as Content-Type),
and (optionally) a
MIME element with the message body.

The type of each XML element is the field name:

<Subject>Hello, world!</Subject>

Field categories:
Addresses: From, To, Cc, Bcc, Return-Path, Sender, Reply-To, Disposition-Notification-To, Recent-From, Recent-To, Return-Receipt-To, Errors-To
The element body is the E-mail address, in the userName@domainName format, or a more generic userName[%domainA[%domainB]]@domainName format.
These elements can contain the realName attribute - a MIME-decoded address name-part or comment.
If a field contains several addresses, then several XML elements are created, so each element contains exactly one address.
Timestamps: Date, Resent-Date
These elements contain:
the timeShift attribute - the time difference (in seconds) between the local time specified in the field and the corresponding GMT time
the localTime attribute - the field time value (in the iCalendar format) in the Time Zone selected for the current user.
The element body is the field global (GMT) time value in the iCalendar format.
Pty
These elements body are High or Low strings. These values are converted to and from numeric X-Priority header field values.
Phones: X-Telnum
The element body is a phone number.
These elements can contain the type attribute (WORK, CELL, HOME, AGENT, etc.) specifying the type of the phone number/address.
If a field contains several phone numbers, then several XML elements are created, so each element contains exactly one phone number.
Unstructured
All fields not listed in previous categories belong to this category.
The element body contains the MIME-decoded field value.

Example:
From: "Mr. Sender." <user1@example.com>
To: user2@example.com (My Friend),
 =?iso-8859-1?Q?=4Eot=20A=20Friend?= <user2@example.com>
Date: Mon, 10 Apr 2006 13:15:48 -0700
Subject: It's 1:15PM now, the meeting has started!

<EMail>
  <From realName="Mr. Sender.">user1@example.com</From>
  <To realName="My Friend">user2@example.com</To>
  <To realName="Not A Friend">user3@example.com</To>
  <Bcc>user1@example.com</Bcc>
  <Date timeShift="-25200" localTime="20060410T151548">20060410T201548Z</Date>
  <Subject>It's 1:15PM now, the meeting has started!</Subject>
</EMail>

MIME

This XML element represents a message body or its part (referred to as "part" in the rest of this section).
Attributes:
partID
this string provides the MIME part location within the message. It can be used to retrieve this message part.
estmatedSize
the estimated size (in bytes) of the part data, after the part data is decoded.
type
the part Content-Type type, without the subtype information.
subtype
the part Content-Type subtype, if present.
charset
the part character set (assume UTF-8 if the attribute is absent).
contentID
the Content-ID string (without the enclosing angle brackets).
disposition
the Content-Disposition string (without parameters).
description
the Content-Description string.
location
the Content-Location string.
class
the Content-Class string, after removing the urn: and content-classes: prefixes.
Type-name
any Content-Type field name parameter with its value, excluding the boundary, charset, and format parameters.
Disposition-name
any Content-Disposition field name parameter with its value.

Body:
The element body is optional. When present, it contains the part body data.
If the Server fails to read the element body part data, the readError attribute is added to the element. The attribute value contains the reading error code.
If the Server fails to parse the element body part data, the parserError attribute is added to the element. The attribute value contains the parsing error code.
The element format depends on the part Content-Type (the "*" symbol below means any Content-Type or subtype):
multipart/*
Zero or more MIME XML elements containing message subparts.
message/rfc822
A EMail XML element for the enclosed message.
text/rfc822-headers
An EMail XML element (not containing any MIME body element).
text/directory, text/x-vcard
Zero or more vCard XML elements.
text/x-vgroup
One vCardGroup XML element.
text/calendar
an iCalendar XML element.
message/disposition-notification, message/delivery-status
a MIMEReport XML element.
text/*
The decoded message text, with all EOL symbols replaced with the Line Feed (0x0A) symbol.
Note: When a message is being retrieved with the folderRead operation, a MIME element body is included only if its size plus the size of the parts already included into the response XML does not exceed the totalSizeLimit operation attribute.

Example:

From: <user1@example.com>
To: user2@example.com
MIME-Version: 1.0
Content-Type: multipart/alternative;boundary="abcd"
Content-Description: Test Message

--abcd
Content-Type: text/plain; charset="iso-8859-1";
format=flowed; paramX="valueX"
Content-Transfer-Encoding: quoted-printable

=46rom where I stay, I can see & hear a lot!

--abcd
Content-Type: text/html; charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

<html><body bgcolor=3D"yellow">
<I>From where I stay</I>, I can see &amp; hear a lot!
</body></html>
--abcd--

<EMail>
  <From>user1@example.com</From>
  <To>user2@example.com</To>
  <MIME Type="multipart" subtype="alternative" Description="Test Message">
    <MIME type="text" subtype="plain" charset="iso-8859-1" type-paramX="valueX">
      From where I stay, I can see &amp; hear a lot!
    </MIME>
    <MIME type="text" subtype="html" charset="iso-8859-1" type-paramX="valueX">
    &lt;html&gt;&lt;body bgcolor=&quot;yellow&quot;&gt;
    &lt;I&gt;From where I stay&lt;/I&gt;, I can see &amp;amp; hear a lot!
    &lt;/body&gt;&lt;/html&gt;
    </MIME>
  </MIME>
</EMail>

MIMEReport

This XML element represents a message report, such as Disposition Notification or a Delivery report.
Attributes:
none

Body:
a set of XML elements containing report header fields, such as Reporting-MTA, /Final-Recipient, etc.
and (optionally)
MIMEReport elements for the report body.

Example:
Subject: Delivery report: TEST - disposition and delivery
From: <MAILER-DAEMON@remote.example.com>
To: <sender@local.example.com>
Date: Wed, 02 May 2007 00:33:13 -0700
Message-ID: <receipt-39457791@remote.example.com>
X-MAPI-Message-Class: REPORT.IPM.Note.DR
MIME-Version: 1.0
Content-Type: multipart/report; report-type="delivery-status"; boundary="_===39457791====remote.example.com===_"


--_===39457791====remote.example.com===_
Content-Type: text/plain; charset="utf-8"

Message delivered to '<recepient@remote.example.com>'
LOCAL module(account recepient) reports:
Delivered to the user mailbox


--_===39457791====remote.example.com===_
Content-Type: message/delivery-status

Reporting-MTA: dns; remote.example.com

Original-Recipient: rfc822;<recepient@remote.example.com>
Final-Recipient: LOCAL;<recepient>
Action: delivered
Status: 2.0.0

--_===39457791====remote.example.com===_
Content-Type: text/rfc822-headers

From: "Sender Name" <sender@local.example.com>
Subject: TEST - disposition and delivery
To: recepient@remote.example.com
X-Mailer: CommuniGate Pro WebUser v5.1.9
Date: Wed, 02 May 2007 00:35:51 -0700
Message-ID: <web-3990004@local.example.com>
MIME-Version: 1.0
Disposition-Notification-To: <sender@local.example.com>
Content-Type: text/plain;charset="utf-8";format="flowed"
Content-Transfer-Encoding: 8bit

--_===39457791====remote.example.com===_--

<EMail>
 <Subject>Delivery report: TEST - disposition and delivery</Subject>
 <From>MAILER-DAEMON@stalker.com</From>
 <To>sender@local.example.com</To>
 <Date localTime="20070502T003313" timeShift="-25200">20070502T073313Z</Date>
 <Message-ID>&lt;receipt-39457791@remote.example.com&gt;</Message-ID>
 <X-MAPI-Message-Class>REPORT.IPM.Note.DR</X-MAPI-Message-Class>
 <MIME estimatedSize="1433" subtype="report" type="multipart" Type-report-type="delivery-status">
  <MIME charset="utf-8" estimatedSize="120" partID="01" subtype="plain" type="text">Message delivered to &#39;&lt;recepient@remote.example.com&gt;&#39;
LOCAL module(account recepient) reports:
 Delivered to the user mailbox

  </MIME>
  <MIME estimatedSize="158" partID="02" subtype="delivery-status" type="message">
   <MIMEReport>
    <Reporting-MTA>dns; remote.example.com</Reporting-MTA>
    <MIMEReport>
     <Original-Recipient>rfc822;&lt;recepient@remote.example.com&gt;</Original-Recipient>
     <Final-Recipient>LOCAL;&lt;recepient&gt;</Final-Recipient>
     <Action>delivered</Action>
     <Status>2.0.0</Status>
    </MIMEReport>
   </MIMEReport>
  </MIME>
  <MIME estimatedSize="787" partID="03" subtype="rfc822-headers" type="text">
   <EMail>
    <From realName="Sender Name">sender@local.example.com</From>
    <Subject>TEST - disposition and delivery</Subject>
    <To>recepient@remote.example.com</To>
    <X-Mailer>CommuniGate Pro WebUser v5.1.9</X-Mailer>
    <Date localTime="20070502T003551" timeShift="-25200">20070502T073551Z</Date>
    <Message-ID>&lt;web-3990004@local.example.com&gt;</Message-ID>
    <Disposition-Notification-To>sender@local.example.com</Disposition-Notification-To>
   </EMail>
  </MIME>
 </MIME>
</EMail>

HTTP Access

Some clients may be unable to implement all operations via the XIMSS protocol. When a XIMSS session is created, its ID is reported back to the client using the session data message. The Server provides access to that session via the HTTP protocol.

Message Part Retrieval

The following URL can be used to retrieve any part of a message visible in any currently opened Folder:
/Session/sessionID/MIME/folder/UID-partID-suffix[/filename]
where
sessionID
the current XIMSS session ID, sent with the session data message
folder
the target Folder name or the target Calendar name
UID
the target message UID in the target Folder or Calendar
partID
the id of the requested message MIME part. This is the string reported in the MIME XML element when the message was retrieved using the folderRead operation. If the entire message is to be retrieved, the partID string and the following - symbol should be omitted.
suffix
the retrieval mode:
  • P.txt - the entire undecoded part (including the headers and the body) is retrieved.
  • H.txt - the part headers are retrieved.
  • B.extension - the decoded part body is retrieved. You can use any appropriate file name extension. The HTTP response gets the Content-Type of the retrieved MIME part.
  • R/cid - the cid string should be URI-encoded. Its decoded value specifies a MIME-part Content-ID. The Server searches all MIME parts "related" to the current one, and retrieves the body of the part with the matching Content-ID.
    This feature is used to convert cid:-type URLs in HTML-formatted messages.
filename
an optional file name. It is ignored by the Server, but it can help the user browser to store the file under the proper name.
Examples:
C:GET /Session/1-2xklkdld8-djdkjk/MIME/INBOX/567-01-B.gif HTTP/1.1

C:GET /Session/1-2xklkdld8-djdkjk/MIME/INBOX/567-02-01-B.gif/Logo.gif HTTP/1.1

File Uploading

The following URL can be used to upload a file to the session "uploaded file set".
/Session/sessionID/UPLOAD/uploadID
where
sessionID
the current XIMSS session ID, sent with the session data message.
uploadID
a string identifying this file in the "uploaded file set".

The request body should contain a file in the raw (binary) form, as a body element with the fileData name.

When the file is uploaded and added to the "uploaded file set", the Server returns the 200 response code. If uploading failed, the Server returns the 500 response code.

The uploaded file is stored together with its Content-Type value.

If the "uploaded file set" already contains a file with the specified uploadID value, the old file is removed.

File Downloading

The following URL can be used to download a file from the session Account File Storage.
/Session/sessionID/DOWNLOAD/fileName
where
sessionID
the current XIMSS session ID, sent with the session data message.
fileName
the file name in the session Account File Storage.
Note: to download a file from the "uploaded file set", specify the fileName as $UPLOAD$/uploadId, where uploadId is the "uploaded file set" file identifier.

CommuniGate® Pro Guide. Copyright © 1998-2008, Stalker Software, Inc.