OneSignal's Email Messaging requires the use of a third-party email service provider to handle email delivery. All you have to do is set up the integration between the provider and OneSignal, and you'll be ready to send emails through OneSignal.

Step 1. Requirements

• Mailgun Account
• Mailgun US API. Currently Mailgun's EU API is not supported.
• OneSignal Account
• A domain you own and DNS provider.

📘

Don't have a Domain, DNS Provider or Email Service Provider?

No problem! Contact OneSignal's Sales Team and ask about Email Onboarding.

Step 2. Configure your Domain for Email

In Mailgun, navigate to Sending > Domains click Add New Domain.

Add your domain and follow the setup.

You will be given two TXT (SPF and DKIM), two MX, and a CNAME record. Update these records in your DNS provider. It may take up to 48 hours (usually less) to propagate. Mailgun will email you once complete.

🚧

Confirm all DNS records are verified.

Check in Mailgun > Sending > Domain settings > Your Domain > DNS records. Green checkboxes will show next to each record correctly identified.

For example, if the CNAME is missing, you will not get email click, open and unsubscribe tracking.

Step 3. Add OneSignal Webhooks to Mailgun

Within Mailgun Sending > Webhooks > Your Domain > Webhooks.

This should be pointing to https://onesignal.com/email/hooks/mailgun

Step 4. Change Tracking Protocol to HTTPS

This will make sure that when recipients click on links within your emails they are brought to a secure page that does not show a warning that the link is not secure.

Go to your domain and navigate to Domain Settings.

Under Tracking > Tracking Protocol change the setting from HTTP to HTTPS

Step 5. Enable Email Messaging

After all your DNS records are verified, go to OneSignal and navigate to Settings > Platforms > Email.
Select Mailgun and Continue.

In another tab, navigate to Mailgun > Sending > Domain settings > Your Domain > SMTP credentials.

Copy your Domain and SMTP Login into OneSignal.

Click the Reset password button and Copy the provided value into OneSignal's Default Password field.

In Mailgun under Settings > API Keys copy the Private API key and paste into the OneSignal API Key Field and Continue.

Make sure you do not block the OneSignal Server API keys under "IP Whitelist". It's recommended to keep this section blank. However, if you use it add 147.75.1.2/30 and 147.76.1.2/30 to make sure it is not blocked.

Step 6. Configure Delivery Defaults

In OneSignal, add the default name and email address you want your emails to come from (these can be changed later).

Press Done when finished.

Step 7. Add Subscribers

If you have a list of emails ready, select Upload CSV to Import Email Addresses. You can always do this again later.

If you have a website and want to prompt users to provide their email. Select Add Web Prompt to use OneSignal's Email Web Prompt.

Step 8. Send Yourself a Test Email

In OneSignal > Messages > Email, select New Email.

Add a Subject and click Send Test Email. Input your email and press Send Test Message.

An email should arrive to your inbox shortly!

📘

Troubleshooting

If running into issues, see our Email FAQ.

If stuck, contact support directly or email [email protected] for help.

For faster assistance, please provide:

• Your OneSignal App Id
• Details, logs, and/or screenshots of the issue.
• Steps to reproduce

Step 9. Set Custom User Properties

OneSignal creates channel-level device records under a unique Id called the player_id. A single user can have multiple player_id records based on how many devices, email addresses, and phone numbers they use to interact with your app.

If your app has its own login system to track users, call setExternalUserId at any time to link all channels to a single user. For more details, see External User Ids.

All other event and user properties can be set using Data Tags. Setting this data is required for more complex segmentation and message personalization.

Step 8. Collect New Emails

Emails can be added into OneSignal using the following options outlined in our Import Email Addresses guide.

👍

Setup Complete!

Visit Email Tutorials for next steps.

FAQ

How do I whitelist OneSignal's IPs?

OneSignal uses GCP data centers located in Groningen, Netherlands. There are a wide range of IPs that can be used. You can copy-paste the following IP ranges to your whitelist (make sure to include your own IP Address if you have not!):

34.90.0.0/15,34.104.126.0/23,34.124.62.0/23,34.141.128.0/17,34.147.0.0/17,34.157.80.0/23,34.157.208.0/23,35.204.0.0/16,35.214.128.0/17,35.220.16.0/23,35.234.160.0/20,35.242.16.0/23,2600:1900:4060::/44