Subscriber segments are one of the core building blocks of a campaign, allowing you to target subscribers with particular attributes. They are essentially a list of subscribers and can be used as a destination for a notification. One important concept to undersatand about segments is dynamism

Dynamism

A segment has a dynamism field which dictates when a particular subscriber list is created for given segment.

A subscriber list is the "bucket"/list of subscribers which match your segment rules or otherwise

Each segment can have multiple buckets which link a notification to a particular subscriber list. So lets say you create a segment and want to create the subscriber list at time of creating this segment, this can be done by omitting the dynamism field altogether. A segment bucket is created and the list of subscribers which match your segment is created. This way every single notification which has this segment associcated with it will use this same subscriber list. However lets say you create a segment but as time rolls on you get new devices which install your app, the subscriber list created by this segment will be stale. So dynamism allows you to accomodate this scenario. There are two supported dynamism types:

• "one-time" - segment bucket created, and its subscriber list is created at the time of the first push. So when segment is created, a subscriber list will not be created until the first notification associated with the segment is pushed. Thereafter subsequent notifications associated with the segment will use this same segment bucket which is linked to this subscriber list
• "always" - a segment bucket is always created every time a notification which uses this segment is pushed. This way segment will always create the most up to date list of subscribers which match segment rules for every notification, these lists will have their own dedicated segment bucket linked to the segment

There are two ways of creating a segment

1. create empty segment and assign list of subscribers yourself manually. NOTE this method does not support dynamism
2. create a segment with rules which will be used to filter subscribers

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.

In order to create a Segment with rules we include the field in the request to POST /segment. An example request to the endpoint can be:

{
  "name": "My first rule segment",
  "description": "An optional description value",
  "dynamism": "always",
  "rules": [{
    "ruleId": "sessionCounts",
    "operator": "greaterThanOrEqual",
    "value": 10
  }, {
    "ruleId": "device",
    "operator": "is",
    "value": ["IOS"]
  }]
}

When dynamism is omitted this will include every user at the moment of the call is made, while setting dynamism will trigger the subscriber list generation process mentioned above
So now we have our first segment created, we can upload some content to attach and then send.

NOTE: Dynamism will not work when your list of rules includes either one of deviceId, subscriberId or customerId. Omit adding dynamism options when you add any of these rules

Including every user to a Segment

If you want to include every single user that is registered under your account simply make sure to omit the rules field

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

{
  "name": "Segment containing every single user",
  "description": "An optional description value",
  "dynamism": "one-time"
}