Creating subscriber segments

Subscriber segments are one of the core building blocks of a campaign, allowing you to target subscribers with particular attributes. They are essentially a named list of subscribers and can be used to retrieve analytics information or as a destination for a notification.

There are two ways of creating a segment

  1. create empty segment and assign list of subscribers yourself manually
  2. create a segment with rules which will be used to filter subscribers

Note that you don't always need a segment if you want to send a notification. If you're doing transactional notifications (i.e. to a single subscriber) or a small group (<100) then you can skip straight to uploading your content.

Manually creating segments

Steps required are as follows:

Create empty segment

First lets create a named segment by calling following endpoint:

POST /v1/segment
{
    "name": "My first test segment",
    "description": "An optional description value"
}

Once this call is made we now have an empty segment to which we will assign our select subscribers. Response of this call will contain segment id value that we will need to use later.

Note: You can always see all your existing segments by calling:

GET /v1/segments

Accessing list of subscribers

We can always get a list of subscribers by calling endpoint:

GET /v1/subscribers

Each object in response.subscribers array will contain id attribute along with other details about your subscriber and their device. We will use these id attribute values later to assign select subscribers to the segment.

Adding subscribers to the segment

By this point we already have an empty segment created can list out our subscribers. We can now add batches of subscribers to this newly created segment by calling this endpoint:

POST /segment/subscribers
{
  "segmentId": "<target segment id>",
  "subscriberIds": [
    "<subscriber id>",
    "<subscriber id 2>",
    "<subscriber id 3>",
    // ...
  ]
}

Should you want to add more subscribers to this segment later simply call this endpoint again with a new array of subscriberIds in the POST body attribute.

Rule based Segments

Segments can be created using rules.

We support a wide variety of rules including session counts, device types and many more. Refer to our rules page for a comprehensive list

An example request to the POST /segment endpoint can be:

{
  "name": "My first rule segment",
  "description": "An optional description value",
  "dynamicRules": true, // defaults to false
  "rules": [{
    "ruleId": "sessionCounts",
    "operator": "greaterThanOrEqual",
    "value": 10
  }, {
    "ruleId": "device",
    "operator": "is",
    "value": ["IOS"]
  }]
}

So now we have our first segment created and populated, we can upload some content to attach and then send.

Note: You can assign a single subscriber to as many segments as you wish. There is no limit to the number of segments you can create, or the number of subscribers in each segment.

Including every user to a Segment

If you want to include every single user that is registered under your account simply make sure to provide { includeAll: true } parameter. On dynamicRules set to false this will include every user at the moment of the call is made, while setting dynamicRules to true, will include most up-to-date user list just before pushing the notification.

An example request to the POST /segment endpoint can be:

{
  "name": "Segment containing every single user",
  "description": "An optional description value",
  "dynamicRules": true, // defaults to false
  "includeAll": true    // defaults to false
}