Sending Email Messages

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

The Messages page shows you recent messages you've sent or scheduled through the dashboard.

Just select the drop down and click "New Email".


OneSignal's Messaging works similarly for all channels 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.

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.

See below for sending test messages.


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

To learn more about tags, see Message Personalization.

Unsubscribe Link

Currently, every email sent from OneSignal requires an unsubscribe link to let users opt-out of future mailings. This unsubscribe link must be set using this literal syntax [unsubscribe_url] which is added in 1 of 2 ways:

  1. You can add this special unsubscribe link [unsubscribe_url] in a text area by selecting Special Links > Unsubscribe. This will drop an unsubscribe link into the text area. You may also highlight text before adding this link.
  1. If you are using an HTML block, you can put [unsubscribe_url] in the href= portion of an <a> tag like this:
    <a class="Unsubscribe--unsubscribeLink" href="[unsubscribe_url]" target="_blank" style="font-weight:600;text-decoration:none; color: #555555;">unsubscribe</a>


Must contain [unsubscribe_url]

Emails that do not contain [unsubscribe_url] will have one added automatically at delivery at the bottom of the email which cannot be styled or overwritten.


Create your own Unsubscribe URL

While your emails must contain [unsubscribe_url], you can style it to be "harder to find" and include your own unsubscribe url that is easier to find.

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.

More details see: How does unsubscribing work?


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


Step 4 Scheduling

Emails can be sent immediately or scheduled up to 1 month in advance.

Test Messages

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.


Tag Substitution Limitation

Tag Substitution will not work with Send Test Message. You will need to setup a segment to send to yourself to test or use the API.


Step 5 Confirm Message

Once you've decided on an email you like, click Confirm Message 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 Reports, 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.


What’s Next