privateMessageService

Provides the ability to manipulate private messages. The abilities provided through this service -- including getting, creating, sending, moving, and deleting messages -- are available to the application's users when the private message feature is enabled. This service doesn't provide configuration (administrative) abilities.

Method	Description
createFolder	Creates a new private message folder for the specified user.
createMessage	Creates a new private message from the specified user.
deleteFolder	Deletes the specified message folder.
deleteMessage	Deletes a private message from the specified folder by moving it to the trash folder.
getFolder	Returns the specified message folder for a user.
getFolders	Returns a list of message folders for the specified user.
getMessage	Returns the specified private message.
getMessageCount	Returns the total number of private messages a user has in their mailbox.
getMessageCountForFolder	Returns the number of messages in the specified folder.
getMessages	Returns all the messages in the specified folder sorted by date in descending order.
getUnreadMessageCount	Returns the total number of unread messages a user has in their mailbox.
getUnreadMessageCountForFolder	Returns the total number of unread private messages a user has in the specified folder.
isPrivateMessagesEnabled	Returns <tt>true</tt> if private messaging is enabled; <tt>false</tt> otherwise.
moveMessage	Moves a private message to another message folder.
saveMessageAsDraft	Saves a message as a draft by storing it in the sender's <tt>Drafts</tt> folder.
sendMessage	Sends a private message to another user.

createFolder

Creates a new private message folder for the specified user.

POST http://domain:port/application_context/rpc/rest/privateMessageService/folders

Arguments

Name	Type	Description
userID	xs:long	ID of the user to create the folder for.
name	xs:string	The name of the folder to create.

Arguments Template

<createFolder> 
    <userID>xs:long</userID>
    <name>xs:string</name>
</createFolder>

Response

Type	Description
PrivateMessageFolder	The new folder.

Response Template

<createFolderResponse> 
    <return>
        <!-- Contents of PrivateMessageFolder -->
    <return>
</createFolderResponse>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
UserNotFound	If the specified user is not a user in the system.

createMessage

Creates a new private message from the specified user. The message must be either saved as a draft or sent to another user in order to be stored. See other operations of this service for saving and sending.

POST http://domain:port/application_context/rpc/rest/privateMessageService/messages

Arguments

Name	Type	Description
senderID	xs:long	ID of the user sending the message.

Arguments Template

<createMessage> 
    <senderID>xs:long</senderID>
</createMessage>

Response

Type	Description
PrivateMessage	The newly created message.

Response Template

<createMessageResponse> 
    <return>
        <!-- Contents of PrivateMessage -->
    <return>
</createMessageResponse>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
UserNotFound	If the specified user is not a user in the system.
com.jivesoftware.community.RejectedException	If the message could not be created.

deleteFolder

Deletes the specified message folder. All messages in the folder will be moved to the user's Trash folder. Attempting to delete one of the four default folders will move all messages in the folder to Trash but won't delete the folder itself. If the folder is the Trash folder, all messages in the folder will be permanently deleted.

DELETE http://domain:port/application_context/rpc/rest/privateMessageService/folders/{userID}/{folderID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user the folder belongs to.
folderID	xs:int	ID of the folder to delete.

Arguments Template

<deleteFolder> 
    <userID>xs:long</userID>
    <folderID>xs:int</folderID>
</deleteFolder>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
UserNotFound	If the specified user is not a user in the system.
com.jivesoftware.community.PrivateMessageFolderNotFoundException	If the specified folder isn't there.

deleteMessage

Deletes a private message from the specified folder by moving it to the trash folder. Messages in the Trash folder will be routinely automatically deleted. If the specified folder is the Trash folder, this method will do nothing.

DELETE http://domain:port/application_context/rpc/rest/privateMessageService/userMessages/{userID}/{messageID}

Arguments

Name	Type	Description
userID	xs:long	ID of the private message to delete.
messageID	xs:long	ID of the user this message and folder belong to.

Arguments Template

<deleteMessage> 
    <userID>xs:long</userID>
    <messageID>xs:long</messageID>
</deleteMessage>

Errors

Error	When Returned
UserNotFound	If the specified user is not a user in the system.
com.jivesoftware.community.PrivateMessageFolderNotFoundException	If the specified folder isn't there.
com.jivesoftware.community.PrivateMessageNotFoundException	If the specified message wasn't found.
Unauthorized	If the caller is neither an administrator nor the specified user.

getFolder

Returns the specified message folder for a user.

GET http://domain:port/application_context/rpc/rest/privateMessageService/folders/{userID}/{folderID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user the folder belongs to.
folderID	xs:int	ID the folder to get.

