Email Messaging

Common Email Guides and Tutorials.


You're Viewing User Model Beta Documentation πŸŽ‰

OneSignal is in the process of migrating from a device-centric model (player ID) to a new user-centric data model (OneSignal ID). To learn more, check out the User Model Beta Overview.

Please refer to Version 9 of our documentation for device-centric information.

The following are important features and best practices for OneSignal's email messaging capabilities. Make sure you follow OneSignal's Email Acceptable Use Policy & Code of Conduct to keep your account in good standing and maintain high deliverability.

Getting Started

Common and important features when getting started with email messaging.

Use a Subdomain

Using a subdomain for email communications is a recommended practice in the industry. It improves email credibility and deliverability by isolating email traffic from your primary domain, reducing the risk of spam association.

Subdomains also allow you to have more control over implementing email authentication measures and monitoring performance.

Importing Email Addresses

If you already have a list of email addresses, you can Import Email Addresses into your OneSignal App through the Dashboard or API. It's highly recommended to clean your email list before sending to ensure high deliverability.

Also see Email Segmentation Best Practices.

Follow a Warm Up Plan

Another way to increase deliverability is to follow a warm up plan by sending a small amount of emails at first and gradually increasing that over time. See Email Warm-Up for details.

Validate Emails

Users should be asked for consent or acknowledge that they want emails from you. Once you obtain their email address, it’s recommended to validate that email is correct and used before sending it messages. This ensures that email addresses are real, spelled correctly, and won’t result in a bounce. It helps improve your deliverability.

See Example: Verification, Magic Link, OTP for details.

Sending Emails

OneSignal provides different ways to Send Email Messages:

  • Use the dashboard for a no-code approach with a drag-and-drop editor or add your own HTML.
  • Setup Journeys for easy automation and omni-channel flows.
  • For more programmatic approach use our Create notification API with details in Send Transactional Emails guide.

Email Design

The OneSignal dashboard provides options for Designing Emails with Drag and Drop and Designing Emails with HTML. Some best practices as follows.

Include Unsubscribe URLs

Unsubscribe links shouldn't be "hard to find". You should use accessible, or high contrast, colors and a large enough font that is easy to read (we recommend at least 12px). If a person can't easily see unsubscribe links, ISPs may mark your emails as spam which will affect future deliverability across all your emails. Make sure to follow the recommended syntax when including Unsubscribe Links .

Avoid shortened URLs

Shortened URLs in an email can often be flagged up as spam. So avoid shortening your URLs.

Add a Physical Address in your Footer

Within the footer of your email, add a physical address. This ensures you are compliant with the CAN-SPAM Act of 2003

Limit Image Sizes

We recommend each image is kept to a 10 MB as a maximum size. This prevents your email from being blocked from the user's email client.

Images you want to be the same aspect ratio, size, and dimensions should be modified before used within the email editor. For example, if you have products showing in a row, and product 1 is 50x50 pixels but product 2 is 100x30 pixels, this will not render the same hight and width. You must modify the images to be the same dimensions before use within the editor.

Use a Preheader (Email Preview Text)

Preheader text or "email summary" is the text that shows up next to or below the subject line in an inbox or email client. Using a preheader increases open rates and audience engagement as it allows your user to be enticed to open the email.

When creating an email or template, you can include the Preheader Text using the provided field. Preheaders can include text, Data Tags, or emojis.


Add preheader text to a message with the preheader text field.

Preheaders have character limits that vary based on the email client.

Email ClientLimitClient Type
iOS Outlook74Mobile Email Client
Android Native43Mobile Email Client
Android Gmail24Mobile Email Client
iOS Native82Mobile Email Client
iOS Gmail30Mobile Email Client
Apple Mail33Desktop Email Client
Outlook β€˜1338Desktop Email Client
Outlook for Mac β€˜1553Desktop Email Client
Outlook β€˜1650Desktop Email Client
AOL Mail81Webmail Client
Gmail119Webmail Client
Outlook.com49Webmail Client
Office 36540Webmail Client
Mail.ru64Webmail Client

Source: Email on Acid

Avoid Image Only Emails and Add Alt-text to images

Over 3.2 million Americans have a visual impairment or blindness in the US, in 2015. This means emails should not only contain images, as screen readers cannot discern the content of an image, and instead rely on alt-text.

Add alt-text to any image used to ensure accessibility.

Use Contrasting Colors

Choose background colors and foreground colors with contrast to ensure your text is legible for those with visual impairments.


Image showing examples of color contrast, as shown in Email On Acid Article

Email FAQs

Email Client Maximum Size

Email clients tend to limit the size of an inbound email. If your email goes over a certain size, it is highly likely it will rejected and your deliverability rates will be lower than expected.

Email ClientSending and inbound size limits
Apple Mail (iCloud)20 MB
Gmail25 MB
Outlook/Office 36520 MB (10 MB for Exchange accounts), with up to 150 MB in Office 365
ProtonMail25 MB
Yahoo25 MB
Zoho Mail20 MB

Source: Mailtrap - Recommended Email Size

Email Providers Maximum Size

Email providers additionally limit the size of emails that can be sent as an outbound emails. If your email goes over a certain size, it will not be sent by the provider being used.

Email Sending ProviderSending size limit
Mailgun25 MB
Mailchimp (previously known as Mandrill)25 MB
Sendgrid30 MB

Source: Mailtrap - Email Providers Recommended Email Size

Why are my Emails ending up in the Promotions Tab?

Avoid too many links in your email.
Avoid using spam trigger words.
Avoid sending email blasts.
Avoid sending lengthy emails.
Personalize your emails.
Keep text to HTML ratio 60:40.