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


Retention policy

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: name, criteria and not_filter.

Filter attributeDetails
nameDevice attribute on which the criteria will be applied.

Example: { "name": "locale", "criteria": ["en-us"] } will match devices with en_US locale. See the list of valid names/attributes below.
criteriaValues to match in filtering.

A criteria should always be an array with at least one element of type string, integer, float, or a range object (see below how to define a range object).
not_filterBoolean value (false by default). When true, it will match devices that don't match the criteria.

Valid names/attributes for a filter

localeLanguage used on the device. Possible values can be found here.
time_zoneTime zone used on the device. Possible values can be found here.
created_atThe date of device registration
registered_atThe date of last device update
badgeThe current badge count
os_nameThe device OS name
os_versionThe device OS version
app_versionThe app version on the device
sdk_versionThe Sailthru SDK version
tagsThe tags on the device
device_idThe device ID assigned by Sailthru
countryThe 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).
marketing_nameThe device model.

Examples: iPhone 5, iPhone 6, Samsung Galaxy S5
user_idThe 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


  • custom.string.favorite_color
  • custom.boolean.completed_setup

Filtering by custom events

The filter name should be composed as follows:

events. + event name.


  • events.shared_post_on_twitter
  • events.video_plays

Specifying criteria ranges

A range is an object with at least of the following keys: gt, lt, gte and lte.

Range keyDescription
gtGreater than value
ltLess than value
gteGreater than or equal to value
lteLess 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".