Send a message using the email channel.
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.
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.
Choose a targeting strategy
Choose a strategy for targeting users with message. Strategies include sending to:
- Aliases like External ID, Subscription ID, custom aliases, or email addresses.
- Segments
- Filters
See Create message reference for details.
Craft your email
Draft the email and embed it in the email_body parameter as HTML. If you created Templates, you can use the template_id property instead of email_body.
Set the subject of your email by using the email_subject parameter. Refer to the below Email parameters for additional configuration parameters.
Email parameters
Tailor the presentation of emails. The collective impact of these parameters is significant, as they work together to enhance the effectiveness of message campaigns and ensure that users receive the most appropriate and engaging content, ultimately leading to higher user engagement and satisfaction.
email_subject
email_subjectType string
Description
The subject line of the email.
Example
{
"email_subject": "Welcome to Cat Facts"
}
email_preheader
email_preheaderType: 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"
}
email_body
email_bodyType string
Description
Specifies the body of the email being sent. See Message Personalization to learn how to personalize your message.
Required if the template_id parameter is unset.
Example
{
"email_body": "<html>Welcome to Cat Facts</html>"
}
email_from_name
email_from_nameType string
Description
Specifies the name the email is sent from. Defaults to the “Sender Name” in the Email Settings in your OneSignal Dashboard. See Email setup for details.
Example
{
"email_from_name": "Cat Facts"
}
email_from_address
email_from_addressType string
Description
Specifies the email address the email is sent from. Defaults to the "Sender Email" in the Email Settings in your OneSignal Dashboard. See Email setup for details.
Example
{
"email_from_address": "[email protected]"
}
email_reply_to_address
email_reply_to_addressType string
Description
Specifies the email address users reply to. Defaults to the "Reply-To" address in the Email Settings in your OneSignal Dashboard. See Email setup for details.
Example
{
"email_reply_to_address": "[email protected]"
}
disable_email_click_tracking
disable_email_click_trackingType 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. See Email unsubscribe links & headers for details.
- Use if your emails contain Universal Links.
- Defaults to
false.
Example
{
"disable_email_click_tracking": true
}
include_unsubscribed
include_unsubscribedType bool
Description
If set to true, the notification will also be sent to unsubscribed users.
Defaults to false. Use only for transactional emails. See Email unsubscribe links & headers for details.
Example
{
"include_unsubscribed": true
}
Schedule delivery
Messages are sent immediately unless you specify a specific date in which to start sending.
You can also include user-specific delivery like timezone which send to users based on their own data once the message starts sending.
See Create message reference for details.