Inbox API

Create, retrieve, update and delete application inbox notifications for a whole organization or a single customer.

Inbox objects create and send application inbox notifications that can be targeted to specific customers as well as, en masse, to the organization as a whole. Messages for customers are stored in a customer-specific inbox. They represent scheduled and targeted content of any kind: messaging, promotions, games and display advertising.

The endpoints allow an organization to manage the typical procedural flow of notifications for its customers. In addition to messages being sent, they can be retrieved for display to customers; they can be updated and deleted; and, they can be marked "read".

API Contingencies and Combinations:

Before inbox messages can be sent, the customers receiving them must be created. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.
Inbox messages can be used to convey a variety of content designed to promote campaigns and loyalty program earning opportunities. For more information, see the following: Campaigns API, Promo Code APIs or Rewards Store API.

This API provides the following methods:

Create an organization inbox message
Update an organization inbox message
Retrieve organization inbox messages
Delete an organization inbox message
Create a customer inbox message
Update a customer inbox message
Retrieve customer inbox messages
Delete a customer inbox message
Bulk update customer inbox messages

Create an Organization Inbox Message

Generates an inbox message for all customers in the organization.

Endpoints for Create an Organization Inbox Message

This method offers the following endpoints:

REST Endpoints

POST /priv/v1/apps/:api_key/messages

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Create an Organization Inbox Message

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.

Request Object for Create an Organization Inbox Message

When this method runs, it passes in a request object that contains the message object, which is the payload to create the message, as shown below:

JSON Request

{
   "message":{
      "subject":"Foo",
      "external_id":"foo",
      "image":"http://images.foo.com/sessionM_M.png",
      "state":"live",
      "weight":60,
      "data":{
         "body":"Body"
      },
      "metadata":{
         "tag":"value"
      },
      "targeting":{
         "user.gender":{
            "#eq":"m"
         }
      }
   }
}

This object is detailed in the following table:

Request Attributes for Message

Attribute	Type Required/Optional	Description
subject	string required	Subject of the message.
external_id	string required	External message ID. Unique identifier to keep track of the message.
image	string optional	Valid URL of an icon to use for the message. Usually a square icon 50x50; or if handled by a developer, it can be any custom size.
state	string required	State of the message: Organization inbox message state, includes: live, preview Customer inbox message: new, read, deleted
weight	integer optional	The amount of time in seconds to keep the message at the top of the list; supports selective prioritization of messages for promotions. Default: 90
expires_on	datetime optional	Expiration time when the message will no longer persist in the inbox.
data	object required	Body of the message specified in the body attribute.
metadata	object optional	Any additional metadata (key-value pairs) to add to the message; supports use of rich display.
targeting	object optional	Customer targeting settings such as gender.

Response Object for Create an Organization Inbox Message

In addition to a status key-value pair, the response object returned by the method contains a message object, as shown below:

JSON Response

{
   "status":"ok",
   "message":{
      "id":2,
      "external_id":"foo",
      "subject":"Foo",
      "type":"inbox",
      "state":"live",
      "weight":60,
      "data":{
         "body":"Body"
      },
      "metadata":{
         "tag":"value"
      },
      "targeting":{
         "user.gender":{
            "#eq":"m"
         }
      },
      "created_at":"2016-10- 04 20:23:43",
      "updated_at":"2016-10- 04 20:23:43"
   }
}

This object is detailed in the following table:

Response Attributes for Message

Attribute	Type	Description
id	integer	Message identifier.
external_id	string optional	External message ID. Unique identifier to keep track of the message.
subject	string optional	Subject of the message.
type	string	Type of message, inbox.
state	string	State of the message: Organization inbox message state, includes: live, preview Customer inbox message: new, read, deleted
weight	integer	The amount of time in seconds to keep the message at the top of the list; supports selective prioritization of messages for promotions. Default: 90
data	object	Body of the message specified in the body attribute.
metadata	object	Any additional metadata (key-value pairs) to add to the message; supports use of rich display.
targeting	object	Customer targeting settings such as gender.
created_at	datetime	The time the message was created.
updated_at	datetime	The time the message was updated.

Statuses and Errors for Create an Organization Inbox Message

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Update an Organization Inbox Message

Updates an inbox message for all customers in an organization. One of the typical updates is setting the request object's status attribute to read.

Endpoints for Update an Organization Inbox Message

This method offers the following endpoints:

REST Endpoints

PUT /priv/v1/apps/:api_key/messages/:message_id
PUT /priv/v1/apps/:api_key/external/messages/:external_id

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Update an Organization Inbox Message

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
message_id	Internal identifier for the message.
external_id	External message ID. Unique identifier for a message in an external system integrating with the SessionM Platform.

