Sending messages with the OneSignal API

This guide helps you get started with sending messages using the OneSignal API. You’ll learn how to pick your target audience, set up content for push, email, or SMS, and schedule when it sends. Before you begin, make sure you:

Completed our Channel Setup Guides for the messaging channels you want to use (Push, Email, SMS, Live Activities).
Started accumulating Subscriptions to send messages to.

Select your target audience

You can target users using:

Aliases – Specific users via unique IDs, emails, or phone numbers.
Segments – Groups based on predefined behaviors or attributes.
Filters – Custom rules using tags, location, activity, and more.

Only one targeting method is allowed per message. For example, you cannot mix aliases and filters.

Additionally, you can target specific platforms (e.g. Android, iOS, Web) when sending push notifications.

Aliases, emails, phone numbers

Target specific users or groups of users (up to 20,000 entries). This method is best for Transactional Messages.

Aliases, emails, and phone numbers targeting parameters.

`include_aliases`

Target up to 20,000 users by their external_id, onesignal_id, or a custom alias. Use with target_channel to control the delivery channel. See Users and Aliases for more details.

{
  "include_aliases": {
    "external_id": [
      "user1",
      "user2",
      "user3"
    ]
  },
  "target_channel": "push"
}

`target_channel`

The targeted delivery channel.Required when using include_aliases. Accepts "push", "email", or "sms".

{
  "target_channel": "push"
}

`include_subscription_ids`

Target users’ specific subscriptions by ID. Include up to 20,000 subscription_id per API call.

{
  "include_subscription_ids": [
    "1dd608f2-c6a1-11e3-851d-000c2940e62c"
  ]
}

`email_to`

Send email to specific users by their email address. Can only be used when sending Email. Include up to 20,000 email addresses per API call. If the email address does not exist within the OneSignal App, then a new email Subscription will be created.

{
  "email_to": [
    "user1@example.com",
    "user2@example.com"
  ]
}

`include_phone_numbers`

Send SMS/MMS to specific users by their phone number in E.164 format. Can only be used when sending SMS/MMS. Include up to 20,000 phone numbers per API call. If the phone number does not exist within the OneSignal App, then a new SMS Subscription will be created.

{
  "include_phone_numbers": [
    "+19999999999"
  ]
}

Segments

Target groups of users based on predefined Segments.

Segments targeting parameters.

`included_segments`

Target predefined Segments. Users that are in multiple segments will only be sent the message once. Can be combined with excluded_segments.

{
  "included_segments": [
    "Active Users",
    "Inactive Users"
  ]
}

`excluded_segments`

Exclude users in predefined Segments. Overrides membership in any segment specified in the included_segments.

{
  "included_segments": [
    "Subscribed Users"
  ],
  "excluded_segments": [
    "Inactive Users"
  ]
}

`filters`

Use filters to target groups of users dynamically without creating predefined Segments.

Filters targeting parameter details.

Dynamically target users based on real-time properties like tags, activity, app usage, or location using flexible AND/OR logic. No need to create predefined Segments.You can include up to 200 total entries per request. This limit includes each filter condition (e.g., field) and logic operators like "OR".Performance guidance:

Fast: Tag filters using "=" or "exists", and filters on last_session, session_count, or country.
Slower: Negation filters ("!=", "not_exists")—especially with users who have many tags. Contact support to request indexing optimizations.
Slow by default: Numeric comparisons (">", "<") on tags or custom properties. Indexing may be available on request.
Mixed performance: Combining tag filters with other fields may increase computation time.

Available filters:

`operator`

Chain conditions with implicit AND logic (default). AND filters must be satisfied for the recipient to be included
Use "operator": "OR" to separate branches of logic. OR filters are mutually exclusive. Recipients only need to satisfy one condition.
Mix and nest operators to build complex logic trees.
Allowed values: "AND", "OR".

// Users must satisfy both filters to be included.
// Notice the AND operator is not required

"filters": [
{"field": "tag", "key": "level", "relation": "=", "value": "10"},
{"field": "amount_spent", "relation": ">","value": "0"}
]

// The same example using the AND operator. This is not required.
"filters": [
{"field": "tag", "key": "level", "relation": "=", "value": "10"},
{"operator": "AND"},
{"field": "amount_spent", "relation": ">","value": "0"}
]

`tag`

Target based on custom user Data Tags.

Do not use tags for targeting individual users like a “user id”. Instead use External ID or custom Aliases and the include_aliases targeting property.

relation = ">", "<", "=", "!=", "exists", "not_exists", "time_elapsed_gt", (time elapsed greater than) and "time_elapsed_lt" (time elapsed less than)
- time_elapsed_gt/lt fields correspond to Time Operators and require a paid plan.
key = Tag key to compare.

value = Tag value to compare. Not required for "exists" or "not_exists".

"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"}
]

`last_session`

Time since user last used the app (in hours_ago).

relation = ">" or "<"
hours_ago = number of hours before or after the user’s last session. Example: "1.1"
```
"filters": [
  {"field": "last_session", "relation": ">","hours_ago": "10"}
]
```

