Segments

A segment is a dynamic audience that groups Subscriptions based on filters like activity, country, Tags, and more. Segments help you send personalized, timely, and relevant messages. Once created, segments update automatically as users interact with your app or site—no extra tracking required.

Segment counts only reflect opted-in Push, SMS, and Email subscriptions.When used in Journeys or In-App Messages, segments include users and opted-out subscriptions.To analyze unsubscribed subscriptions, use the Export CSV of Players API.

Creating segments

You can create segments in three ways:

From the Dashboard
Via the Create Segment API
By uploading a CSV. See our Import guide for details.

Create a segment in the dashboard

Go to Audience > Segments
Click New Segment
Add filters, name the segment, and click Create Segment

New Segment creation interface

Exclude segments

Exclude a segment to prevent its members from receiving a message or entering a Journey. Common use cases:

Avoid sending duplicate or conflicting messages
Respect user messaging preferences (e.g., “opted out of promo”)
Prioritize transactional messages over campaigns

You can exclude segments when:

Sending a message
Building a Journey
Using the Exclude Segment option in segment settings

Filters

Filters define which subscriptions belong to a segment. You can combine multiple filters using AND or OR logic.

Filter	Description
First session	Date/time of user creation.
Last session	Last time Subscription opened the app or site.
Session count	Number of times Subscription opened the app or visited the site.
Usage duration	Total seconds the Subscription had your app/site open.
Language	User’s preferred language (based on device/browser). See multi-language support.
App version	Pulled from Android `versionCode` or iOS `CFBundleShortVersionString`. - Combine with Device type to filter by different app versions for each platform. - See Target outdated app versions tutorial for more details.
Device type	iOS, Android, Web Push (browser), Email, etc.
User tag	Custom tags you set via the SDK or API. See Add User Tags.
Location	Filter by radius from coordinates (lat/long). Requires at least 1 meter and up to 2 decimal places of precision. See location permission.
Country	Based on last IP geolocation (ISO 3166-2 code).
Test users	Users marked as Test Users.
Rooted	Android only — whether device is rooted.
Message Event	Filter by message event (e.g., “clicked”, “delivered”, “failed”). See Message event filters.

Segment filters configuration screen

Message event filters

Message event filters allow you to filter users based on their interaction with one of your messaging channels within a certain window.

Message event filters

First select the messaging channel you want to filter on, then specify the action that you want to track for that channel and whether the user has or has not performed that action. You can specify a minimum, maximum, or exact number of time the user must have performed the action in order to qualify, as well as a time window ranging from the last 24 hour to the last 90 days in which they must have performed or not performed the action. See below for a list of available trackable interactions for each channel:

Channel	Trackable Interactions
Push	Sent, Received, Clicked, Failed
SMS	Sent, Delivered, Failed
Email	Sent, Delivered, Opened, Clicked, Bounced, Failed, Suppressed, Reported as spam
In-App	Received, Clicked

Segments created with message event filters are user-based. Because of this, they cannot be combined with subscription-based segments (those that don’t use message event filters) for inclusion or exclusion when sending messages outside of Journeys.However, within Journeys which is user-based, you can combine event-based segments with subscription-based segments. This allows for more flexible targeting in automated messaging flows.

Custom event filters

Custom event filters let you target users based on meaningful actions they have taken in your app, website, or external systems.

Custom events filters are currently in Early Access.To request access, contact support@onesignal.com with:

your company name
your OneSignal Organization ID
your OneSignal App ID(s) that you want to use the feature on

Custom event filters

How They Work

Start by selecting the event type you want to filter on. Then specify:

The action that you want to track.
Whether the user has or has not performed that action.

You can also set conditions such as:

Minimum, maximum, or exact number of times the action must be performed.
A time window during which the action must (or must not) occur.

Event Properties

After selecting an event type, you can optionally filter on event properties. You can include filters on multiple custom event properties,

Choose all, applies an AND condition across properties.
Choose at least one, applies an OR condition.

Custom events are represented as JSON Objects. See the full structure here Nested event properties can be referenced using dot notation. Example Given the following custom event structure,

{
  "signup": {
    "method": "google",
    "experiment_group": "control_group",
    "referral_code": "SAVE15",
    "location": {
      "timezone": "Europe/Paris",
      "country": "CA"
    }
  },
  "user_id": "user_804f7e88"
}

