Sign in

v1

latestOpenAPI 3.1.02026-07-26497885.9 KB

SMS

Send a message using the SMS channel.

post/notifications?c=sms

Headers

Authorizationstring required

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

Request body

app_idstring required

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

target_channel'push' | 'email' | 'sms' required

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

include_subscription_idsstring[]

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_numbersstring[]

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_segmentsstring[]

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_segmentsstring[]

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.

sms_fromstring

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_urlsstring[]

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

namestring

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

template_idstring

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

custom_dataobject

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_afterstring

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_keystring

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

OR

Example response

{
  "errors": {
    "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\"]"
      ]
    }
  }
}