Server REST API Reference
Log InSign Up

Email

post https://api.onesignal.com/notifications?c=email

Send a message using the email channel.

Overview

The Create Notification 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.

This API allows you to email users regardless of their subscription status. Users do not need to set up email Subscriptions before sending an email. If an email Subscription does not exist for the app, sending an email with include_email_tokens automatically creates a Subscription for that email address.

How to use this API

To start with this API, ensure your application is properly configured by following the Email Setup guide.

Craft your email

  1. Embed the email using one of the following methods:
    1. Use the template_id parameter to specify an existing email template and render it with additional data, Data Tags, or user data stored in OneSignal.
    2. Use the email_body parameter to embed the email as raw text or HTML.
  2. Set the subject of your email by using the email_subject parameter.
  3. Refer to Email channel parameters for additional configuration parameters.

Choose a targeting strategy

Choose only one strategy for targeting users with this message:

  • Segments
  • Filters
  • Aliases

Schedule delivery

You can specify rate limits and delivery timing as well. See Delivery Notification Parameters to learn more.


Body Parameters

email_subject

Type string

Description

The subject line of the email.

Example

{
  "email_subject": "Welcome to Cat Facts"
}

email_body

Type string

Description

Specifies the body of the email being sent.

Guidance

Required if the template_id parameter is unset.

Example

{
  "email_body": "<html>Welcome to Cat Facts</html>"
}

📘

See Message Personalization to learn how to personalize your message using additional data in the request, Data Tags, or user data.

email_from_name

Type string

Description

Specifies the name the email is sent from.

Guidance

It defaults to the “From Name” setting in the Email Settings in the Dashboard.

Example

{
  "email_from_name": "Cat Facts"
}

email_from_address

Type string

Description

Specifies the email address the email is sent from.

Example

{
  "email_from_address": "[email protected]"
}

email_reply_to_address

Type string

Description

Specifies the email address users reply to.

Example

{
  "email_reply_to_address": "[email protected]"
}

email_preheader

Type: string

Description

Preview text displayed after the email subject to provide additional context about the email.

Example

{
  "email_preheader": "Welcome to the Daily Cat Facts"
}

disable_email_click_tracking

Type bool

Description

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.

Guidance

  • Use if your emails contain Universal Links.
  • Defaults to false.

Example

{
  "disable_email_click_tracking": true
}

📘

Email Link Tracking Enabled by Default

More information available on Email Links and Click Tracking.

template_id

Type string

Description

Identifies a specific template configured within the dashboard. Templates enable standardized notifications across campaigns

Guidance

Provide the UUID of the template, which can be found in the URL when viewing a template on our dashboard.

Example

{
  "template_id": "be4a8044-bbd6-11e4-a581-000c2940e62c"
}

include_unsubscribed

Type bool

Description

If set to true, the notification will also be sent to unsubscribed users.

Guidance

Defaults to false. Use only for transactional emails.

Example

{
  "include_unsubscribed": true
}

📘

Sending to Unsubscribed Emails

More information available at Unsubscribe Links & Email Subscriptions.


include_email_tokens

Type string[]

Description

Allows targeting users based on their email address. If the email address does not exist within the OneSignal App, then a new email subscription will be created.

Guidance

You may include up to 2,000 email addresses per API call.

Example

{
  "include_email_tokens": [
    "[email protected]"
  ]
}
Language