Skip to main content
Segments update automatically as users interact with your app or site—no extra tracking required.
Push notifications, emails, and SMS messages are only sent to opted-in (subscribed) Subscriptions. The segment editor shows both subscribed and unsubscribed counts for transparency, but only subscribed Subscriptions receive messages when you target a segment. In-App Messages are displayed to all mobile Subscriptions, regardless of status.When used in Journeys, all Subscriptions in a segment, regardless of status, are evaluated to their respective users and those users are entered into the Journey.

​
Segment types

The OneSignal platform supports two main categories of segments:

​
Subscription-based segments

Subscription-based segments are built using filters on subscription attributes, such as device type, language, or app version.

​
User-based segments

User-based segments are built using filters on user-level attributes rather than individual subscriptions. Currently, these segments support filters on message events and custom events. Examples include:
  • When a user last opened an email, SMS, or push notification sent via OneSignal.
  • Specific custom events tracked in your app or website.
A user-based segment includes all users who meet the criteria and automatically makes all of their subscriptions eligible to be targeted, enabling richer audience definitions that can reach any of the user’s devices.

​
Creating segments

Segments can be created in the dashboard, via the API, or by uploading a CSV. Target your audience by including and excluding segments when sending messages or building Journeys.

Dashboard

Create and manage segments from Audience > Segments.

API

Create segments programmatically using the Create Segment API.

CSV Import

Bulk-import Subscriptions into a segment by uploading a CSV.
Create a segment in the dashboard
1

Go to Audience > Segments

Navigate to the Segments page in the dashboard.
Segments page showing list of segments
2

Click New Segment

Opens the segment creation interface.
Segment creation interface showing filter options and segment name field
3

Add filters, name the segment, and click Create Segment

  • Add filters to define your audience criteria. If no filters are selected, it will default to every user of your app.
  • Name the segment and click Create Segment.
Segment creation interface showing filter options and segment name field

​
Segment logic: AND vs OR

Use AND to combine filters that all must match. Use OR to match any of multiple conditions.
Create a segment of users who:
  • Have been active within the last 30 days
  • Have at least 3 total sessions
Segment with AND filters for users active within 30 days with at least 3 sessions

​
Filters

Filters define which Subscriptions belong to a segment. You can combine multiple filters using AND or OR logic. If no filters are selected, the segment will default to every user of your app.
FilterDescription
First sessionDate/time of user creation.
Last sessionLast time Subscription opened the app or site.
Session countNumber of times Subscription opened the app or visited the site.
Usage durationTotal seconds the Subscription had your app/site open.
LanguageUser’s preferred language (based on device/browser). See multi-language support.
App versionPulled from Android versionCode or iOS CFBundleShortVersionString. Combine with Device type to filter by different app versions per platform. See Target outdated app versions.
Device typeiOS, Android, Web Push (browser), Email, etc.
User tagCustom tags you set via the SDK or API. See Add Tags.
LocationFilter by radius from coordinates (lat/long). Requires at least 1 meter and up to 2 decimal places of precision. See location permission.
CountryBased on last IP geolocation (ISO 3166-2 code).
Test usersUsers marked as Test Users.
Message EventFilter by message event (e.g., “clicked”, “delivered”, “failed”). See Message event filters.
Custom EventFilter by custom event (e.g., “purchase”, “user login”). See Custom event filters.

​
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 filter options showing channel, action, and time window selectors
First select the messaging channel you want to filter on, then specify the action to track and whether the user has or has not performed that action. You can specify a minimum, maximum, or exact number of times the user must have performed the action, as well as a time window ranging from the last 24 hours to the last 90 days. Use the between option to define a custom start and end range (in days ago). Trackable interactions by channel:
ChannelTrackable Interactions
PushSent, Received, Clicked, Failed
SMSSent, Delivered, Failed
EmailSent, Delivered, Opened, Clicked, Bounced, Failed, Suppressed, Reported as spam
In-AppReceived, Clicked
Segments created with message event filters are user-based.They cannot be combined with subscription-based segments for inclusion or exclusion when sending messages outside of Journeys.Within Journeys, which is user-based, you can combine event-based and subscription-based segments for more flexible targeting.
Message event retention The amount of time message event data is retained depends on your plan. The dashboard time window selector shows up to 90 days, but data beyond your plan’s retention period will not return results.

