Email

curl --request POST \
  --url 'https://api.onesignal.com/notifications?c=email' \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {
    "external_id": [
      "<string>"
    ]
  },
  "target_channel": "email",
  "include_subscription_ids": [
    "<string>"
  ],
  "email_to": [
    "<string>"
  ],
  "included_segments": [
    "<string>"
  ],
  "excluded_segments": [
    "<string>"
  ],
  "filters": [
    {
      "field": "tag",
      "relation": "=",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "email_subject": "This is your email subject.",
  "email_preheader": "<string>",
  "email_body": "<string>",
  "name": "<string>",
  "template_id": "<string>",
  "custom_data": {},
  "email_from_name": "Your Company",
  "email_from_address": "<string>",
  "email_sender_domain": "<string>",
  "email_reply_to_address": "<string>",
  "include_unsubscribed": true,
  "disable_email_click_tracking": true,
  "send_after": "<string>",
  "delayed_option": "<string>",
  "delivery_time_of_day": "<string>",
  "idempotency_key": "<string>"
}'

{
  "id": "<string>",
  "external_id": "<string>",
  "errors": {
    "invalid_email_tokens": [
      "<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>"
    ]
  }
}

POST

notifications?c=email

curl --request POST \
  --url 'https://api.onesignal.com/notifications?c=email' \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {
    "external_id": [
      "<string>"
    ]
  },
  "target_channel": "email",
  "include_subscription_ids": [
    "<string>"
  ],
  "email_to": [
    "<string>"
  ],
  "included_segments": [
    "<string>"
  ],
  "excluded_segments": [
    "<string>"
  ],
  "filters": [
    {
      "field": "tag",
      "relation": "=",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "email_subject": "This is your email subject.",
  "email_preheader": "<string>",
  "email_body": "<string>",
  "name": "<string>",
  "template_id": "<string>",
  "custom_data": {},
  "email_from_name": "Your Company",
  "email_from_address": "<string>",
  "email_sender_domain": "<string>",
  "email_reply_to_address": "<string>",
  "include_unsubscribed": true,
  "disable_email_click_tracking": true,
  "send_after": "<string>",
  "delayed_option": "<string>",
  "delivery_time_of_day": "<string>",
  "idempotency_key": "<string>"
}'

{
  "id": "<string>",
  "external_id": "<string>",
  "errors": {
    "invalid_email_tokens": [
      "<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 email. See Push notification or SMS to send to those channels. Ensure your Email setup is complete.

Review the Sending messages with the OneSignal API guide for details on how to structure your messages.

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.

email_subject

string

default:This is your email subject.

required

The subject of the email. Supports Message Personalization.

email_body

string

required

The body of the email in HTML format. Required if template_id is not set. Supports Message Personalization.

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.

Show child attributes

target_channel

enum<string>

default:email

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

Available options:

push,

email,

sms

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.

email_to

string[]

Send email to specific users by their email address. Include up to 20,000 email addresses per API call. If the email address does not exist within the OneSignal App, then a new email Subscription will be created. Can only be used when sending Email. 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. 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

Show child attributes

email_preheader

string

Preview text displayed after the email subject.

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

email_from_name

string

default:Your Company

The name the email is sent from. Defaults to the 'Sender Name' in the Email Settings of your OneSignal Dashboard. See Email setup and Senders.

email_from_address

string

The full email address shown in the 'From' field of the email (e.g., promotions@news.example.com). This is what recipients see as the sender. If not specified, OneSignal uses the default 'Sender Email' set in your Dashboard's Email Settings. See Senders.

email_sender_domain

string

The authenticated sending domain used for email delivery. This domain must be verified in your DNS records and will determine which domain handles the mail transfer. It may not always exactly match the domain in the email_from_address (e.g., email_from_address = news@example.com while email_sender_domain = mail.example.com), but the root domain must align for DMARC compliance. If not specified, OneSignal uses the default sender email's domain configured in your Dashboard. See Email setup and Senders.

email_reply_to_address

string

The email address users reply to. Defaults to the 'Reply-To' address in the Email Settings of your OneSignal Dashboard. See Email setup.

include_unsubscribed

boolean

Used for important account-related, non-marking emails. If set to true it will send the email to unsubscribed email addresses. Defaults to false. See Email unsubscribe links & headers.

disable_email_click_tracking

boolean

If set to true, the URLs sent within the email will not include link tracking and will be the same as originally set; otherwise, all the URLs in the email will be tracked. See Email unsubscribe links & headers. Defaults to false.

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. Must be a v3 or v4 UUID. Valid for 30 days. Previously called external_id.

Response

200

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.

Show child attributes

Push notification SMS

Using the REST APIs

API reference

SDKs

Overview

Headers

Body

Response

Using the REST APIs

API reference

SDKs

​Overview

Headers

Body

Response

Overview