You can filter by:

signup.referral_code → to target users with referral code SAVE15.
signup.location.country → to target users in Canada.

Segments created with custom event filters are in Early Access. Because of this,

a custom event segment can only contain one custom event filter.
a custom event segment can only contain custom event filter, and cannot be combined with other segments for inclusion or exclusion when sending messages.

Segments created with custom event filters are user-based.

Segment logic: AND vs OR

Use AND to combine filters that all must match. Use OR to match any of multiple conditions.

AND filter example

Create a segment of users who:

Have not returned in more than 7 days
Will be removed after 11 days

Inactive segment filter setup

OR filter example

Create a segment of users who:

Have not returned in more than 7 days
Have new Subscriptions created in the last 3 days

OR clause segment configuration

Managing segments

View users

Click Options > View Users to see which subscriptions are in the segment.

Edit

Click the segment name or Options > Edit to change filters.

Pause / Resume

If you’re near your segment limit (based on your plan), you can pause segments. Targeting a paused segment will fail.

Set as default

Set a default segment to be auto-selected when sending a new message. This helps reduce targeting mistakes and save time.

Duplicate

Copy a segment’s filters to create a new one.

Deleting segments

Deleting a segment cannot be undone and does not delete the users inside it.

In the dashboard

Go to Audience > Segments
Click the three-dot menu next to a segment
Select Delete

Segment options menu

Using the API

Use the Delete Segment API. Only removes the segment definition. To delete users in the segment, use the Delete Users API.

{
  "name": "Segment 2",
  "filters": [
    { "field": "session_count", "relation": ">", "value": "1" },
    { "operator": "AND" },
    { "field": "tag", "relation": "!=", "key": "tag_key", "value": "1" },
    { "operator": "OR" },
    { "field": "last_session", "relation": "<", "hours_ago": "30" }
  ]
}

FAQ

How do I add myself to a segment?

Find your Subscriptions using your External ID.
Either:

Set yourself as a Test user
Add a custom Tag

Create a segment using the Test Users filter or the tag.

Do segment counts include opted-out users?

Visible counts only include opted-in subscriptions.
Segments used in Journeys and in-app messages include both subscribed and unsubscribed subscriptions.
To see unsubscribed subscriptions, use the Export CSV of Players API.

Are segment counts always accurate?

Segments larger than 80,000 total users may have an estimated size, instead of a precise count, in order to calculate them quickly. To get the most accurate numbers, see the message report stats after sending the message.

What types of in-app purchases are tracked?

Tracked: Consumable purchases made while the OneSignal SDK is active.
Not tracked: Subscription purchases.
To import historical purchase data, use the Update User API with the purchases parameter.

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

Creating segments

Create a segment in the dashboard

Exclude segments

Filters

Message event filters

Custom event filters

How They Work

Event Properties

Segment logic: AND vs OR

AND filter example

OR filter example

Managing segments

View users

Edit

Pause / Resume

Set as default

Duplicate

Deleting segments

In the dashboard

Using the API

FAQ

How do I add myself to a segment?

Do segment counts include opted-out users?

Are segment counts always accurate?

What types of in-app purchases are tracked?

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

​Creating segments

​Create a segment in the dashboard

​Exclude segments

​Filters

​Message event filters

​Custom event filters

​How They Work

​Event Properties

​Segment logic: AND vs OR

​AND filter example

​OR filter example

​Managing segments

​View users

​Edit

​Pause / Resume

​Set as default

​Duplicate

​Deleting segments

​In the dashboard

​Using the API

​FAQ

​How do I add myself to a segment?

​Do segment counts include opted-out users?

​Are segment counts always accurate?

​What types of in-app purchases are tracked?

Creating segments

Create a segment in the dashboard

Exclude segments

Filters

Message event filters

Custom event filters

How They Work

Event Properties

Segment logic: AND vs OR

AND filter example

OR filter example

Managing segments

View users

Edit

Pause / Resume

Set as default

Duplicate

Deleting segments

In the dashboard

Using the API

FAQ

How do I add myself to a segment?

Do segment counts include opted-out users?

Are segment counts always accurate?

What types of in-app purchases are tracked?