Cisco Unity Connection Messaging Interface (CUMI) API -- Using the CUMI API

From DocWiki

(Difference between revisions)
Jump to: navigation, search
Line 49: Line 49:
<br>
<br>
Doing a GET on a Folder returns a small folder resource object and a reference to its list of Messages:
Doing a GET on a Folder returns a small folder resource object and a reference to its list of Messages:
-
<pre>&lt;Folder&gt;&nbsp;
+
<pre>
 +
<Folder>
&lt;DisplayName&gt;&lt;/DisplayName&gt;
&lt;DisplayName&gt;&lt;/DisplayName&gt;
&lt;MessageCount&gt;&lt;/MessageCount&gt;
&lt;MessageCount&gt;&lt;/MessageCount&gt;
-
&lt;/Folder&gt;
+
</Folder>
</pre>  
</pre>  
Line 59: Line 60:
<pre>
<pre>
GET /vmrest/mailbox/folders/inbox/messages
GET /vmrest/mailbox/folders/inbox/messages
 +
</pre>
 +
 +
A PUT API call can be used on Messages in the Inbox folder to update the Subject on the Messages. No other parameter on a message can be changed:
 +
<pre>
 +
PUT /vmrest/messages/<messageid>
 +
<Message>
 +
    <Subject>New subject</Subject>
 +
</Message>
</pre>
</pre>
Line 65: Line 74:
<pre>
<pre>
GET /vmrest/mailbox/folders/sent/messages
GET /vmrest/mailbox/folders/sent/messages
 +
</pre>
 +
 +
A PUT API call can be used on Messages in the Sent Items folder to update the Subject on the Messages. No other parameter on a message can be changed:
 +
<pre>
 +
PUT /vmrest/messages/<messageid>
 +
<Message>
 +
    <Subject>New subject</Subject>
 +
</Message>
</pre>
</pre>
Line 73: Line 90:
</pre>
</pre>
-
Doing a GET on &lt;folder&gt;/messages returns a message list:  
+
A PUT API call can be used on Messages in the Deleted Items folder to update the Subject on the Messages. No other parameter on a message can be changed:
-
<pre>&lt;Messages&gt;
+
<pre>
-
&lt;Message&gt;&nbsp;
+
PUT /vmrest/messages/<messageid>
-
...&nbsp;
+
<Message>
-
&lt;/Message&gt;&nbsp;
+
    <Subject>New subject</Subject>
-
&lt;Message&gt;&nbsp;
+
</Message>
-
...&nbsp;
+
</pre>
-
&lt;/Message&gt;&nbsp;
+
 
-
...&lt;/Messages&gt;
+
-
</pre>  
+
HTTP requests for Messages differ by folder, so they are listed here separately for each folder:  
HTTP requests for Messages differ by folder, so they are listed here separately for each folder:  

Revision as of 06:53, 5 March 2012

Back to: CUMI API Overview

Contents



About Mailboxes and Folders

The root of the Cisco Unity Connection Messaging Interface (CUMI) API is the Mailbox resource that is associated with each user. This contains some general information about the user's mailbox, and also contains a Folders resource that lists the folders for the mailbox. This list is currently fixed, although it is possible that folders may be added in the future.

Doing a GET on the Mailbox returns properties of the mailbox (for example, quotas) as well as a link to the Folders element for the mailbox:

GET /vmrest/mailbox
<xs:complexType name="Mailbox">
<xs:all>
<xs:element name="DisplayName" type="xs:string" />
<xs:element name="CurrentSizeInBytes" type="xs:long" />
<xs:element name="IsPrimary" type="xs:boolean" />
<xs:element name="IsStoreMounted" type="xs:boolean" />
<xs:element name="IsStoreOverFlowed" type="xs:boolean" />
<xs:element name="IsMailboxMounted" type="xs:boolean" />
<xs:element name="IsWarningQuotaExceeded" type="xs:boolean" />
<xs:element name="IsReceiveQuotaExceeded" type="xs:boolean" />
<xs:element name="IsSendQuotaExceeded" type="xs:boolean" />
<xs:element name="WarningQuota" type="xs:long" />
<xs:element name="ReceiveQuota" type="xs:long" />
<xs:element name="SendQuota" type="xs:long" />
<xs:element name="IsDeletedFolderEnabled" type="xs:boolean" />
<xs:element name="FoldersURI" type="xs:anyURI" />
</xs:all>
</xs:complexType>

