---
title: "SMS"
method: POST
path: "/notifications?c=sms"
---

# SMS

`POST /notifications?c=sms`

Send a message using the SMS channel.

## Headers

- `Authorization` string, required

## Request body

- object
  - `app_id` string, required — Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).
  - `contents` object, required — The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Too many characters may result in multiple messages and increased costs. See [SMS](/docs/sms-messaging). Required unless using `template_id`. Supports [Message Personalization](/docs/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.
    - `en` string, required — The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages).
  - `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](/reference/create-message#include-aliases).
    - `external_id` string[] — An array of external IDs which should be the same as the user ID in your app. This is the recommended method for targeting users. See [Users](/docs/users).
  - `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_ids` string[] — Target users' specific [subscriptions](/docs/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](/reference/create-message).
  - `include_phone_numbers` string[] — Send SMS/MMS to specific users by their phone number in [E.164 format](/docs/sms-setup#what-is-e164-format). Can only be used when sending [SMS/MMS](/reference/sms). 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](/reference/create-message).
  - `included_segments` string[] — Target predefined [Segments](/docs/segmentation). 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](/reference/create-message).
  - `excluded_segments` string[] — Exclude users in predefined [Segments](/docs/segmentation). 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](/reference/create-message).
  - `filters` union[] — 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](/reference/create-message#filters).
    - union
      - object — Required. The fitler object.
        - `field` 'tag' | 'last_session' | 'first_session' | 'session_count' | 'session_time' | 'language' | 'app_version' | 'location' | 'country', required — The name of the filter to use.
        - `relation` '=' | '!=' | '>' | '<' | 'exists' | 'not_exists' | 'in_array' | 'not_in_array' | 'time_elapsed_gt' | 'time_elapsed_lt', required — Used with most filters. See details on the specific filter.
        - `key` string — Used with the `tag` filter. This is the tag `key`.
        - `value` string — The value of the `field` or tag `key` in which you want to filter with.
      - object
        - `operator` 'AND' | 'OR' — Chain filter conditions with implicit `AND` and `OR` logic. Never end your `filters` object with an `operator`. See [filters](/reference/create-message#filters) for more.
  - `sms_from` string — The [Messaging Service ID](/docs/en/sms-setup#step-2-create-senders) 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](/docs/en/sms-setup). If using [per-sender opt-out](/docs/en/sms-consent-keyword-management), 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](/docs/sms-messaging).
  - `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](/docs/en/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](/docs/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](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript’s Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring). 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](/reference/idempotent-notification-requests). Any RFC 9562 UUID supported. Valid for 30 days. Previously called `external_id`.

## Response `200`

200

- union — 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.
  - object — Notification was accepted and dispatched to one or more subscribers. `errors` (when present) reports per-channel invalid identifiers; `warnings` (when present) reports non-fatal issues such as unsubscribed external IDs. `external_id` echoes the request's `idempotency_key` (or null when not provided).
    - `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, nullable — 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](/reference/idempotent-notification-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.
      - `invalid_phone_numbers` string[]
      - `invalid_aliases` object — The alias label that was used in the `include_aliases` parameter.
        - `external_id` string[]
        - `onesignal_id` string[]
      - `invalid_player_ids` string[]
    - `warnings` union — Non-fatal warnings emitted alongside a successful send.
      - object — Object form.
        - `invalid_external_user_ids` string — external_ids whose subscriptions are unsubscribed.
      - string[] — Array form. Contains non-fatal warning messages.
  - object — Validation passed but the targeting matched zero subscribers (and the notification is not lightspeed-eligible). HTTP status is 200 even though no message was dispatched. `id` is always the empty string in this branch — use it as the discriminator from the Message Sent variant.
    - `id` '', required — If the message `id` is an empty string, then no message was sent. The request appears to be formatted correctly, but there are issues with the aliases, segments, or filters targeted.
    - `errors` string[], required — Reasons the message was not dispatched. The most common value is `"All included players are not subscribed"`, which means every subscription matched by the segments/aliases/filters was unsubscribed before send time. Per-channel sentinels (e.g., invalid identifiers) may also appear.
    - `warnings` union — Non-fatal warnings emitted alongside a successful send.
      - object — Object form.
        - `invalid_external_user_ids` string — external_ids whose subscriptions are unsubscribed.
      - string[] — Array form. Contains non-fatal warning messages.

## Other responses

- `400` — 400
- `403` — Forbidden. The Authorization key cannot send SMS for this app, or the request targets a feature the app's plan does not enable.
- `429` — Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.
- `503` — Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.

---

[API](https://skmtc.net/onesignal/apis/api-onesignal-com.md) · [All operations](https://skmtc.net/onesignal/apis/api-onesignal-com/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onesignal/api-onesignal-com/versions/0fc223f7e338/schema)