OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Sending Email Messages

OneSignal features - Sending Email Messages with the new OneSignal Email Messaging composer

Beta Feature

Beta Feature

OneSignal Email Messaging is currently in Beta, which means you should expect the user interface and available features to change. To learn more, please return to Email Quickstart.

The Messages page shows you recent messages you've sent or scheduled, and links you to New Email Message and Sent Messages.

To send an email, just click on New Email:

New Email Page

Dashboard > Messages > New Email Message

OneSignal Email Messaging works just like our existing New Push Message notification creation flow, where you select your audience, craft your message, and schedule it for delivery.

Step 1. Audience

Selecting Users

First, select your audience for your email.

By default, emails will go to the All segment, which are all of the users with valid email addresses. You may also include or exclude segments of users if you've set up User Segments. For instance, you may wish to send an email only to users who have not logged in in the past week.

Want to send to test users? See below

Step 2. Email Details

Next, enter the email subject you want users to see in their inbox. By default, the name and email address your email is from are taken from Platforms: Email, but you can override them in individual emails here.

Step 3. Create Message

Create Message lets you visually design and compose your emails just as they'll be seen in your users' email boxes. The OneSignal Email Messaging composer consists of three different parts:

  • Body - settings that apply to the entire message
  • Structures - rows of content in the message, which can be added, removed, copied, & moved
  • Content - individual content blocks: images, text, buttons, etc., which also can be added, removed, copied, and moved


The body contains the general settings for the message.

Body items are inherited by Structure and Content blocks. For example, the font family set in the message settings is then used everywhere in your message, except where you use a custom setting.

This is very useful to build a coherent message very quickly.


The structure tab is where you can find different types of rows to insert into the message.

Rows are structural units that define the horizontal composition of a section of the message by using columns. You can use from one to four columns.

Using more than one column allows you to put different content elements side by side.

You can add to your messages all the structural elements you need, regardless of the template you selected when you started.

Every row has its own settings, which gives you the kind of flexibility that before was only achieved with hand-coded email.

For example, you can select a background color for the entire row, only the message area, or a specific column within it.

See also: How do I change the properties of a row?


The Content section includes a series of tiles that represent the different kinds of content you can use in your message. More will become available in the future.

To use them, just drag one inside a column, it will auto-adjust to the column width.

Every content block has it owns settings, such as granular control on padding. The right-side panel automatically switches to a property panel for the selected content element.

Email Templates

Just like in notifications, OneSignal Email Messaging supports Templates, letting you save designs you like for future use. When you've designed a layout you like, just click Save Template in the top of the create message box, and you'll be able to name your template. At any time you may also click Select Template to load existing email templates. OneSignal Email Messaging comes with several pre-built templates to choose from.

Merge Tags

Merge tags are placeholders that are replaced with real values at the time the message is sent. Just add the @ symbol in a text area in your email, and the list of available tags will show up:

When you select a tag, it will appear using the liquid templating language, e.g. {{ first_name | default: "there" }}. You may adjust the default value to your liking here. Defaults will only appear if a user does not have a tag already.

Beta - Currently, the only merge tags available are for names and salutations. Please contact us to give us feedback on what you'd like to see! See Email Setup for how to send OneSignal these tags.

To learn more about tags, see Message Personalization.

Unsubscribe Link

By law, every email requires an unsubscribe link to let users opt-out of future mailing. You can add an unsubscribe link by clicking in a text area and selecting Special Links > Unsubscribe. This will drop an unsubscribe link into the text area. You may also highlight text before adding this link.

Emails that do not contain an unsubscribe link will have one added automatically at delivery at the bottom of the email. The location and style of this link may not be to your liking, so it's best to add the link to email templates yourself.

Make sure unsubscribe links are easily visible to users, with a high contrast color to distinguish them from the background and a large enough font that users will be able to read it (we recommend at least 12px). Note that if users cannot easily see unsubscribe links, they may mark your emails as spam which will affect future deliverability across all your emails.


How does unsubscribing work?


Similar to push notifications, each email platform renders emoji slightly differently, so plan accordingly:

Step 4. Scheduling

Clicking the Schedule item lets you select among different notification delivery scheduling options:

The OneSignal Dashboard detects timezone according to your Operating Systems time.

You can set a desired time to start sending a notification using the "Begin sending at a particular time" option. This will make all the notifications go out to your users at the desired time.

OneSignal also provides Per-User Optimizations to target users in specific ways.

Per-user Optimization

Beta Note

Per-user Optimization is still in development for email.

Intelligent Delivery

Learn more in Intelligent Delivery.

Optimize by the user time zone

This will send the notification to each user at the time you specify but for the user's timezone.

If you are not sure exactly when a notification will be sent, we show you in the tips on the right-hand side. For example, if you chose "Begin Sending at a Particular Time" and "Optimize by Timezone" options, it would look something like this:

Test Messages

Want to make sure your message will look good in your email client? At any time you can test your emails by scrolling to the bottom and clicking Send Test Message. All test messages are sent immediately, regardless of what is set up in Schedule.

Step 5. Confirm Message

Once you've decided on an email you like, click Confirm Message at the bottom, and make sure everything checks out. If it does, click Send Message in confirmation modal, and your email will start sending.

Message Reports

After sending an email, you'll be brought to the Message Report, where you'll be able to see the performance of your email.

Certain statistics about email performance (such as unsubscribes, bounces, delays, spam reports, etc) may not be available when using certain email service providers. See Which email service providers support which statistics?


How do I change the properties of a row?

First mouse over an area of the stage that is free of message content.

Then, click to select it.

The right side of the editor will now show you some properties that apply to the entire row (e.g. background color, background image, padding, etc.)...

... and some that apply to each column in the row. A row could contain multiple columns, and you can control several settings independently for each column.

Updated 2 years ago

Sending Email Messages

OneSignal features - Sending Email Messages with the new OneSignal Email Messaging composer

Beta Feature

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.