Request Object for Update an Organization Inbox Message

When this method runs, it passes in a request object that contains a message object, as shown in two samples below:

JSON Request (Modify Message)

{
   "message":{
      "subject":"New Name"
   }
}

JSON Request (Mark Message "Read")

{
  "message":{
    "state":"read"
  }
}

Response Object for Update an Organization Inbox Message

In addition to a status key-value pair, this response object contains a message object, as shown in the samples below:

JSON Response (Modified Message)

{
   "status":"ok",
   "message":{
      "id":18,
      "external_id":"foo",
      "subject":"New Name",
      "type":"inbox",
      "state":"live",
      "weight":0,
      "data":{
         "body":"body"
      },
      "metadata":{
         "tag":"value"
      },
      "created_at":"2016-10- 03 16:53:19",
      "updated_at":"2016-10- 05 16:55:07"
   }
}

JSON Response (Message Marked "Read")

{
    "message": {
        "created_at": "2016-02-06T05:33:34Z",
        "data": {
            "body": "Test Body"
        },
        "expires_on": null,
        "id": "2a2529ea-cc93-11e5-87bd-e59d3e4d1689",
        "image": null,
        "metadata": null,
        "state": "read",
        "subject": "Hello",
        "type": "inbox"
    },
    "status": "ok"
}

Statuses and Errors for Update an Organization Inbox Message

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code	Reason
message_not_found	Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Organization Inbox Messages

Retrieves inbox messages for an organization; the endpoints can specify either all of the messages or one in particular. For example, adding the parameter message_id to the GET /priv/v1/apps/:api_key/messages endpoint retrieves the specified message.

Endpoints for Retrieve Organization Inbox Messages

This method offers the following endpoints:

REST Endpoints

GET /priv/v1/apps/:api_key/messages
GET /priv/v1/apps/:api_key/messages/:message_id
GET /priv/v1/apps/:api_key/external/messages/:external_id

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Retrieve Organization Inbox Messages

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
message_id	Returns just the specified message using the internal message ID.
external_id	Returns just the specified message using the external message ID.

Request Object for Retrieve Organization Inbox Messages

When this method runs, it passes in a request object, as shown below:

JSON Request

{
   "page": 1,
   "limit": 1
}

This object is detailed in the following table:

Request Attributes

Attribute	Type Required/Optional	Description
page	integer optional	Page to return for organization message. Default is 1. Example: page=2.
limit	integer optional	Maximum messages to receive for organization or customer inbox message.

Response Object for Retrieve Organization Inbox Messages

In addition to a status key-value pair, this object contains a messages array, as shown below:

JSON Response

{
   "status":"ok",
   "messages":[
      {
         "id":20,
         "external_id":"foo2",
         "subject":"Foo2",
         "type":"inbox",
         "state":"live",
         "weight":0,
         "created_at":"2016-10- 05 16:58:57",
         "updated_at":"2016-10- 05 16:58:57"
      }
   ]
}

This object is detailed in the following table:

Response Attributes for Messages

Attribute	Type	Description
id	integer	Message identifier.
external_id	string optional	External message ID. Unique identifier to keep track of the message.
subject	string optional	Subject of the message.
type	string	Type of message, inbox.
state	string	State of the message: Organization inbox message state, includes: live, preview Customer inbox message: new, read, deleted
weight	integer	The amount of time in seconds to keep the message at the top of the list; supports selective prioritization of messages for promotions. Default: 90
created_at	datetime	The time the message was created.
updated_at	datetime	The time the message was updated.

Statuses and Errors for Retrieve Organization Inbox Messages

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code	Reason
message_not_found	Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete an Organization Inbox Message

Deletes inbox messages for an organization; the endpoints can specify either all of the messages or one in particular.

Endpoints for Delete an Organization Inbox Message

This method offers the following endpoints:

REST Endpoints

DELETE /priv/v1/apps/:api_key/messages/:message_id
DELETE /priv/v1/apps/:api_key/external/messages/:external_id

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Delete an Organization Inbox Message

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
message_id	Returns just the specified message using the internal message ID.
external_id	Returns just the specified message using the external message ID.

Request Object for Delete an Organization Inbox Message

Not applicable.

Response Object for Delete an Organization Inbox Message

In addition to a status key-value pair, the response object returned by the method contains a message object, as shown below:

JSON Response

{
    "message": {
        "created_at": "2016-02-06T05:33:34Z",
        "data": {
            "body": "Test Body"
        },
        "expires_on": null,
        "id": "2a2529ea-cc93-11e5-87bd-e59d3e4d1689",
        "image": null,
        "metadata": null,
        "state": "deleted",
        "subject": "Hello",
        "type": "inbox"
    },
    "status": "ok"
}

