Private Messaging

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 FolderPath
Inboxinbox
Sentsent
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.

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

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

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>