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 email_to 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`

Type string

Description

The subject line of the email.

Example

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

`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"
}

`email_body`

Type 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`

Type 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 and Senders for details.

Example

{
  "email_from_name": "Cat Facts"
}

`email_from_address`

Type 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 and Senders for details.

Example

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

`email_sender_domain`

Type string

Description

Specifies the sending domain the email is sent from. Defaults to the default sender email's sending domain in the Email Settings in your OneSignal Dashboard. See Email setup and Senders for details.

Example

{
  "email_sender_domain": "mail.cats.org"
}

`email_reply_to_address`

Type 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`

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

Type bool

Description

This property is best used for important account-related, non-marking emails. If you set this to true it will send the email to unsubscribed email Subscriptions.

Including this property with a template_id will override whatever is selected for Include sending to unsubscribed users option for that template. 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 with the send_after parameter.

You can also include user-specific delivery based on each user's timezone or last-active with the delayed_option parameter.

See Create message reference for details.