Mailbox Folder Operations

There are three Folders currently supported on a Unity Connection Mailbox -

  • Inbox
  • Sent Items
  • Deleted Items

Doing a GET on the Folders returns the fixed list of folders:

GET /vmrest/mailbox/folders

A Folder consists of a small set of properties (DisplayName and MessageCount) and a collection of Messages.
Doing a GET on a Folder returns a small folder resource object and a reference to its list of Messages:

<Folder>
<DisplayName></DisplayName>
<MessageCount></MessageCount>
</Folder>

Inbox Folder Operations

A GET API call on the folder returns a message list:

GET /vmrest/mailbox/folders/inbox/messages

A PUT API call can be used on Messages in the Inbox folder to update the Subject on the Messages. No other parameter on a message can be changed:

PUT /vmrest/messages/<messageid>
<Message>
     <Subject>New subject</Subject>
</Message>

Sent Items Folder Operations

A GET API call on the folder returns a message list:

GET /vmrest/mailbox/folders/sent/messages

A PUT API call can be used on Messages in the Sent Items folder to update the Subject on the Messages. No other parameter on a message can be changed:

PUT /vmrest/messages/<messageid>
<Message>
     <Subject>New subject</Subject>
</Message>

Deleted Items Folder Operations

A GET API call on the folder returns a message list:

GET /vmrest/mailbox/folders/deleted/messages

A PUT API call can be used on Messages in the Deleted Items folder to update the Subject on the Messages. No other parameter on a message can be changed:

PUT /vmrest/messages/<messageid>
<Message>
     <Subject>New subject</Subject>
</Message>

HTTP requests for Messages differ by folder, so they are listed here separately for each folder:


Folder Request Description
inbox/messages GET Returns read and unread messages that are not drafts or deleted messages.
inbox/messages PUT Can be used to update the message subject only.
inbox/messages DELETE Depending on system settings, either removes message or moves it to the "deleted" folder.
inbox/messages POST?method=accept Causes a dispatch message to be accepted.
inbox/messages POST?method=reject Causes a dispatch message to be rejected.
deleted/messages GET Returns list of deleted messages (if the system is set to "soft" delete - otherwise the list will always be empty).
deleted/messages DELETE Removes messages from the deleted folder (does a "hard" delete).
deleted/messages POST?method=empty Empties the deleted folder (permanently removes all messages in the folder).
deleted/messages POST?method=undelete Undeletes the specified message.
sent/messages GET Returns a list of recently sent messages.
sent/messages DELETE Deletes a message from the sent list.

A dispatch message is a message that needs to go to one and only one member of a group. When the message is accepted by any one user, it is no longer available to other users. When the message is rejected by a user in the group, it is removed from the user's voicemail list.

Offset and Limit

Each of the folders will accept the parameters "pagenumber" and "rowsperpage" to specify which messages to retrieve:

/vmrest/mailbox/folders/inbox/messages?pagenumber=1&rowsperpage=10

Sorting

Initially, server-side sorting will be limited to what can be done efficiently by the database, and will default to placing new messages first, followed by read messages, and sorted within each by ArrivalTime.

As recommended in the VTG REST guidelines, sorting will be controlled via "sortkey" and "sortorder" parameters, although initially only the following sort orders will be supported by the server:

Sort Description Sort Parameters
Newest first no parameters (default) or sortkey=arrivaltime&sortorder=descending
Oldest first sortkey=arrivaltime&sortorder=ascending
Urgent first sortkey=priority&sortorder=descending


Filtering

Filtering can be done on the folders by read, priority, voice, fax and dispatch.

read={true|false}
priority={urgent|normal|low}
dispatch={true|false}
type={voice|fax|email|receipt}

Examples

To get a list of unheard voice messages:

GET /vmrest/mailbox/folders/inbox/messages?read=false&type=voice

To get a list of unheard urgent messages:

GET /vmrest/mailbox/folders/inbox/messages?read=false&priority=urgent

To get a list of saved (deleted) messages:

GET /vmrest/mailbox/folders/deleted/messages



Back to: CUMI API Overview

Rating: 4.3/5 (3 votes cast)

Personal tools