Private messages are 'e-mail style' messages that can be sent and shared between multiple users.
Table of Contents
Fields
Field
Name
Description
Type
Required
subject
Message Subject
The subject of the message
string
message
Message body
The body of the message
string
no
recipient_ids
Recipient User IDs
A comma delimited list of the message recipients’ user IDs
string
yes
last_updated
Last updated timestamp
The unix timestamp when the message was last updated
integer
message_status
Message status
Whether or not the message has been read
{read,unread}
id
Message thread ID
The ID of the existing message thread. Specify this value in POST when replying to an existing message.
integer
no
author_id
Message author ID
The user ID of the user who sent the message
integer
Operations
recipient list
View a list of valid message recipients for the given user. This list may vary significantly from the list of users in the school, or in the user’s network, as there are several permissions that affect whether or not users can message one another.
The operations listed below this line are available for the following message folders (replace [message folder] with the appropriate message folder name):
Message Folder
Path
Inbox
inbox
Sent
sent
Path
GET https://api.schoology.com/v1/messages/recipients
Content
none
Return
A collection of message objects, each one containing message fields.
JSON
{ "recipient": [ { "id": "48289", "name": "James Howlett", "school": "Hill Valley High School", "picture_url": "http:\/\/..." }, { "id": "45552", "name": "Mr. Strickland", "school": "Hill Valley High School", "picture_url": "http:\/\/..." }, { "id": "248101", "name": "Sam Jones", "school": "Hill Valley High School", "picture_url": "http:\/\/..." } ]}
XML
<?xml version="1.0" encoding="utf-8" ?><result> <recipient> <id>48289</id> <name>James Howlett</name> <school>Hill Valley High School</school> <picture_url>http:\/\/...</picture_url> </recipient> <recipient> <id>45552</id> <name>Mr. Strickland</name> <school>Hill Valley High School</school> <picture_url>http:\/\/...</picture_url> </recipient> <recipient> <id>248101</id> <name>Sam Jones</name> <school>Hill Valley High School</school> <picture_url>http:\/\/...</picture_url> </recipient></result>
list
View a list of messages in the user’s inbox or sent message folder.
?with_attachments=TRUE available
Path
GET https://api.schoology.com/v1/messages/[message
Content
none
Return
A collection of message objects, each one containing message fields.
View an individual message. However, if the given message is part of a message thread, all of the related thread messages will be returned in list fashion.
?with_attachments=TRUE available
Executing this endpoint will automatically mark the thread as read. If you wish to keep the thread set as unread, pass the following query
?keep_unread=TRUE
Path
GET https://api.schoology.com/v1/messages/[message
Content
none
Return
An object or collection of objects containing message fields.
{ "subject": "The subject of the message", "message": "The body of the message", "recipient_ids": "534342,678887,88923"}
XML
<body> <subject>The subject of the message</subject> <message>The body of the message</message> <recipient_ids>534342,678887,88923</recipient_ids></body>
Executing this endpoint will automatically mark the thread as read. If you wish to keep the thread set as unread, pass the following query
?keep_unread=TRUE
Path
POST https://api.schoology.com/v1/messages/[id]
Content
An object or collection of objects containing message fields
JSON
{ "subject": "The subject of the message", "message": "The body of the message", "recipient_ids": "534342,678887,88923"}
XML
<body> <subject>The subject of the message</subject> <message>The body of the message</message> <recipient_ids>534342,678887,88923</recipient_ids></body>
Return
An object or collection of objects containing message fields.
JSON
{ "id": 14065, "subject": "This is subject", "recipient_ids": "45552,48289", "last_updated": 1389716514, "mid": null, "author_id": 45552, "message_status": null, "message": "Did you see my message"}
XML
<?xml version="1.0" encoding="utf-8" ?><result> <id>14065</id> <subject>This is subject</subject> <recipient_ids>45552,48289</recipient_ids> <last_updated>1389716514</last_updated> <mid /> <author_id>45552</author_id> <message_status /> <message>Did you see my message</message></result>