Message event retention by plan

Retention periods vary by plan — see the Billing FAQ for details.

​
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 event filters are currently in Early Access.To request access, contact support@onesignal.com with your company name, OneSignal Organization ID, and App ID(s).
Custom event filter options showing event type and property selectors
Start by selecting:
  • The event name you want to filter on.
  • Whether the user has or has not performed that action.
  • The minimum, maximum, or exact number of times the action must be performed.
  • A time window during which the action must (or must not) occur — choose a preset range or define a custom window using the between option (start and end in days ago).
After specifying the event, you can optionally filter on specific or multiple properties:
  • all — applies an AND condition across properties.
  • at least one — applies an OR condition.
Then set the properties you want to filter on using dot notation. Example Given the following custom event: 
{
  "events": [
    {
      "name": "cart_updated",
      "properties": {
        "product_name": "24 Pack of Acorns",
        "product_price": "12.99",
        "product_quantity": "2"
      },
      "external_id": "ID_OF_THE_USER"
    }
  ]
}
You can filter by:
  • product_name → to target users with product name 24 Pack of Acorns.
  • product_price → to target users with product price 12.99.
  • product_quantity → to target users with product quantity 2.
Custom event filter example showing product name, image, price, quantity, and cart URL
Segments created with custom event filters are in Early Access and are user-based. A custom event segment can only contain custom event filters, and cannot be combined with other segments for inclusion or exclusion when sending messages.

​
Audience counts

The segment editor shows how many subscribed and unsubscribed Subscriptions are in your segment, with a breakdown by channel (push, email, and SMS).
  • Subscribed Subscriptions are opted in and will receive messages when you target this segment.
  • Unsubscribed Subscriptions match your segment filters but are opted out and will not receive messages.
The channel breakdown lets you see reachable vs. unreachable Subscriptions per channel — useful for understanding which channels will be most effective before you build a message or Journey.
Audience counts showing subscribed and unsubscribed counts by channel

​
Exact counts and estimates

OneSignal always returns a count within approximately 15 seconds. Whenever possible within that time limit, you will see an exact count. For large or complex segments where exact counts can take a long time to compute, an estimate is shown instead. Estimates are labeled to make clear they are not exact:
Segment sizeFormatExample
Above 10,000Count with margin of error140,000 +/- 5,000
Below 10,000Less-than value<4,800
Both formats are rounded to signal the number is approximate. Estimates will never display as 0: if your segment has very few members, the estimate reflects a small non-zero estimate to avoid implying the segment is empty when records may exist.
Audience counts are available for subscription-based segments. User-based segment counts are not yet supported.

​
Managing segments

When viewing your Segments in the dashboard, you can:
  • View Subscriptions: See which Subscriptions are in the segment.
  • Copy segment ID: Copy the segment ID to use in the API.
  • Edit: Change filters or name.
  • Pause / Resume: If you’re near your segment limit, you can pause segments without deleting them. 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.
  • View Audit Logs: See the audit logs for who may have changed a segment and when.
  • Delete: Delete the segment.

​
Deleting segments

Deleting a segment removes it from your list of segments. It does not delete the users inside it. To delete the users inside a segment, see Delete Users.
  1. Go to Audience > Segments
  2. Click the three-dot menu next to a segment
  3. Select Delete
Three-dot options menu on a segment showing Edit, Pause, Duplicate, and Delete actions

​
FAQ

​
How do I add myself to a segment?

Set yourself as a Test User or add a custom Tag, then create a segment that targets it.
  1. Find your Subscriptions using your External ID.
  2. Either:
  3. Create a segment using the Test Users filter or the tag.

​
Do segment counts include opted-out users?

Yes. The segment editor shows counts for both subscribed and unsubscribed Subscriptions. Subscribed Subscriptions are opted in and will receive messages. Unsubscribed Subscriptions match your filters but are opted out and will not receive messages. Only subscribed Subscriptions are targeted when you send a message. When used in Journeys and in-app messages, segments include both subscribed and unsubscribed Subscriptions.

​
Are segment counts always accurate?

OneSignal always returns a count within approximately 15 seconds. For smaller or simpler segments, this is an exact count. For larger or more complex segments, an estimate is shown instead. Estimates are clearly labeled with their precision. See Audience counts for details on how estimates are formatted and what they mean.