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.

Setup

1. Add a new domain in Mailgun

Skip to step 2 if you already have a domain setup in the US region with Mailgun.

From the Mailgun dashboard, navigate to the Domains page.

1. Click the Add new domain button

2. Configure the domain

2. Verify DNS settings

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.

Check-in Mailgun > Sending > Domain settings > Your Domain > DNS records. Green checkboxes will show next to each record correctly identified. If the CNAME is missing, you will not get email click, open, and unsubscribe tracking.

3. Setup SMTP Credentials

From the Mailgun dashboard navigate to Sending > Domain settings > SMTP credentials.

1. Click Add new SMTP user button

2. Provide user with a login name

3. Save credentials for later

4. Get a Mailgun API key

1. Navigate to your Mailgun dashboard and click the API Keys located in the bottom-right of the page

2. Click Add new key

3. Enter a name for your key and click Create Key

4. Copy your API key.

5. Configure OneSignal email

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

2. Select Mailgun as email provider.

3. Enter the domain from Step 1 - Add a new domain, the SMPT login details from Step 3 - Create SMTP Credentials, and the API key from Step 4 - Create an API key.

4. Provide default values for the sender name and the email address that will appear in the from header if none are specified when creating an email.

6. Add OneSignal Webhooks to Mailgun

Within Mailgun Sending > Webhooks > Your Domain > Webhooks.

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

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

8. Add Email Subscriptions

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.

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

Recommended

Identify Users

Required if using integrations.
Recommended for messaging across multiple channels (push, email, sms).

OneSignal creates subscription-level records under a unique ID called the subscription_id. A single user can have multiple subscription_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 login at any time to link all channels to a single user. For more details, see Aliases & External ID.

Add Data Tags

Optional

Tags are custom key : value pairs of String data used for tracking user events and properties. Setting tags is required for more complex segmentation and message personalization.

See Data Tags for more details.

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 allowlist OneSignal's IPs?

See the requirements in our REST API Overview for details.