Note that if the message was successfully deleted, the state attribute in the response object is set to deleted.

Statuses and Errors for Delete an Organization Inbox Message

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code	Reason
message_not_found	Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a Customer Inbox Message

Generates an inbox message for a single customer in the organization.

Endpoints for Create a Customer Inbox Message

This method offers the following endpoints:

REST Endpoints

POST /priv/v1/apps/:api_key/external/users/:external_id/messages
POST /priv/v1/apps/:api_key/users/:user_id/messages

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Create a Customer Inbox Message

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
message_id	Identifier for the specified message using the internal message ID.
external_id	Identifier for a customer in an external system creating a message.
user_id	Internal identifier for the customer whose messages are all being updated in bulk within the SessionM Platform.

Request Object for Create a Customer Inbox Message

When this method runs, it passes in a request object that contains a message object, as shown below:

JSON Request

{
   "message":{
      "subject":"message_direct",
      "image":"http://images.foo.com/sessionM_M.png",
      "data":{
         "body":"Body"
      },
      "metadata":{
         "tag":"value"
      }
   }
}

Response Object for Create a Customer Inbox Message

In addition to a status key-value pair, this object contains a message object, as shown below:

JSON Response

{
   "status":"ok",
   "message":{
      "id":"9bc36976-8b11- 11e6-8932- 43f360cca317",
      "subject":"message_direct",
      "image":"http://images.foo.com/sessionM_M.png",
      "data":{
         "body":"Body"
      },
      "metadata":{
         "tag":"value"
      },
      "state":"new",
      "type":"inbox",
      "created_at":"2016-10- 05T15:40:52Z"
   }
}

Statuses and Errors for Create a Customer Inbox Message

Update a Customer Inbox Message

Updates an inbox message for a specified customer in an organization.

Endpoints for Update a Customer Inbox Message

This method offers the following endpoints:

REST Endpoints

PUT /priv/v1/apps/:api_key/external/users/:external_id/messages/:message_id
PUT /priv/v1/apps/:api_key/users/:user_id/messages/:message_id

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Update a Customer Inbox Message

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
external_id	Identifier for a customer in an external system updating a message.
message_id	Message identifier.
user_id	Internal identifier for the customer within the SessionM Platform getting an updated message.

Request Object for Update a Customer Inbox Message

When this method runs, it passes in a request object. This object contains a message object, as shown below:

JSON Request

