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 email users regardless of their subscription status. Users do not need to set up an email subscription before sending an email. If a user does not have an existing subscription, sending an email will automatically create a new one for them.

How to Use this API

To get started 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.

Examples

Send to segments

curl --include \
     --request POST \
     --header "Content-Type: application/json; charset=utf-8" \
     --header "Authorization: Basic <YOUR_REST_API_KEY>" \
     --data-binary '{
         "app_id": "YOUR_APP_ID",
         "email_subject": "Welcome to Cat Facts!",
         "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts</h1><h4>Learn more about everyone\'s favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can\'t wait to surprise you with funny details about your favorite animal.</p><h5>Today\'s Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href=\'https://catfac.ts/welcome\'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href=\'[unsubscribe_url]\'>Unsubscribe</a></small></p></body></html>",
         "included_segments": ["Subscribed Users"]
     }' \
     https://api.onesignal.com/notifications

Send to dynamically filtered segment

curl --include \
     --request POST \
     --header "Content-Type: application/json; charset=utf-8" \
     --header "Authorization: Basic <YOUR_REST_API_KEY>" \
     --data-binary '{
         "app_id": "YOUR_APP_ID",
         "email_subject": "Welcome to Cat Facts!",
         "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts</h1><h4>Learn more about everyone\'s favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can\'t wait to surprise you with funny details about your favorite animal.</p><h5>Today\'s Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href=\'https://catfac.ts/welcome\'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href=\'[unsubscribe_url]\'>Unsubscribe</a></small></p></body></html>",
         "filters": [
             {"field": "tag", "key": "level", "relation": ">", "value": "10"},
             {"operator": "OR"},
             {"field": "amount_spent", "relation": ">", "value": "0"}
         ]
     }' \
     https://api.onesignal.com/notifications

Send to specific users via External ID

curl --include \
     --request POST \
     --header "Content-Type: application/json; charset=utf-8" \
     --header "Authorization: Basic <YOUR_REST_API_KEY>" \
     --data-binary '{
         "app_id": "YOUR_APP_ID",
         "email_subject": "Welcome to Cat Facts!",
         "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts</h1><h4>Learn more about everyone\'s favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can\'t wait to surprise you with funny details about your favorite animal.</p><h5>Today\'s Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href=\'https://catfac.ts/welcome\'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href=\'[unsubscribe_url]\'>Unsubscribe</a></small></p></body></html>",
         "include_aliases": {
           "external_id": ["CUSTOM-EXTERNAL_ID-ASSIGNED-BY-YOU-1", "CUSTOM-EXTERNAL_ID-ASSIGNED-BY-YOU-2", "CUSTOM-EXTERNAL_ID-ASSIGNED-BY-YOU-3"]
         },
         "target_channel": "email"
     }' \
     https://api.onesignal.com/notifications

Send to specific email addresses

curl --include \
     --request POST \
     --header "Content-Type: application/json; charset=utf-8" \
     --header "Authorization: Basic <YOUR_REST_API_KEY>" \
     --data-binary '{
         "app_id": "YOUR_APP_ID",
         "email_subject": "Welcome to Cat Facts!",
         "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts</h1><h4>Learn more about everyone\'s favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can\'t wait to surprise you with funny details about your favorite animal.</p><h5>Today\'s Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href=\'https://catfac.ts/welcome\'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href=\'[unsubscribe_url]\'>Unsubscribe</a></small></p></body></html>",
         "include_email_tokens": ["[email protected]", "[email protected]"]
     }' \
     https://api.onesignal.com/notifications

Send to unsubscribed users

curl --include \
     --request POST \
     --header "Content-Type: application/json; charset=utf-8" \
     --header "Authorization: Basic <YOUR_REST_API_KEY>" \
     --data-binary '{
         "app_id": "YOUR_APP_ID",
       	 "email_subject": "Welcome to Cat Facts!",
         "template_id": "<TEMPLATE_ID>",
         "included_segments": ["Subscribed Users"],
         "include_unsubscribed": true
     }' \
     https://api.onesignal.com/notifications

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