POST Messages

Send push notifications and in-app notifications to segments of your users.

URL Endpoint:


Name Type Required Definition
message object No JSON model of message


# Basic text message
curl -X POST -u :$API_KEY -d '{"message":{"to":"*", "title":"test","text":"test message"}}' -H 'Content-Type:application/json' -H 'Accept: application/json'

# Basic text message with message attributes 
curl -X POST -u :$API_KEY -d '{"message":{"to":"*", "title":"test","text":"test message", "custom":{"my_key":"my value"}}}' -H 'Content-Type:application/json' -H 'Accept: application/json'

# Link message
curl -X POST -u :$API_KEY -d '{"message":{"to":"*","title":"test","url":""}}' -H 'Content-Type:application/json' -H 'Accept: application/json'

# Message with push notification attached
curl -X POST -u :$API_KEY -d '{"message":{"to":"*","title":"test","text":"test message","notification":{"payload":{"alert":"foo","bar":"baz"}}}}' -H 'Content-Type:application/json' -H 'Accept: application/json'

# Message with push notification containing interruption level attached
curl -X POST -u :$API_KEY -d '{"message":{"to":"*","title":"test","text":"test message","notification":{"payload":{"alert":"foo","bar":"baz","interruption_level":"time-sensitive"}}}}' -H 'Content-Type:application/json' -H 'Accept: application/json'

# Basic text message with unpublish_at date
curl -X POST -u :$API_KEY -d '{"message":{"to":"*", "title":"test","text":"test message", "unpublish_at": "2019-09-01T00:00:00Z"}}' -H 'Content-Type:application/json' -H 'Accept: application/json'

Result Format

201 Created

   "created_at": "2019-01-08T01:47:01.527Z",
   "state": "scheduled",
   "id": "5c34011507492800095c97e5",
   "to": {
       "id": "5c1c35670798cd000973ce87",
       "type": "Audience"
    "notification": {
       "id": "5c34011507492800095c97e6",
       "created_at": "2019-01-08T01:47:01.535Z",
       "payload": {
          "alert": "foo",
          "bar": "baz"
   "title": "test",
   "text": "test message",
   "html": <p>"test message\n",</p>
   "custom": {} 

401 Unauthorized

// This error is given when your API client credentials are not correct. 

403 Forbidden

// This error is given when your API client does not have the ability to send Push Notifications.
  "error":"your api client does not have the correct roles"

422 Unprocessable Entity

error: # Dependant on why the request body was incorrect. 
Note: Rich Messages created through the API have a retention policy of 3 months. Messages in a user's stream will be deleted after this time.

Notification Payload Field

Please refer to Notifications Payload Field section.

To Field

There are three options for sending
  • "*" will send to everyone
  • A key audience with the value set as the audience ID, retrieved via Audiences, will send to the specified audience.
    {"to":{"audience":"AUDIENCE_KEY"} ,"title":"test","type":"text_message","text":"test message"}
  • An array of filters for creating an "on-the-fly" audience will send to users who match the filters. See the Filters section for available filters.


A filter is an object composed of three attributes: namecriteria and not_filter.
Filter attribute Details
name String. Device attribute on which the criteria will be applied.Example: { "name": "user_email", criteria: [""] } will match devices with a user email set to the supplied value. See the list of valid names/attributes below.
criteria Array with values to match.Provide at least one element of type string, integer, float or boolean.
not_filter Boolean. When true, it will match devices that don't match the criteria. Default is false.

Valid names/attributes for a filter

Name/Attribute Description
Language used on the device. Possible values can be found here.
Time zone used on the device. Possible values can be found here.
The date of device registration
The date of last device update
The current badge count
The device OS name
The device OS version
The app version on the device
The Sailthru SDK version
The tags on the device
The device ID assigned by Sailthru
The country based on user location (can be inaccurate, since sometimes the user doesn't enable GPS tracking and this value be defined using the user IP).
The device model. Examples: iPhone 5iPhone 6Samsung Galaxy S5
The user id on the device (Array of strings)

Filtering by custom attributes

The filter name should be composed as follows: custom. + type of attribute (string, integer, float, date or boolean). + attribute_name Examples:
  • custom.string.favorite_color
  • custom.boolean.completed_setup

Filter by custom events

The filter name should be composed as follows: events. + event name. Examples:
  • events.shared_post_on_twitter
  • events.video_plays

Specifying criteria ranges

A range is an object with at least of the following keys: gtltgte and lte.
Range key Description
Greater than value
Less than value
Greater than or equal to value
Less than or equal to value
Examples of valid ranges:
  • { "gt": 0 } - return values greater than 0
  • { "gt": 0, "lt": 10 } - return values greater than zero and less than 10 (non-inclusive)
  • { "gte": 0 } - return values greater than or equal to 0
Note: Make sure to use the same type of double quotation marks (e.g. both smart or both straight) when testing using the message box below.

unpublish_at Field

Optional field. When passed, the message will be unpublished from the device's message stream once the specified time has passed. The unpublish_at field's date must be specified using a UTC time with the following format: 'YYYY-MM-DDTHH:mm:SSZ'. Example: "2019-09-01T00:00:00Z".

Contact us