{
   "message":{
      "state":"read"
}

Response Object for Update a Customer Inbox Message

In addition to a status key-value pair, this object contains a message object, as shown below:

JSON Response

{
   "status":"ok",
   "message":{
      "id":"9bc36976-8b11- 11e6-8932- 43f360cca317",
      "subject":"message_direct",
      "image":"http://images.foo.com/sessionM_M.png",
      "data":{
         "body":"Body"
      },
      "metadata":{
         "tag":"value"
      },
      "state":"read",
      "type":"inbox",
      "created_at":"2016-10- 05T15:40:52Z"
   }
}

Statuses and Errors for Update a Customer Inbox Message

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code	Reason
message_not_found	Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Customer Inbox Messages

Retrieves inbox messages for a customer in an organization; the endpoints can specify either all of the messages or one in particular. For example, adding the parameter message_id to either the GET /priv/v1/apps/:api_key/external/users/:external_id/messages or the GET /priv/v1/apps/:api_key/users/:id/messages endpoint retrieves the specified message.

Endpoints for Retrieve Customer Inbox Messages

This method offers the following endpoints:

REST Endpoints

GET /priv/v1/apps/:api_key/external/users/:external_id/messages
GET /priv/v1/apps/:api_key/external/users/:external_id/messages/:message_id
GET /priv/v1/apps/:api_key/users/:user_id/messages
GET /priv/v1/apps/:api_key/users/:user_id/messages/:message_id

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Retrieve Customer Inbox Messages

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
external_id	Identifier for a customer in an external system receiving a message.
message_id	Message identifier.
user_id	Internal identifier for the customer within the SessionM Platform receiving a message.

Request Object for Retrieve Customer Inbox Messages

When this method runs, it passes in a request object shown below:

JSON Request

{
   "limit": 29
}

This object is detailed in the following table:

Request Attributes

Attribute	Type Required/Optional	Description
limit	integer optional	Maximum messages to receive for organization or customer inbox message.
from	string optional	Customer inbox message time, or UUID.

Response Object for Retrieve Customer Inbox Messages

In addition to a status key-value pair, this object contains a messages array, as shown below:

JSON Response

{
   "messages":[
      {
         "id":"38347820-8bdc- 11e6-82cb- b67a60cca317",
         "subject":"message4",
         "state":"new",
         "type":"inbox",
         "created_at":"2016-10- 06T15:47:43Z"
      },
      {
         "id":"0db644d0-8b13- 11e6-803a- e8e460cca317",
         "subject":"message2",
         "state":"new",
         "type":"inbox",
         "created_at":"2016-10- 05T15:47:43Z"
      }
   ],
   "pagination":{
      "from":"e302804c-8a49- 11e6-89b1- 56cd60cca317"
   },
   "status":"ok"
}

The second child object in the response is named pagination; this object contains the from attribute, which is a string that specifies the message time.

Statuses and Errors for Retrieve Customer Inbox Messages

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code	Reason
message_not_found	Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Delete a Customer Inbox Message

Deletes an inbox message for a customer in an organization.

Endpoints for Delete a Customer Inbox Message

This method offers the following endpoints:

REST Endpoints

DELETE /priv/v1/apps/:api_key/external/users/:external_id/messages/:message_id
DELETE /priv/v1/apps/:api_key/users/:user_id/messages/:message_id

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Delete a Customer Inbox Message

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
external_id	Identifier for a customer in an external system deleting a message.
message_id	Message identifier.
user_id	Internal identifier for the customer within the SessionM Platform deleting a message.

Request Object for Delete a Customer Inbox Message

Not applicable.

Response Object for Delete a Customer Inbox Message

In addition to a status key-value pair, this object contains a message object, as shown below:

JSON Response

{
    "message": {
        "created_at": "2016-02-06T05:33:34Z",
        "data": {
            "body": "Test Body"
        },
        "expires_on": null,
        "id": "2a2529ea-cc93-11e5-87bd-e59d3e4d1689",
        "image": null,
        "metadata": null,
        "state": "deleted",
        "subject": "Hello",
        "type": "inbox"
    },
    "status": "ok"
}

Note that if the message was successfully deleted, the state attribute in the response object is set to deleted.

Statuses and Errors for Delete a Customer Inbox Message

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code	Reason
message_not_found	Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Bulk Update Customer Inbox Messages

Updates in bulk all of the messages specified in the associated array of request objects.

Endpoints for Bulk Update Customer Inbox Messages

This method offers the following endpoints:

REST Endpoints

PUT /priv/:api_version/apps/:api_key/users/:user_id/messages
PUT /priv/:api_version/apps/:api_key/external/users/:external_id/messages

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters for Bulk Update Customer Inbox Messages

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter	Description
api_version	Internal parameter that supports API versioning.
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id	Internal identifier for the customer whose messages are all being updated in bulk within the SessionM Platform.
external_id	External identifier for the customer whose messages are all being updated in bulk in an external system integrating with the SessionM Platform.

Request Object for Bulk Update Customer Inbox Messages

When this method runs, it passes in a request object that contains a messages object, as shown below:

JSON Request

{
   "messages":[
      {
         "id":"38347820-8bdc- 11e6-82cb- b67a60cca317",
         "state":"read"
      }
   ]
}

This object's attributes are documented in the following table:

Request Attributes

Attribute	Type Required/Optional	Description
id	integer required	Message identifier.
state	string required	State of the message: Organization inbox message state, includes: live, preview Customer inbox message: new, read, deleted.

Attribute

Type
Required/Optional

Description

integer
required

Message identifier.

state

string
required

State of the message:

Organization inbox message state, includes:
live, preview

Customer inbox message:
new, read, deleted.

Response Object for Bulk Update Customer Inbox Messages

In addition to a status key-value pair, this object contains a messages array, as shown below:

JSON Response

{
   "messages":[
      {
         "id":"38347820-8bdc- 11e6-82cb- b67a60cca317",
         "subject":"message4",
         "state":"new",
         "type":"inbox",
         "created_at":"2016-10- 06T15:47:43Z"
      },
      {
         "id":"0db644d0-8b13- 11e6-803a- e8e460cca317",
         "subject":"message2",
         "state":"new",
         "type":"inbox",
         "created_at":"2016-10- 05T15:47:43Z"
      }
   ],
   "pagination":{
      "from":"e302804c-8a49- 11e6-89b1- 56cd60cca317"
   },
   "status":"ok"
}

The second child object in the response is named pagination; this object contains the from attribute, which is a string that specifies the message time.

Statuses and Errors for Bulk Update Customer Inbox Messages

Returned errors can be either method-specific or generic. The SessionM Platform returns the following error messages for this method:

Code	Reason
message_not_found	Customer message not found. Bad message ID.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Was this page helpful?