This setup guide is if you have Mailgun already and want to integrate it with OneSignal. If you don’t have a Mailgun account, you can use OneSignal Email instead.

​
Requirements

​
Setup

​
1. Add a new domain in Mailgun

Skip this step if your domain is already set up in the US region.
  1. Go to the Domains page in the Mailgun dashboard.

Navigate to the Domains page

  1. Click Add new domain.

Open Add New Domain form

  1. Enter a subdomain (e.g., mail.yourdomain.com) and ensure the region is US.

Specify subdomain and select US region

​
2. Verify DNS settings

Mailgun provides the following DNS records:
  • 2 TXT (SPF & DKIM)
  • 2 MX
  • 1 CNAME
Update these in your DNS provider. Propagation may take up to 48 hours. Mailgun will notify you via email once verified. To verify:
  • Go to Mailgun > Sending > Domain Settings > Your Domain > DNS Records
  • Look for green checkmarks next to each record

Verify DNS setup

If CNAME is not set correctly, email click, open, and unsubscribe tracking will not work.

​
3. Set up SMTP credentials

  1. Go to Sending > Domain Settings > SMTP credentials in Mailgun.

Navigate to SMTP Credentials

  1. Click Add new SMTP user.

Add new SMTP credentials

  1. Set a login name and save the credentials.

Create SMTP user

  1. Click the copy icon to save the password securely.

Copy SMTP password

​
4. Get a Mailgun API key

  1. In the Mailgun dashboard, scroll to the bottom and click API Keys.

Navigate to API Keys

  1. Click Add new key

Add new key

  1. Name the key and click Create Key.

Create key

  1. Copy the generated API key and save it securely.

Copy API key

​
5. Configure Mailgun in OneSignal

  1. In OneSignal, go to Settings > Platforms > Email and choose Mailgun.

App setup email

  1. Select Mailgun as the provider.

App setup email

  1. Enter:

Configure provider

  1. Set default sender name and from email address.

Configure additional settings

​
6. Add OneSignal webhooks to Mailgun

Navigate to Mailgun > Sending > Webhooks > Your Domain > Webhooks and add: 
https://onesignal.com/email/hooks/mailgun

Add webhook

​
7. Change tracking protocol to HTTPS

Ensure recipients are directed to secure URLs.
  1. Go to your domain settings in Mailgun.
  2. Under Tracking > Tracking Protocol, change from HTTP to HTTPS.

Change tracking protocol

​
8. Send a test email

  1. Go to OneSignal > Messages > Email, click New Email.
  2. Add a subject, click Send Test Email, input your email, and hit Send Test Message.

Send test email

You should receive the test email shortly.

​
Troubleshooting

See our Email FAQ
Need help?Chat with our Support team or email support@onesignal.comPlease include:
  • Details of the issue you’re experiencing and steps to reproduce if available
  • Your OneSignal App ID
  • The External ID or Subscription ID if applicable
  • The URL to the message you tested in the OneSignal Dashboard if applicable
  • Any relevant logs or error messages
We’re happy to help!
Email setup complete! Next steps: