Skip to main content
POST
/
notifications?c=sms
SMS
curl --request POST \
  --url 'https://api.onesignal.com/notifications?c=sms' \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app_id": "YOUR_APP_ID",
  "contents": {
    "en": "<string>"
  },
  "target_channel": "sms",
  "include_aliases": {
    "external_id": [
      "<string>"
    ]
  },
  "include_subscription_ids": [
    "<string>"
  ],
  "include_phone_numbers": [
    "<string>"
  ],
  "included_segments": [
    "<string>"
  ],
  "excluded_segments": [
    "<string>"
  ],
  "filters": [
    {
      "field": "tag",
      "relation": "=",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "sms_from": "<string>",
  "sms_media_urls": [
    "<string>"
  ],
  "name": "<string>",
  "template_id": "<string>",
  "custom_data": {},
  "send_after": "<string>",
  "delayed_option": "<string>",
  "delivery_time_of_day": "<string>",
  "idempotency_key": "<string>"
}
'
{
  "id": "<string>",
  "external_id": "<string>",
  "errors": {
    "invalid_phone_numbers": [
      "<string>"
    ],
    "invalid_aliases": {
      "external_id": [
        "[\"user_id_1\", \"user_id_1\", \"user_id_2\"]"
      ],
      "onesignal_id": [
        "[\"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\"]"
      ]
    },
    "invalid_player_ids": [
      "<string>"
    ]
  }
}

​
Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for SMS and MMS. See Push notification or Email to send to those channels. Ensure your SMS setup is complete.
Review the Sending messages with the OneSignal API guide for details on how to structure your messages.
Add trackable links to your SMS contents using liquid syntax in the format {{'your_url' | track_link}}. Example:
JSON
{
  "contents": {
    "en": "Hi, here's my link: {{'https://example.com' | track_link}} "
  }
}
In this example, the liquid syntax block will be replaced with a trackable short link and display in the message as: 1sgnl.co/XXXX.
See SMS trackable links for more details.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

Body

application/json
​
app_id
string
default:YOUR_APP_ID
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

​
contents
object
required

The main message body with language-specific values. Too many characters may result in multiple messages and increased costs. See SMS. Required unless using template_id. Supports Message Personalization. You can add trackable links to your SMS via the API by including liquid syntax in your message contents. For example: {{'your_url' | track_link}} The liquid syntax block will be replaced with a trackable short link in the following format: 1sgnl.co/XXXX. Using trackable links allows you to see the click through rates of your SMS.

​
target_channel
enum<string>
default:sms
required

The targeted delivery channel. Required when using include_aliases and included_segments for SMS/RCS. Accepts push, email, or sms.

Available options:
push,
email,
sms
​
include_aliases
object

Target up to 20,000 users by their external_id, onesignal_id, or your own custom alias. Use with target_channel to control the delivery channel. Not compatible with any other targeting parameters like filters, include_subscription_ids, included_segments, or excluded_segments. See Sending messages with the OneSignal API.

​
include_subscription_ids
string[]

Target users' specific subscriptions by ID. Include up to 20,000 subscription_id per API call. Not compatible with any other targeting parameters like filters, include_aliases, included_segments, or excluded_segments. See Sending messages with the OneSignal API.

​
include_phone_numbers
string[]

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. Not compatible with any other targeting parameters like filters, include_aliases, included_segments, or excluded_segments. See Sending messages with the OneSignal API.

​
included_segments
string[]

Target predefined Segments. Users that are in multiple segments will only be sent the message once. Can be combined with excluded_segments. Requires target_channel to be set to 'sms' or isSms=true when sending SMS/RCS. Not compatible with any other targeting parameters like filters, include_aliases, or include_subscription_ids. See Sending messages with the OneSignal API.

​
excluded_segments
string[]

Exclude users in predefined Segments. Overrides membership in any segment specified in the included_segments. Not compatible with any other targeting parameters like filters, include_aliases, or include_subscription_ids. See Sending messages with the OneSignal API.

​
filters
(Filter · object | Operator · object)[]

Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and OR operators. See Sending messages with the OneSignal API.

Required array length: 1 - 200 elements

Required. The fitler object.

​
sms_from
string

The phone number or messaging service used to send the SMS or MMS. Defaults to the number selected in SMS Setup.

​
sms_media_urls
string[]

URLs for the media files to be sent as MMS. Additional rates apply. sms_from must support sending MMS messages. See SMS.

​
name
string

An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.

​
template_id
string

The template ID in UUID v4 format set for the message if applicable. See Templates.

​
custom_data
object

Include user or context-specific data (e.g., cart items, OTPs, links) in a message. Use with template_id. See Message Personalization. Max size: 2KB (Push/SMS), 10KB (Email).

​
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. Example: 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.

​
delivery_time_of_day
string

Use with delayed_option: 'timezone' to set a consistent local delivery time. Accepted formats: '9:00AM' (12-hour), '21:45' (24-hour), '09:45:30' (HH:mm:ss).

​
idempotency_key
string

A unique identifier used to prevent duplicate messages from repeat API calls. See Idempotent notification requests. Any RFC 9562 UUID supported. Valid for 30 days. Previously called external_id.

Response

200

​
id
string

The message ID in UUID v4 format. If id is an empty string, then the message was not sent.

​
external_id
string

The idempotency_key parameter if set. Used to prevent duplicate messages from repeat API calls. See Idempotent message requests.

​
errors
object

If the message id is set, then a message was sent. Any errors reported are with individual Users or Subscriptions that cannot be sent the message.