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

Import Email Addresses

How to import email addresses from your server to use OneSignal Email Messaging

Import Option


Dashboard Upload

Upload a CSV list of emails and add/remove/update Data Tags for segmentation and personalization.

Also, individually add emails if needed.

Import Emails via API

Programmatically add emails server side.

Import Emails via SDK

Recommended client side implementation.

Common Questions

What happens if I add the same email multiple times?

OneSignal will automatically remove duplicates and combine associated tags. If the email record is marked as unsubscribed, it will continue to be marked unsubscribed unless manually updated.

Why do email records have their own Player ID?

Email records will have a separate device record (Player ID) than push notification subscribers. This is to manage cases of the user opting-out of one channel, you can still message them on the other.

Import Emails through Dashboard

Within Audience > All Users, you can import a CSV list of email addresses or add email addresses directly.

With emails, you can add Data Tags for segmentation and Message Personalization.

CSV Upload


CSV Email Upload

  • Must have email column
  • Limited to UTF-8 Encoding
  • Columns must be unique
  • 10 columns max
  • Commas only
  • No quotes

Example CSV:


Select Actions > Import/Update Users

Next to "Import Emails", select Upload CSV

Make sure you have an email field in the CSV file. All other fields will be added as tags.

Manually Add Emails

Click Actions > Manually Add Emails to open a new modal where you can add an individual user's email and tag data.

Adding Tags

In addition to adding a user's email, you may also add/update Data Tags to the user record. The Manually Add Users modal supports adding up to 10 tags.

If the email address you enter is not found in your OneSignal user list, a new user will be created. However, if the email address is found, the user will be updated with any tags that you add here. If a user already has a tag with a particular key (e.g. levels_completed), any value you add here will replace the value the user record previously had.

Import Emails via API

A benefit of using OneSignal for email is the ability to control both a user's Push and Email subscriptions together in one place.

Using the Server API Add a device endpoint, you can import your Email Addresses into OneSignal.

This creates a new unique Email Record Player ID in OneSignal. To associate the OneSignal Player ID Records across Email, Push, and SMS together to the same User, set the external_user_id parameter to be your unique User ID from your databases.

If you are storing the OneSignal Push Record Player IDs in your database, you can also link this to the Email Record Player ID using the device_player_id parameter.

See the following for example code:




Example Code


Example Code (can test from


Example Code (can test from

Import Emails via SDK

Each OneSignal SDK has a setEmail method which should be called when the user provides their email.

This creates a new Email Player ID record and associates it with the Push Player ID record for that user by calling this method.

Calling setEmail multiple times with the same email will not create duplicate records inside OneSignal.

Websites should use setEmail upon the user providing the email for the first time and upon authentication into the site to make sure it is tied to the Push Player ID if this changes (like upon clearing cache).



Once you've imported your emails, go back to Email Quickstart to determine if you have any steps left.

Updated about a month ago

Import Email Addresses

How to import email addresses from your server to use OneSignal Email Messaging

Suggested Edits are limited on API Reference Pages

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