Sending messages with the OneSignal API

Overview

This guide walks you through sending messages with the OneSignal API—from choosing a target audience to composing content, scheduling delivery, and validating responses. You’ll find channel-specific options, performance guidance, and common pitfalls to avoid.

Prerequisites

Complete Channel Setup for the channels you’ll use: Push, Email, SMS, Live Activities.
Start accumulating Subscriptions for your users.
Have your REST API Key and App ID ready. See Keys and IDs.

Choose your target audience

You can target users with one of the following methods per request:

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. isAndroid, isIos, isAnyWeb) when sending push notifications.

Aliases, emails, phone numbers

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

Aliases, emails, and phone numbers targeting parameters.

include_aliases

object

Target up to 20,000 users by their external_id, onesignal_id, or a custom alias. Combine with target_channel to select the delivery channel.

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

target_channel

string

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

{
  "target_channel": "push"
}

include_subscription_ids

array

Target users’ specific Subscriptions by ID. Max 20,000 subscription_id per request.

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

email_to

array

Send email to specific email addresses (max 20,000 per request). Can only be used when sending Email. 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

array

Send SMS/MMS/RCS to phone number in E.164 format (max 20,000 per request). Can only be used when sending SMS/MMS/RCS. 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 users in existing Segments. Users in multiple Segments only receive the message once.

Segments targeting parameters.

included_segments

array

Target predefined Segments. Users that are in multiple segments will only be sent the message once. Combine with excluded_segments to exclude users from specific Segments.

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

excluded_segments

array

Exclude users in these Segments even if they’re in included_segments.

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

`filters`

Build real-time audiences with AND/OR logic. No need to create segments first. You can include up to 200 total entries per request. This includes filter rows (e.g., each field) and logical operators like {"operator": "OR"}.

Filters targeting parameter details.

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.

operator

string

Implicit AND logic between filters. Use "operator": "OR" to start a new branch.
OR filters are mutually exclusive. Recipients only need to satisfy one condition.
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"}
]

field

object

`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"}
]

`country`

Country of the user.

relation = "=", "!=", "exists", "not_exists"

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

"filters": [
  {"field": "country", "relation": "=", "value": "US"}
]

`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 channel has its own set of fields. At a minimum, you need the following to send a displayable message:

Push & SMS use contents
Email uses email_subject and email_body
Or reuse template_id if you created Templates.

// 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.

📄 Content & text

contents – Main message body.
headings – Title of the notification.
subtitle – Secondary line of text.
template_id – Use a pre-defined template for common message types.

🖼 Appearance

ios_attachments – Images/video/media.
big_picture – Large image (Android).
chrome_web_image – Large image (Chrome).
small_icon
large_icon
buttons – Action buttons.

🔔 Delivery & priority

android_channel_id
priority – Delivery urgency.
ios_interruption_level
collapse_id – Replaces older messages.

🧩 Data & Extras

data – Custom key-value pairs sent to your app.
url – Opens when notification is tapped.

Email options

📧 Email Options

📄 Content

🖼 Appearance

template_id – Use a pre-defined template for common message types.

📬 Sender Info

SMS/MMS options

💬 SMS/MMS Options

Schedule & per-user delivery

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

string

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

string

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

string

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

Sending messages with the OneSignal API

Overview

Prerequisites

Choose your target audience

Aliases, emails, phone numbers

Segments

`filters`

`tag`

`country`

`last_session`

`first_session`

`session_count`

`session_time`

`language`

`app_version`

`location`

Craft your message

Push notification options

📄 Content & text

🖼 Appearance

🔔 Delivery & priority

🧩 Data & Extras

Email options

📄 Content

🖼 Appearance

📬 Sender Info

SMS/MMS options

📄 Content

🖼 Media (MMS only)

📬 Sender Info

Schedule & per-user delivery

Submit the request

Handle the response

Next steps

Using the REST APIs

API reference

SDKs

​Overview

​Prerequisites

​Choose your target audience

​Aliases, emails, phone numbers

​Segments

​filters

​tag

​country

​last_session

​first_session

​session_count

​session_time

​language

​app_version

​location

​Craft your message

​Push notification options

​📄 Content & text

​🖼 Appearance

​🔔 Delivery & priority

​🧩 Data & Extras

​Email options

​📄 Content

​🖼 Appearance

​📬 Sender Info

​SMS/MMS options

​📄 Content

​🖼 Media (MMS only)

​📬 Sender Info

​Schedule & per-user delivery

​Submit the request

​Handle the response

​Next steps

Overview

Prerequisites

Choose your target audience

Aliases, emails, phone numbers

Segments

`filters`

`tag`

`country`

`last_session`

`first_session`

`session_count`

`session_time`

`language`

`app_version`

`location`

Craft your message

Push notification options

📄 Content & text

🖼 Appearance

🔔 Delivery & priority

🧩 Data & Extras

Email options

📄 Content

🖼 Appearance

📬 Sender Info

SMS/MMS options

📄 Content

🖼 Media (MMS only)

📬 Sender Info

Schedule & per-user delivery

Submit the request

Handle the response

Next steps