Arguments Template

<getFolder> 
    <userID>xs:long</userID>
    <folderID>xs:int</folderID>
</getFolder>

Response

Type	Description
PrivateMessageFolder	The user's message folder.

Response Template

<getFolderResponse> 
    <return>
        <!-- Contents of PrivateMessageFolder -->
    <return>
</getFolderResponse>

Errors

Error	When Returned
com.jivesoftware.community.PrivateMessageFolderNotFoundException	If the specified folder isn't there.
Unauthorized	If the caller is neither an administrator nor the specified user.
UserNotFound	If the specified user is not a user in the system.

getFolders

Returns a list of message folders for the specified user. The four built-in folders (Inbox, Sent, Drafts, Trash) are returned first, followed by the user's custom folders in alphabetical order.

GET http://domain:port/application_context/rpc/rest/privateMessageService/folders/{userID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user the message folders belong to.

Arguments Template

<getFolders> 
    <userID>xs:long</userID>
</getFolders>

Response

Type	Description
List of PrivateMessageFolder	A list of the user's message folders.

Response Template

<getFoldersResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of PrivateMessageFolder -->
    <return>
</getFoldersResponse>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
UserNotFound	If the specified user is not a user in the system.

getMessage

Returns the specified private message.

GET http://domain:port/application_context/rpc/rest/privateMessageService/messages/{privateMessageID}

Arguments

Name	Type	Description
privateMessageID	xs:long	ID of the private message to get.

Arguments Template

<getMessage> 
    <privateMessageID>xs:long</privateMessageID>
</getMessage>

Response

Type	Description
PrivateMessage	The message.

Response Template

<getMessageResponse> 
    <return>
        <!-- Contents of PrivateMessage -->
    <return>
</getMessageResponse>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
com.jivesoftware.community.PrivateMessageNotFoundException	If the specified message wasn't found.

getMessageCount

Returns the total number of private messages a user has in their mailbox. This calculation does not count messages in the user's Trash folder.

GET http://domain:port/application_context/rpc/rest/privateMessageService/messageCount/{userID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user whose messages should be counted.

Arguments Template

<getMessageCount> 
    <userID>xs:long</userID>
</getMessageCount>

Response

Type	Description
xs:int	The total number of private messages the user has.

Response Template

<getMessageCountResponse> 
    <return>xs:int</return>
</getMessageCountResponse>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
UserNotFound	If the specified user is not a user in the system.

getMessageCountForFolder

Returns the number of messages in the specified folder.

GET http://domain:port/application_context/rpc/rest/privateMessageService/messsageCount/{userID}/{folderID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user whose messages should be counted.
folderID	xs:int	ID of the folder in which to count messages.

Arguments Template

<getMessageCountForFolder> 
    <userID>xs:long</userID>
    <folderID>xs:int</folderID>
</getMessageCountForFolder>

Response

Type	Description
xs:int	The number of messages in the specified folder.

Response Template

<getMessageCountForFolderResponse> 
    <return>xs:int</return>
</getMessageCountForFolderResponse>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
UserNotFound	If the specified user is not a user in the system.
com.jivesoftware.community.PrivateMessageFolderNotFoundException	If the specified folder isn't there.

getMessages

Returns all the messages in the specified folder sorted by date in descending order. Users can create folders to organize their private messages.

GET http://domain:port/application_context/rpc/rest/privateMessageService/userMesages/{userID}/{folderID}

Arguments

Name	Type	Description
userID	xs:long	ID of the message folder from which to get messages.
folderID	xs:long	ID of the user this folder belongs to.

Arguments Template

<getMessages> 
    <userID>xs:long</userID>
    <folderID>xs:long</folderID>
</getMessages>

Response

Type	Description
List of PrivateMessage	All messages in the folder sorted by date in descending order.

Response Template

<getMessagesResponse> 
    <!-- List of ... -->
    <return>
        <!-- Contents of PrivateMessage -->
    <return>
</getMessagesResponse>

Errors

Error	When Returned
UserNotFound	If the specified user is not a user in the system.
com.jivesoftware.community.PrivateMessageFolderNotFoundException	If the specified folder isn't there.
Unauthorized	If the caller is neither an administrator nor the specified user.

getUnreadMessageCount

Returns the total number of unread messages a user has in their mailbox. This calculation does not count messages in the user's Trash folder.

GET http://domain:port/application_context/rpc/rest/privateMessageService/unreadMessageCount/{userID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user whose messages should be counted.

Arguments Template

