Private Messaging

Fields

FieldNameDescriptionTypeRequired
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 folder]

Content

none

Return

A collection of message objects, each one containing message fields.

JSON 
{
    "message": [
        {
            "id": 13886,
            "subject": "[Time Travel: Section 8i] Getting started",
            "recipient_ids": "45552",
            "last_updated": 1381432687,
            "mid": null,
            "author_id": 45552,
            "message_status": "read",
            "message": null,
            "links": {
                "self": "http:\/\/..."
            }
        }
    ],
    "links": {
        "self": "http:\/\/...?start=0&limit=20"
    },
    "unread_count": "0"
}
XML 
<?xml version="1.0" encoding="utf-8" ?>
<result>
    <message>
        <id>13886</id>
        <subject>[Time Travel: Section 8i] Getting started</subject>
        <recipient_ids>45552</recipient_ids>
        <last_updated>1381432687</last_updated>
        <mid />
        <author_id>45552</author_id>
        <message_status>read</message_status>
        <message />
        <links>
            <self>http:\/\/...</self>
        </links>
    </message>
    <links>
        <self>http:\/\/...?start=0&amp;limit=20</self>
    </links>
    <unread_count>0</unread_count>
</result>

view

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 folder]/{id}

Content

none

Return

An object or collection of objects containing message fields.

JSON 
{
    "message": [
        {
            "id": 13886,
            "subject": "[Time Travel: Section 8i] Getting started",
            "recipient_ids": "45552",
            "last_updated": 1381432687,
            "mid": null,
            "author_id": 45552,
            "message_status": "read",
            "message": "Hi,\r\n\r\n\r\nBye"
        }
    ]
}
XML 
<?xml version="1.0" encoding="utf-8" ?>
<result>
    <message>
        <id>13886</id>
        <subject>[Time Travel: Section 8i] Getting started</subject>
        <recipient_ids>45552</recipient_ids>
        <last_updated>1381432687</last_updated>
        <mid />
        <author_id>45552</author_id>
        <message_status>read</message_status>
        <message>Hi,


Bye</message>
    </message>
</result>

update

Modify the message status of an existing message in the inbox message folder. The message status value should be either 'read' or 'unread'.

Path

PUT https://api.schoology.com/v1/messages/inbox/{id}

Content

An example PUT call request body looks like this:

JSON 
{
    "message_status": "read",
}
XML 
<message>
  <message_status>read</message_status>
</message>
Return

none

create

Create a message

Path

POST https://api.schoology.com/v1/messages

Content

An object 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

none

JSON 
{
    "id": 14065,
    "subject": "This is subject",
    "recipient_ids": "48289",
    "last_updated": 1389716445,
    "mid": null,
    "author_id": 45552,
    "message_status": null,
    "message": "This is message"
}
XML 
<?xml version="1.0" encoding="utf-8" ?>
<result>
    <id>14065</id>
    <subject>This is subject</subject>
    <recipient_ids>48289</recipient_ids>
    <last_updated>1389716445</last_updated>
    <mid />
    <author_id>45552</author_id>
    <message_status />
    <message>This is message</message>
</result>

delete

Delete a message (cannot be undone). Note: deleting a message from the sent folder does NOT un-send the message.

Path

DELETE https://api.schoology.com/v1/messages/[message folder]/{id}

Content

none

Return

none

reply

Reply to an individual thread.

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>