`first_session`

Time since user first used the app or was created (in hours_ago).

relation = ">" or "<"
hours_ago = number of hours before or after the user’s first session. Example: "1.1"
```
"filters": [
  {"field": "first_session", "relation": "<","hours_ago": "24"}
]
```

`session_count`

Total number of sessions by the user.

relation = ">", "<", "=" or "!="

value = number sessions. Example: "1"

"filters": [
  {"field": "session_count", "relation": ">","value": "5"}
]

`session_time`

Total time spent in the app (in seconds).

relation = ">" or "<"
value = Time in seconds the user has been in your app. Example: 1 day is "86400" seconds
```
"filters": [
  {"field": "session_time", "relation": ">","value": "86400"}
]
```

`language`

User’s language code (e.g., “en”). See Multi-Language Messaging for details and supported language codes.

relation = "=" or "!="

value = 2 character language code. Example: "en".

"filters": [
  {"field": "language", "relation": "=","value": "en"},
  {"operator": "OR"},
  {"field": "language", "relation": "=","value": "es"}
]

`app_version`

Subscription’s app version.

relation = ">", "<", "=" or "!="

value = app version. Example: "1.0.0"

"filters": [
  {"field": "app_version", "relation": "=","value": "1.0.1"}
]

`location`

Target by GPS coordinates and radius. See Location-Triggered Notifications for details.

radius = in meters
lat = latitude

long = longitude

"filters": [
  {"field": "location", "radius": "1000","lat": "37.77", "long":"-122.43"}
]

Craft your message

Each messaging channel has its own set of parameters that control how the message appears, behaves, and is delivered. At a minimum, you need the following to send a displayable message:

Push & SMS use contents
Email uses email_subject and email_body
If you created Templates, you can use template_id instead.

// Message request body
{
  "contents": {
    "en": "Hello, world",
    "es": "Hola Mundo",
    "fr": "Bonjour le monde",
    "zh-Hans": "你好世界"
  }
}

For advanced customization—like adding images, buttons, sounds, or tracking—see the channel-specific options below.

Push notification options

Below are the most common parameters for push notifications. For the full list of options, see the Push notification reference.

📲 Push Notification Options.

Email options

📧 Email Options

SMS/MMS options

💬 SMS/MMS Options

Schedule & per-user delivery options

By default, messages are sent immediately. You can schedule delivery in advance and optimize timing per-user based on their local timezone or recent activity.

Schedule delivery and per-user optimization parameters.

`send_after`

Schedule delivery for a future date/time (in UTC). The format must be valid per the ISO 8601 standard and compatible with JavaScript’s Date() parser.

{
  "send_after": "2025-09-24T14:00:00-07:00"
}

`delayed_option`

Controls how messages are delivered on a per-user basis:

'timezone': Sends at the same local time across time zones.
'last-active': Delivers based on each user’s most recent session.

Not compatible with Push Throttling. If enabled, set throttle_rate_per_minute to 0.

{
  "delayed_option": "last-active",
  "throttle_rate_per_minute": 0
}

`delivery_time_of_day`

Use with delayed_option: 'timezone' to set a consistent daily delivery time. Accepted formats:

"9:00AM" (12-hour)
"21:45" (24-hour)
"09:45:30" (HH:mm:ss)

Example – Send every day at 9 AM in each user’s local time:

{
  "delayed_option": "timezone",
  "delivery_time_of_day": "9:00AM",
  "throttle_rate_per_minute": 0
}

Submit the request

This final example sends a localized push notification to all subscribed users:

curl -X "POST" "https://api.onesignal.com/notifications" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Key YOUR_API_KEY' \
     -d $'{
      "target_channel": "push",
      "included_segments": [
        "Subscribed Users"
      ],
      "app_id": "YOUR_APP_ID",
      "contents": {
        "en": "Hello, world",
        "es": "Hola mundo",
        "fr": "Bonjour le monde",
        "zh-Hans": "你好世界"
      }
    }'

Once the request is sent, OneSignal will send it to the appropriate downstream provider (e.g., Push: FCM, APNS, HMS; Email: your Email Service Provider; SMS: Twilio), who then delivers it to the end user.

Handle the response

You will receive a 200 response code if the request is valid and accepted.

If an id is returned, the message was created successfully. Save this id for future tracking and reference of message stats via View Message API.
If no id is returned, then the message was not created, likely due to no valid Subscriptions in the target audience.

Response details by channel:

See our REST API Overview page for details on retries and rate limits.

Next steps

Refer to the channel-specific APIs to customize delivery further:

Using the REST APIs

API reference

SDKs

​Select your target audience

​Aliases, emails, phone numbers

​Segments

​filters

​Craft your message

​Push notification options

​Email options

​SMS/MMS options

​Schedule & per-user delivery options

​Submit the request

​Handle the response

​Next steps

Select your target audience

Aliases, emails, phone numbers

Segments

`filters`

Craft your message

Push notification options

Email options

SMS/MMS options

Schedule & per-user delivery options

Submit the request

Handle the response

Next steps