<getUnreadMessageCount> 
    <userID>xs:long</userID>
</getUnreadMessageCount>

Response

Type	Description
xs:int	The total number of unread private messages the user has.

Response Template

<getUnreadMessageCountResponse> 
    <return>xs:int</return>
</getUnreadMessageCountResponse>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
UserNotFound	If the specified user is not a user in the system.

getUnreadMessageCountForFolder

Returns the total number of unread private messages a user has in the specified folder.

GET http://domain:port/application_context/rpc/rest/privateMessageService/unreadMessageCount/{userID}/{folderID}

Arguments

Name	Type	Description
userID	xs:long	ID of the user whose messages should be counted.
folderID	xs:int	ID of the folder in which to count messages.

Arguments Template

<getUnreadMessageCountForFolder> 
    <userID>xs:long</userID>
    <folderID>xs:int</folderID>
</getUnreadMessageCountForFolder>

Response

Type	Description
xs:int	The total number of unread private messages in the specified folder.

Response Template

<getUnreadMessageCountForFolderResponse> 
    <return>xs:int</return>
</getUnreadMessageCountForFolderResponse>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
UserNotFound	If the specified user is not a user in the system.
com.jivesoftware.community.PrivateMessageFolderNotFoundException	If the specified folder isn't there.

isPrivateMessagesEnabled

Returns true if private messaging is enabled; false otherwise.

GET http://domain:port/application_context/rpc/rest/privateMessageService/privateMessagesEnabled

Response

Type	Description
xs:boolean	true if private messaging is enabled; false otherwise.

Response Template

<isPrivateMessagesEnabledResponse> 
    <return>xs:boolean</return>
</isPrivateMessagesEnabledResponse>

moveMessage

Moves a private message to another message folder.

POST http://domain:port/application_context/rpc/rest/privateMessageService/moveMessage

Arguments

Name	Type	Description
userID	xs:long	ID of the user this message and folder belong to.
messageID	xs:long	ID of the message to move.
destinationFolderID	xs:int	ID of the folder to move the message to.

Arguments Template

<moveMessage> 
    <userID>xs:long</userID>
    <messageID>xs:long</messageID>
    <destinationFolderID>xs:int</destinationFolderID>
</moveMessage>

Errors

Error	When Returned
UserNotFound	If the specified user is not a user in the system.
com.jivesoftware.community.PrivateMessageFolderNotFoundException	If the specified folder isn't there.
com.jivesoftware.community.PrivateMessageNotFoundException	If the specified message wasn't found.
Unauthorized	If the caller is neither an administrator nor the specified user.

saveMessageAsDraft

Saves a message as a draft by storing it in the sender's Drafts folder.

POST http://domain:port/application_context/rpc/rest/privateMessageService/saveDraft

Arguments

Name	Type	Description
privateMessage	Contents of PrivateMessage	The private message to save as a draft.

Arguments Template

<saveMessageAsDraft> 
    <privateMessage>
        <!-- Contents of PrivateMessage -->
    <privateMessage>
</saveMessageAsDraft>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
com.jivesoftware.community.PrivateMessageRejectedException	If the private message could not be saved.
UserNotFound	If the specified user is not a user in the system.
com.jivesoftware.community.RejectedException	If the message could not be saved.

sendMessage

Sends a private message to another user. The message will be delivered to the recipient's Inbox. Optionally, a copy of the message will be put in the sender's Sent folder.

If the recipient's mailbox is full, a PrivateMessageRejectedException will be thrown. The exception will also be thrown if the recipient is not allowed to receive private messages or if the user has elected to save a copy of the message in their Sent folder, but doesn't have room to do so.

POST http://domain:port/application_context/rpc/rest/privateMessageService/sendMessage

Arguments

Name	Type	Description
privateMessage	Contents of PrivateMessage	The message to send.
recipientID	xs:long	ID of the user to send the message to.
copyToSentFolder	xs:boolean	true to copy the message to the Sent folder; otherwise false.

Arguments Template

<sendMessage> 
    <privateMessage>
        <!-- Contents of PrivateMessage -->
    <privateMessage>
    <recipientID>xs:long</recipientID>
    <copyToSentFolder>xs:boolean</copyToSentFolder>
</sendMessage>

Errors

Error	When Returned
Unauthorized	If the caller is neither an administrator nor the specified user.
com.jivesoftware.community.PrivateMessageRejectedException	If the private message could not be posted.
UserNotFound	If the specified user is not a user in the system.
com.jivesoftware.community.RejectedException	If the message could not be posted.