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

From DocWiki

(Difference between revisions)
Jump to: navigation, search
m (1 revision)
 
(15 intermediate revisions not shown)
Line 4: Line 4:
|}
|}
-
__TOC__
+
__TOC__  
-
+
<br>
-
== 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.
+
== About Mailboxes and Folders ==
-
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:
+
The root of 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.
-
<pre>
+
Beginning with Cisco Unity Connection 10.5 and later, when one or more tenants are configured on a single installation of Cisco Unity Connection, a user with '''Mailbox Access Delegate Account''' role and belonging to a particular tenant will be able to list messages of all the users within the same tenant only.
-
GET /vmrest/mailbox
+
-
<xs:complexType name="Mailbox">
+
GET operation on the Mailbox returns properties of the mailbox (for example, quotas) as well as a link to the Folders element for the mailbox:
-
<xs:all>
+
<pre>GET /vmrest/mailbox
-
<xs:element name="DisplayName" type="xs:string" />
+
&lt;xs:complexType name="Mailbox"&gt;
-
<xs:element name="CurrentSizeInBytes" type="xs:long" />
+
&lt;xs:all&gt;
-
<xs:element name="IsPrimary" type="xs:boolean" />
+
&lt;xs:element name="DisplayName" type="xs:string" /&gt;
-
<xs:element name="IsStoreMounted" type="xs:boolean" />
+
&lt;xs:element name="CurrentSizeInBytes" type="xs:long" /&gt;
-
<xs:element name="IsStoreOverFlowed" type="xs:boolean" />
+
&lt;xs:element name="IsPrimary" type="xs:boolean" /&gt;
-
<xs:element name="IsMailboxMounted" type="xs:boolean" />
+
&lt;xs:element name="IsStoreMounted" type="xs:boolean" /&gt;
-
<xs:element name="IsWarningQuotaExceeded" type="xs:boolean" />
+
&lt;xs:element name="IsStoreOverFlowed" type="xs:boolean" /&gt;
-
<xs:element name="IsReceiveQuotaExceeded" type="xs:boolean" />
+
&lt;xs:element name="IsMailboxMounted" type="xs:boolean" /&gt;
-
<xs:element name="IsSendQuotaExceeded" type="xs:boolean" />
+
&lt;xs:element name="IsWarningQuotaExceeded" type="xs:boolean" /&gt;
-
<xs:element name="WarningQuota" type="xs:long" />
+
&lt;xs:element name="IsReceiveQuotaExceeded" type="xs:boolean" /&gt;
-
<xs:element name="ReceiveQuota" type="xs:long" />
+
&lt;xs:element name="IsSendQuotaExceeded" type="xs:boolean" /&gt;
-
<xs:element name="SendQuota" type="xs:long" />
+
&lt;xs:element name="WarningQuota" type="xs:long" /&gt;
-
<xs:element name="IsDeletedFolderEnabled" type="xs:boolean" />
+
&lt;xs:element name="ReceiveQuota" type="xs:long" /&gt;
-
<xs:element name="FoldersURI" type="xs:anyURI" />
+
&lt;xs:element name="SendQuota" type="xs:long" /&gt;
-
</xs:all>
+
&lt;xs:element name="IsDeletedFolderEnabled" type="xs:boolean" /&gt;
-
</xs:complexType>
+
&lt;xs:element name="FoldersURI" type="xs:anyURI" /&gt;
 +
&lt;/xs:all&gt;
 +
&lt;/xs:complexType&gt;
</pre>
</pre>
-
Doing a GET on the Folders returns the fixed list of folders:
+
== Mailbox Folder Operations  ==
 +
 
 +
There are three folders currently supported on a Unity Connection Mailbox -
 +
 
 +
*Inbox
 +
*Sent Items
 +
*Deleted Items
 +
Performing GET operation on the folders returns the fixed list of folders:
<pre>
<pre>
GET /vmrest/mailbox/folders
GET /vmrest/mailbox/folders
</pre>
</pre>
 +
Following are the properties associated with each folder:
-
A '''Folder''' consists of a small set of properties (DisplayName and MessageCount) and a collection of Messages.
+
*DisplayName
-
 
+
*MessageCount
-
Doing a GET on a Folder returns a small folder resource object and a reference to its list of Messages:
+
*Unique Serial Number (Unity Connection 11.5 and later)
 +
*UIDValidity (Unity Connection 11.5 and later)
 +
A GET operation on a folder returns the associated properties.
<pre>
<pre>
-
<Folder> 
+
GET /vmrest/mailbox/folders/<folder_name>
-
<DisplayName></DisplayName>
+
-
<MessageCount></MessageCount>
+
-
</Folder>
+
</pre>
</pre>
 +
Following is the response of above GET request.
 +
