A benefit of using OneSignal for email is the ability to control both a user's Push and Email subscriptions together in one place. 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.

It is recommended to add emails through the OneSignal SDK setEmail method outlined in the Email Quickstart.

If you have a list of email addresses to start sending right away, you can bulk import in the following ways. It's highly recommended to clean your email list before sending to ensure high deliverability.

📘

Duplicate Email Records

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

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 as well as update the subscription status.

You can also utilize the CSV upload feature for emails as a method to update the tags of existing records in bulk, as well as adding new records with tags.

CSV Upload

📘

CSV Email Upload

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

Example CSV:

email,subscribed,group,status,firstname,awesome_level,other_tag_keys

Select the blue button Update/Import Users

Next to "Import Emails", select Upload CSV

The CSV can contain the following fields/columns:

• email (compulsory field) - must be a string of characters, to form a valid email address.
• tags - any additional columns will be added as user tags
• subscribed - if the email is subscribed or unsubscribed from marketing communication
• external_ID - any form of ID from your system that you want to sync with this email.

If you need help ensuring your CSV is in the correct format, download our template using CSV Template. Make sure you have an email field in the CSV file. All other fields will be added as tags.

Manually Add Emails

Click the dropdown next to Update/Import Users > 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

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.

You can associate the Email Player ID record with the Push Player ID record using the Edit device to set the email property on the Push Player ID record.

For example:

https://onesignal.com/api/v1/players/YOUR_PUSH_PLAYER_ID

{
"app_id": "YOUR_APP_ID",
"email": "THE_ASSOCIATED_EMAIL_ADDRESS"
}

👍

Done!

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