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
- Embed the email using one of the following methods:
- 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. - Use the
email_body
parameter to embed the email as raw text or HTML.
- Use the
- Set the subject of your email by using the
email_subject
parameter. - 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
email_subject
Type string
Description
The subject line of the email.
Example
{
"email_subject": "Welcome to Cat Facts"
}
email_body
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
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
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
email_reply_to_address
Type string
Description
Specifies the email address users reply to.
Example
{
"email_reply_to_address": "[email protected]"
}
email_preheader
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
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
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
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
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]"
]
}