<pre>
 +
<Folder>
 +
&lt;DisplayName&gt;&lt;/DisplayName&gt;
 +
&lt;MessageCount&gt;&lt;/MessageCount&gt;
 +
&lt;USN&gt;&lt;/USN&gt;
 +
&lt;UIDValidity&gt;&lt;/UIDValidity&gt;
 +
</Folder>
 +
</pre>
-
Doing a GET on <folder>/messages returns a message list:
+
'''Note:''' Each time an operation is performed on Inbox folder or Delete folder, the Unique Serial Number (USN) of both the folders changes.
 +
=== Inbox Folder Operations ===
 +
All folder operations can be executed by a user when connecting with his/her credentials.
 +
When using the administrative credentials, using the userobjectid parameter will allow administrators to do the same operations on the users mailbox.
 +
 +
A GET operation on a folder returns a message list:
<pre>
<pre>
-
<Messages>
+
GET /vmrest/mailbox/folders/inbox/messages
-
<Message> 
+
</pre>
-
... 
+
A user with administrative privileges can list the messages of another users folder by passing the userobjectid of the other user:
-
</Message> 
+
<pre>
-
<Message> 
+
GET /vmrest/mailbox/folders/inbox/messages?userobjectid=<userobjectid>
-
... 
+
</pre>
-
</Message> 
+
A user with administrative privileges can list the messages of another users folder having USN value greater than specified and by passing the userobjectid of the other user:
-
...</Messages>
+
<pre>
 +
GET /vmrest/mailbox/folders/inbox/messages?userobjectid=<userobjectid>&usngreaterthan=<value>
 +
</pre>
 +
A PUT operation on messages in Inbox folder can update the Subject or the Read field of the Messages. No other parameter of a message can be changed:
 +
<pre>
 +
PUT /vmrest/messages/<messageid>
 +
<Message>
 +
    <Subject>New subject</Subject>
 +
</Message>
</pre>
</pre>
-
HTTP requests for Messages differ by folder, so they are listed here separately for each folder:
+
A DELETE operation on messages in Inbox folder can delete the message from the folder. Whether the message is soft or hard deleted is dependent on the settings of the system.
 +
<pre>
 +
DELETE /vmrest/messages/<message-id>
 +
</pre>
 +
A hard or soft delete can be forced by passing in the harddelete parameter:
 +
<pre>
 +
DELETE /vmrest/messages/<message-id>?userobjectid=<userobjectid>&harddelete=<true or false>
 +
</pre>
 +
=== Sent Items Folder Operations ===
 +
All folder operations can be executed by a user when connecting with his/her credentials.
 +
When using the administrative credentials, using the userobjectid parameter will allow administrators to do the same operations on the users mailbox.
 +
 +
A GET operation on the folder returns a message list:
 +
<pre>
 +
GET /vmrest/mailbox/folders/sent/messages
 +
</pre>
 +
A user with administrative privileges can list the messages of another users folder by passing the userobjectid of the other user:<pre>
 +
GET /vmrest/mailbox/folders/sent/messages?userobjectid=<userobjectid>
 +
</pre>
 +
A user with administrative privileges can list the messages of another users folder having USN value greater than specified and by passing the userobjectid of the other user:
 +
<pre>
 +
GET /vmrest/mailbox/folders/sent/messages?userobjectid=<userobjectid>&usngreaterthan=<value>
 +
</pre>
 +
A PUT operation on messages in the Sent Items folder can update the Subject of messages. No other parameter on a message can be changed:
 +
<pre>
 +
PUT /vmrest/messages/<messageid>
 +
<Message>
 +
    <Subject>New subject</Subject>
 +
</Message>
 +
