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

Email Quickstart

How to set up email messaging on your app or website

This guide will walk you through all the steps to have full email integration with OneSignal.

Step 1. Setup Email Service Provider Support

OneSignal Email Messaging requires an account with an eligible email service provider.

Step 2. Add SDK Code

Optional but recommended for capturing new emails as they are provided to you. Also see step 3 for a no-code solution to capture emails through websites.

See Email SDK Methods to for a full list and example code.


Email vs Push Records

Email and Push subscribers will have separate OneSignal Player IDs (user records). This is to manage the case where a user opts-out of one you can still send messages to the other. Email records cannot get push notifications and push records cannot get emails.

Step 3. Email Web Prompt

If you have a website and want to prompt users to provide their email, use the Email & Phone Number Web Prompt to start gathering emails.

Step 4. Import Emails

If you already have a list of email addresses and wish to immediately start sending emails, you can import them into OneSignal.

You can import emails through our Dashboard or API. Details and code examples are available in Import Email Addresses guide.

Step 5. External User Ids

Each Email record in OneSignal gets a unique Player Id (OneSignal's Device Id). The Email Player Id will be different from the Push record Player Id.

In order to tie the Email and Push Player Id together under a single User Id, leverage the OneSignal setExternalUserId SDK method. See External User Ids. It is recommended to call this method after the email is set.

Step 6. Send Tags

Data Tags are optional but highly recommended for event triggered targeting of devices and also allow for message personalization.

Common tags used for message personalization:

Tag Key

Tag Value


user’s full real name


user’s first name


user’s last name


name that users give themselves; often not a real name (e.g. PokeCatcher22)


if you wish to refer to users by a salutation (Ms, Dr, Hon, etc)

Please refer to the sendTag and sendTags methods in Data Tag Implementation to learn how to send them.

Step 7. Send Emails

Send emails using OneSignal's:



You are a OneSignal Email Pro!

Updated 12 days ago

Email Quickstart

How to set up email messaging on your app or website

Suggested Edits are limited on API Reference Pages

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