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

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

Body

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.

Structure

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?

Content

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

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.

If you are using an HTML block, you can set the link using [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>

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.

More details see: How does unsubscribing work?

Emoji

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.

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?

FAQ

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 about a month ago


What's Next

Email FAQ

Sending Email Messages


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

Suggested Edits are limited on API Reference Pages

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