</pre>
-
{| border="1" cellspacing="0" cellpadding="5" align="center"
+
A DELETE operation on messages in the Sent Items folder can delete the message from the folder. Whether the message is soft or hard deleted is dependent on the settings of the system.
-
! Folder
+
<pre>
-
! Request
+
DELETE /vmrest/messages/<message-id>
-
! Description
+
</pre>
-
|-
+
A hard or soft delete can be forced by passing in the harddelete prarameter:
-
| inbox/messages
+
<pre>
-
| GET
+
DELETE /vmrest/messages/<message-id>?userobjectid=<userobjectid>&harddelete=<true or false>
-
| Returns read and unread messages that are not drafts or deleted messages.
+
</pre>
-
|-
+
-
| 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.
+
=== Deleted Items Folder Operations ===
 +
All folder operations can be executed by a user when connecting with his/her credentials.
 +
When using the administrative credentials, using the userobjectid parameter will allow administrators to do the same operations on the users mailbox.
 +
 +
A GET operation on the folder returns a message list:
 +
<pre>
 +
GET /vmrest/mailbox/folders/deleted/messages
 +
</pre>
 +
A user with administrative privileges can list the messages of another users folder by passing the userobjectid of the other user:
 +
<pre>
 +
GET /vmrest/mailbox/folders/deleted/messages?userobjectid=<userobjectid>
 +
</pre>
 +
A user with administrative privileges can list the messages of another users folder having USN value greater than specified and by passing the userobjectid of the other user:
 +
<pre>
 +
GET /vmrest/mailbox/folders/deleted/messages?userobjectid=<userobjectid>&usngreaterthan=<value>
 +
</pre>
-
=== Offset and Limit ===
+
A PUT operation on messages in the Deleted 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>
-
Each of the folders will accept the parameters "pagenumber" and "rowsperpage" to specify which messages to retrieve:
+
A DELETE operation on messages in the Deleted Items folder will delete the message from the folder. This is a hard (permanent) delete.
 +
<pre>
 +
DELETE /vmrest/messages/<message-id>
 +
</pre>
 +
A POST operation on the Deleted Items folder can be used to empty the whole folder. The messages are hard deleted.
<pre>
<pre>
-
/vmrest/mailbox/folders/inbox/messages?pagenumber=1&rowsperpage=10
+
POST /vmrest/mailbox/folders/deleted/messages?method=empty
</pre>
</pre>
-
== Sorting ==
+
=== Offset and Limit  ===
-
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.
+
Each of the folders will accept the parameters "pagenumber" and "rowsperpage" to specify which messages to retrieve:
 +
<pre>/vmrest/mailbox/folders/inbox/messages?pagenumber=1&amp;rowsperpage=10
 +
</pre>
-
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:
+
== 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:  
{| border="1" cellspacing="0" cellpadding="5" align="center"
{| border="1" cellspacing="0" cellpadding="5" align="center"
-
! Sort Description
+
|-
 +
! Sort Description  
! Sort Parameters
! Sort Parameters
-
|-
 
-
| Newest first
 
-
| no parameters (default) or sortkey=arrivaltime&sortorder=descending
 
|-
|-
-
| Oldest first
+
| Newest first
-
| sortkey=arrivaltime&sortorder=ascending
+
| no parameters (default) or sortkey=arrivaltime&amp;sortorder=descending
 +
|-
 +
| Oldest first  
 +
| sortkey=arrivaltime&amp;sortorder=ascending
|-
|-
-
| Urgent first
+
| Urgent first  
-
| sortkey=priority&sortorder=descending
+
| sortkey=priority&amp;sortorder=descending
|}
|}
 +
<br>
-
== Filtering ==
+
== Filtering ==
-
Filtering can be done on the folders by read, priority, voice, fax and dispatch.
+
Filtering can be done on the folders by read, priority, dispatch, type, and USN of the message.  
-
 
+
<pre>read={true|false}
-
<pre>
+
-
read={true|false}
+
priority={urgent|normal|low}
priority={urgent|normal|low}
dispatch={true|false}
dispatch={true|false}
type={voice|fax|email|receipt}
type={voice|fax|email|receipt}
-
</pre>
+
usngreaterthan={Integer}
-
 
+
</pre>  
-
=== Examples ===
+
=== Examples ===
-
 
+
-
To get a list of unheard voice messages:
+
-
<pre>
+
To get a list of unheard voice messages:
-
GET /vmrest/mailbox/folders/inbox/messages?read=false&type=voice
+
<pre>GET /vmrest/mailbox/folders/inbox/messages?read=false&amp;type=voice
 +
</pre>
 +
To get a list of unheard urgent messages:
 +
<pre>GET /vmrest/mailbox/folders/inbox/messages?read=false&amp;priority=urgent
 +
</pre>
 +
To get a list of saved (deleted) messages:
 +
<pre>GET /vmrest/mailbox/folders/deleted/messages
</pre>
</pre>
-
 
+
To get a list of messages with USN greater than 10:
-
To get a list of unheard urgent messages:
+
<pre>GET /vmrest/mailbox/folders/inbox/messages?usngreaterthan=10
-
 
+
</pre>  
-
<pre>
+
<br>  
-
GET /vmrest/mailbox/folders/inbox/messages?read=false&priority=urgent
+
-
</pre>
+
-
 
+
-
To get a list of saved (deleted) messages:
+
-
 
+
-
<pre>
+
-
GET /vmrest/mailbox/folders/deleted/messages
+
-
</pre>
+
-
 
+
----
----
Line 188: Line 232:
|}
|}
-
 
+
[[Category:Cisco_Unity_Connection_Messaging_Interface_(CUMI)_API]]
-
[[Category:Cisco Unity Connection Messaging Interface (CUMI) API]]
+

Latest revision as of 09:21, 7 June 2016

