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>",
  "idempotency_key": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "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>"
    ]
  },
  "warnings": {
    "invalid_external_user_ids": "<string>"
  }
}

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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 Messaging Service ID or phone number used to send the SMS or MMS. Its recommended to use Messaging Service SIDs (e.g., MGxxxxxxxxxxxxxxx) but also accepts E.164 phone numbers (e.g., +12065551234). Defaults to the sender selected in SMS Setup. If using per-sender opt-out, you must use a Messaging Service ID.

​
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

​
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

Two variants are possible with HTTP 200, distinguished by the id field: a UUID indicates the message was accepted and dispatched (Message Sent); an empty string indicates the request was valid but no subscribers matched (Message Not Sent). Inspect errors when id is empty.

​
id
string<uuid>
required

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

​
external_id
string | null

The idempotency_key parameter from the request, echoed back. Null when no idempotency_key was provided. Used to detect duplicate-send attempts — see Idempotent message requests.

​
errors
object

Per-channel listings of invalid identifiers in the request. Only emitted when at least one identifier in the request failed validation. Each listed key is optional; the keys present depend on the channel and request.

​
warnings

Non-fatal warnings emitted alongside a successful send.