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

OneSignal provides 3 ways to add email records into your account:

Import Option

Details

Dashboard Upload

Best if you have a csv list of emails and want to upload through the dashboard without code.

If you only have a few emails or just testing, you can individually add emails.

Import Emails via API

Useful if wanting to programmatically add emails server side.

Import Emails via SDK

Recommended for long term implementation client side.

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.

CSV Upload

šŸš§

CSV Email Upload

  • Must have email column
  • Limited to UTF-8 Encoding
  • Columns must be unique
  • 10 columns max
  • No quotes and MUST use commas

Example CSV:

email,group,status,firstname,awesome_level,other_tag_keys

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

Which code to use

One of the benefits of using OneSignal for email is the ability to control both a user's push and email subscriptions together in one place. The code you should use depends on whether you store user emails alongside Player IDs or not. However, not all apps or sites store data this way, so we offer two ways to import emails.

Adding Emails when you have Player ID

If your app or website offers accounts that users log into, you are likely already storing email addresses alongside Player IDs. You may also have associated emails <-> Player IDs if you ask users for email addresses, or if you collect them through other means.

To import emails in this case, we recommend you update your Player ID records with email addresses, so that you do not create duplicate records.

To associate an email record with the device push record you will need to use the device_player_id parameter of the associated device.

See the following for example code:

Language

Code

Ruby

Example Code

Node.js

Example Code (can testĀ from repl.it)

PHP

Example Code (can test from repl.it)

Adding Emails when you do not have Player ID

Some apps and sites do not store email addresses alongside Player IDs. We recommend associating these when possible, however this is unavoidable for some apps and sites based on how they collect emails.

Without association, you may have two unrelated user records (push and email), which can lead to sending redundant information to users, having extraneous records (e.g. if a user cancels their account or uninstalls your app), or just limiting your options for more advanced multi-channel marketing in the future.

To import emails in this case, you will need to create new records that have email addresses. See the following for example code:

Language

Code

Ruby

Example Code

Node.js

Example Code (can testĀ from repl.it)

PHP

Example Code (can test from repl.it)

Import Emails via SDK

Each OneSignal SDK has a setEmail method. When the user provides this email, you can set it upon the user to create an Email Record which is different from the Push Record. Web push users must be subscribed before an email can be set. So if the user is not subscribed, you can capture that email and send with the API method above or add it directly.

šŸ‘

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

Updated 3 days 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.