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 FAQ

Using Email with OneSignal FAQ

Email Service Providers

Which email service providers are supported in OneSignal?

Currently, Sendgrid, Mailgun, and Mandrill by Mailchimp are supported by OneSignal. We are working on support for Amazon SES as well. Contact us if you have another email service provider that you want OneSignal to support.

What are the differences between email service providers?

There are only minor differences between email service providers that OneSignal supports. For maximum compatibility we recommend using Sendgrid.

Does this mean I still have to pay another provider for email?

While you are still testing email, you can take advantage of the free plans offered by Sendgrid (up to 40k emails) and Mailgun (up to 10k emails).

Once you are sending a significant amount of emails, you will need to pay an email service provider to act as the final delivery system for OneSignal Email Messaging. However, since OneSignal Email Messaging provide marketing email capabilities on top of transactional email providers, you will only need to pay the much cheaper transactional email rate rather than the rate typically charged for marketing automation tools.

What should I do if I don't have an email provider?

Since OneSignal does not act as it's own email service provider, you will need to sign up for one. See above.


Email vs Push

Email and push subscribers will have separate OneSignal Player IDs. This is to manage the case where a user opts-out of one you can still send them messages to the other.

If you want to tie emails to push subscriptions, you can to do so with OneSignal Data Tags or you can use the External User Id option.


Email Setup

How do I change my domain's email settings?

To configure email, you will need to modify your domain's DNS records. Different email service providers have different requirements for which records need modifying, which likely include MX, CNAME, and TXT types.

You can modify your DNS records where you have your domain hosted. Links to guides on how to do this for some of the most popular hosts are below:

GoDaddyMX, CNAME, TXT
NamecheapDNS Questions
Network SolutionsMX, CNAME, TXT
RackspaceMX, CNAME
HostGatorMX, CNAME
GoogleMX, CNAME
CloudflareCloudflare support
DNS Made EasyMX, CNAME, TXT
DreamhostMX, CNAME, SPF, TXT
DynSetup DNS
HoverEdit DNS records
Amazon Route 53Working with Records

📘

DNS records may take up to 48 hours for changes to propagate across the internet.

What are Webhooks? Why does OneSignal require them?

Webhooks allow access to email delivery statistics, and are sent from your email service provider to OneSignal. To simplify setup, OneSignal will automatically configure Webhooks when possible with your email provider.

If you already have an active Webhook, you must first disable it in your email service provider before you're able to continue. Webhooks are often used for things like analytics integrations. Contact us for possible workarounds.

I don't use push notifications and just want to use email. Can I do this?

The OneSignal Email Messaging beta is meant for customers who already use the OneSignal SDK for push notifications and want to add email messaging capabilities. We do not yet support using OneSignal solely as an email marketing tool.


Using Email

Does OneSignal Email Messaging work with all email clients?

Generally yes - a lot of work has been put into ensuring maximum compatibility and visual similarity across major email clients including gmail, Outlook, yahoo mail, and more.

How does unsubscribing work?

Every email sent through OneSignal must include an unsubscribe link to allow users to opt-out of future mailings. These links may be added in the composer in New Email, or may be added when sending an email through the API by including [unsubscribe_url] in the href= portion of an <a> tag.

The exact unsubscribe link will vary depending on the email service provider you've selected. Some, like Mandrill will redirect users to a onesignal page that tells users have successfully unsubscribed, while others will handle the user flow of unsubscribing themselves.

Can I send emails to my push notification subscribers?

Sending emails to push notification subscribers requires two things:

  1. You have the email address to send to

  2. You know which push notification subscriber is associated with that email address

Email addresses are not collected when users subscribe to push notifications. The only way to send emails to subscribers is if you collect email addresses directly from users that already subscribe to (or will later subscribe to) push notifications.

If your app or website collects email addresses, you likely already have an association between emails and subscribers (technically between email and Player ID). In this case, you can use the setEmail method to add an email address to an existing subscriber. You may also bulk import email addresses that are associated with Player IDs. We recommend both.

If your app or website does not collect email addresses, you will need to do so in order to send emails to your push subscribers. See What are ways I can collect user email addresses? (below).

Can I target emails based on lists or campaigns?

If you currently have email lists with your current provider, you can export that list to CSV. In the CSV file, the columns should read: email, list_1 where list_1 can be whatever you like to help associate those emails with the given list. This will be the Data Tags Key

Then under the list_1 column you can use "true" or "1", this will be the Tag's Value.

You can then Import Email CSV to the OneSignal dashboard and create Segments based on the Data Tag list_1 and use "exists" or whatever value you want to set it to.


Importing Emails

More details in Import Email Addresses.

What are ways I can collect user email addresses?

There are several ways an app or site can gather user email addresses. The most important thing to keep in mind is that you must get a user's consent to send them email, otherwise users will often treat your emails as spam. In many jurisdictions gathering email without consent is also not legal.

The following are some tips on how to request user consent for email:

If you use Facebook authentication
Depending on your implementation, you may already get email when using Facebook to authenticate users. This requires the email permission, which presents users a permission prompt for them to accept. We recommend adding an explanation as to why you need the user's email address when requesting permission (see Facebook's Requesting & Revoking Permissions doc).

If you use Google Sign-In in an Android app
If you use Google Sign-In in an Android app, you may have access to the user's email by using the getEmail method. The same caveats about getting permission above apply.

If you have an Android app
Android supports additional permissions to get the device's primary email address. See this StackOverflow answer for two ways to do so. Unlike the Facebook method, it's the app developer's job to ask users for permission before getting the device email, and note that Google is likely to shut down apps that do not present users with a clear indication and permission that you wish to send them email.

Ask for email
You can prompt users to enter their email address to sign up for updates, a newsletter, etc. When doing so, if the user already has push permissions, you can associate their Player ID with the email address you collect. As always, we recommend finding ways to add value for users when asking for email, such as getting updates on things they may care about.


Updating Email Records

Identity Verification is required for updating current email records using the Edit device API.

{
    "app_id": "3beb3078-e0f1-4629-af17-fde833b9f716",
    "email": "[email protected]",
    "identifier": "[email protected]",
    "parent_player_id": "push_player_id",
    "external_user_id": "194365",
    "device_type": 11
}

If you do not have Identity Verification turned on, you can use the Add a device API method which will create a new email record. If you want to delete the old record, you can do so within our dashboard or API. See Delete Users for more details.

{
    "app_id": "3beb3078-e0f1-4629-af17-fde833b9f716",
    "email": "[email protected]",
    "identifier": "[email protected]",
    "parent_player_id": "push_player_id",
    "external_user_id": "194365",
    "device_type": 11
}

Updated 14 days ago



Email FAQ


Using Email with OneSignal FAQ

Suggested Edits are limited on API Reference Pages

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