Back to: CUMI API Overview

Contents



About Mailboxes and Folders

The root of 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.

Beginning with Cisco Unity Connection 10.5 and later, when one or more tenants are configured on a single installation of Cisco Unity Connection, a user with Mailbox Access Delegate Account role and belonging to a particular tenant will be able to list messages of all the users within the same tenant only.

GET operation 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

Performing GET operation on the folders returns the fixed list of folders:

GET /vmrest/mailbox/folders

Following are the properties associated with each folder:

  • DisplayName
  • MessageCount
  • Unique Serial Number (Unity Connection 11.5 and later)
  • UIDValidity (Unity Connection 11.5 and later)

A GET operation on a folder returns the associated properties.

GET /vmrest/mailbox/folders/<folder_name>

Following is the response of above GET request.

<Folder>
<DisplayName></DisplayName>
<MessageCount></MessageCount>
<USN></USN>
<UIDValidity></UIDValidity>
</Folder>

Note: Each time an operation is performed on Inbox folder or Delete folder, the Unique Serial Number (USN) of both the folders changes.

Inbox Folder Operations

All folder operations can be executed by a user when connecting with his/her credentials. When using the administrative credentials, using the userobjectid parameter will allow administrators to do the same operations on the users mailbox.

A GET operation on a folder returns a message list:

GET /vmrest/mailbox/folders/inbox/messages

A user with administrative privileges can list the messages of another users folder by passing the userobjectid of the other user:

GET /vmrest/mailbox/folders/inbox/messages?userobjectid=<userobjectid>

A user with administrative privileges can list the messages of another users folder having USN value greater than specified and by passing the userobjectid of the other user:

GET /vmrest/mailbox/folders/inbox/messages?userobjectid=<userobjectid>&usngreaterthan=<value>

A PUT operation on messages in Inbox folder can update the Subject or the Read field of the Messages. No other parameter of a message can be changed:

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

A DELETE operation on messages in Inbox folder can delete the message from the folder. Whether the message is soft or hard deleted is dependent on the settings of the system.

DELETE /vmrest/messages/<message-id>

A hard or soft delete can be forced by passing in the harddelete parameter:

DELETE /vmrest/messages/<message-id>?userobjectid=<userobjectid>&harddelete=<true or false>

Sent Items Folder Operations

All folder operations can be executed by a user when connecting with his/her credentials. When using the administrative credentials, using the userobjectid parameter will allow administrators to do the same operations on the users mailbox.

A GET operation on the folder returns a message list:

GET /vmrest/mailbox/folders/sent/messages
A user with administrative privileges can list the messages of another users folder by passing the userobjectid of the other user:
GET /vmrest/mailbox/folders/sent/messages?userobjectid=<userobjectid>

A user with administrative privileges can list the messages of another users folder having USN value greater than specified and by passing the userobjectid of the other user:

GET /vmrest/mailbox/folders/sent/messages?userobjectid=<userobjectid>&usngreaterthan=<value>

A PUT operation on messages in the Sent Items folder can update the Subject of messages. No other parameter on a message can be changed:

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

A DELETE operation on messages in the Sent Items folder can delete the message from the folder. Whether the message is soft or hard deleted is dependent on the settings of the system.

DELETE /vmrest/messages/<message-id>

A hard or soft delete can be forced by passing in the harddelete prarameter:

DELETE /vmrest/messages/<message-id>?userobjectid=<userobjectid>&harddelete=<true or false>

Deleted Items Folder Operations

All folder operations can be executed by a user when connecting with his/her credentials. When using the administrative credentials, using the userobjectid parameter will allow administrators to do the same operations on the users mailbox.

A GET operation on the folder returns a message list:

GET /vmrest/mailbox/folders/deleted/messages

A user with administrative privileges can list the messages of another users folder by passing the userobjectid of the other user:

GET /vmrest/mailbox/folders/deleted/messages?userobjectid=<userobjectid>

A user with administrative privileges can list the messages of another users folder having USN value greater than specified and by passing the userobjectid of the other user:

GET /vmrest/mailbox/folders/deleted/messages?userobjectid=<userobjectid>&usngreaterthan=<value>

A PUT operation 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>

A DELETE operation on messages in the Deleted Items folder will delete the message from the folder. This is a hard (permanent) delete.

DELETE /vmrest/messages/<message-id>

A POST operation on the Deleted Items folder can be used to empty the whole folder. The messages are hard deleted.

POST /vmrest/mailbox/folders/deleted/messages?method=empty

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, dispatch, type, and USN of the message.

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

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

To get a list of messages with USN greater than 10:

GET /vmrest/mailbox/folders/inbox/messages?usngreaterthan=10



Back to: CUMI API Overview

Rating: 4.0/5 (7 votes cast)

Personal tools