> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mailgun Setup

> Step-by-step guide to setting up Mailgun with OneSignal for sending email messages. Includes DNS verification, SMTP credential setup, API key generation, and OneSignal integration instructions.

<Warning>
  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](./email-setup) instead.
</Warning>

## Requirements

* [Mailgun Account](https://www.mailgun.com)
* Mailgun **US** API (EU region is not supported)
* [OneSignal Account](https://onesignal.com)
* A domain you own and access to its DNS provider

***

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

<Frame caption="Navigate to the Domains page">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/6e14df8-01_-_Navigate_to_sending_domains.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=542d06f8870b8e98cdb276d475cb2d99" width="1328" height="1124" data-path="images/docs/6e14df8-01_-_Navigate_to_sending_domains.png" />
</Frame>

2. Click **Add new domain**.

<Frame caption="Open Add New Domain form">
  <img src="https://mintcdn.com/onesignal/_KaXe4GQkxsEfa17/images/docs/403bd98-01.2_-_Click_Add_new_domain_button.png?fit=max&auto=format&n=_KaXe4GQkxsEfa17&q=85&s=d0d94e8e010730d7f80fb782f0bf3557" width="1328" height="1124" data-path="images/docs/403bd98-01.2_-_Click_Add_new_domain_button.png" />
</Frame>

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

<Frame caption="Specify subdomain and select US region">
  <img src="https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/ad8dca5-01.3_-_Add_new_domain.png?fit=max&auto=format&n=RWtLFPeffHrC81wI&q=85&s=fa477b2191c6b916fb4e16a9bf457161" width="1328" height="1124" data-path="images/docs/ad8dca5-01.3_-_Add_new_domain.png" />
</Frame>

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

<Frame caption="Verify DNS setup">
  <img src="https://mintcdn.com/onesignal/Z6xkXGfmy814If53/images/docs/ddbf617-01.5_-_Verified_DNS_settings.png?fit=max&auto=format&n=Z6xkXGfmy814If53&q=85&s=26bd8596b9ac4b96089b8225c00fa94d" width="1328" height="1124" data-path="images/docs/ddbf617-01.5_-_Verified_DNS_settings.png" />
</Frame>

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

***

### 3. Set up SMTP credentials

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

<Frame caption="Navigate to SMTP Credentials">
  <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/963d676-02_-_Add_SMTP_creds.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=2cb892039a5cfee55aa25da01ae438e1" width="1328" height="1124" data-path="images/docs/963d676-02_-_Add_SMTP_creds.png" />
</Frame>

2. Click **Add new SMTP user**.

<Frame caption="Add new SMTP credentials">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b2108d4-02.1_-_Click_Add_new_SMTP_user.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=79537c0dae456ed4320ad09647db4d87" width="1328" height="1124" data-path="images/docs/b2108d4-02.1_-_Click_Add_new_SMTP_user.png" />
</Frame>

3. Set a login name and save the credentials.

<Frame caption="Create SMTP user">
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/be7540c-03_-_New_SMTP_creds.png?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=53a10a727d7dbb9a8234332e50e3308e" width="1328" height="1124" data-path="images/docs/be7540c-03_-_New_SMTP_creds.png" />
</Frame>

4. Click the **copy** icon to save the password securely.

<Frame caption="Copy SMTP password">
  <img src="https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/ab32f9b-03.1_-_Copy_SMTP_user_pass.png?fit=max&auto=format&n=RWtLFPeffHrC81wI&q=85&s=51aeb4db620490e077f63465619e2711" width="1328" height="1124" data-path="images/docs/ab32f9b-03.1_-_Copy_SMTP_user_pass.png" />
</Frame>

### 4. Get a Mailgun API key

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

<Frame caption="Navigate to API Keys">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/430314e-42fc46d-step-1-50.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=f80af7cfcfe4be2d94418b6f15448097" width="1616" height="1365" data-path="images/docs/430314e-42fc46d-step-1-50.png" />
</Frame>

2. Click **Add new key**

<Frame caption="Add new key">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/6390d56-93a49a5-step-2-50.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=45c91e47914b90b577388c8c26fc9538" width="1616" height="1365" data-path="images/docs/6390d56-93a49a5-step-2-50.png" />
</Frame>

3. Name the key and click **Create Key**.

<Frame caption="Create key">
  <img src="https://mintcdn.com/onesignal/6v_cVPknFpo5qSVB/images/docs/09dd33b-6faf199-step-3-50.png?fit=max&auto=format&n=6v_cVPknFpo5qSVB&q=85&s=87af7bad8fc8363e916e5673779a65ea" width="1616" height="1365" data-path="images/docs/09dd33b-6faf199-step-3-50.png" />
</Frame>

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

<Frame caption="Copy API key">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/1350337-cb5aeba-step-4-50.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=d4f1a03d0287b8c3169bda289b839cfa" width="1616" height="1365" data-path="images/docs/1350337-cb5aeba-step-4-50.png" />
</Frame>

***

### 5. Configure Mailgun in OneSignal

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

<Frame caption="App setup email">
  <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/9341a6c-01_-_App_setup_email.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=2c645ab6c1107ed5bb1122aacff78d17" width="1328" height="1124" data-path="images/docs/9341a6c-01_-_App_setup_email.png" />
</Frame>

2. Select **Mailgun** as the provider.

<Frame caption="App setup email">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/4a2a57c-02_-_App_Setup_Email_Mailgun.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=d7bcb86f6bc0d15df9b49a147d132959" width="1328" height="1124" data-path="images/docs/4a2a57c-02_-_App_Setup_Email_Mailgun.png" />
</Frame>

3. Enter:

* The domain from [Step 1](#1-add-a-new-domain-in-mailgun)
* SMTP credentials from [Step 3](#3-set-up-smtp-credentials)
* API key from [Step 4](#4-get-a-mailgun-api-key)

<Frame caption="Configure provider">
  <img src="https://mintcdn.com/onesignal/6v_cVPknFpo5qSVB/images/docs/07c6b2f-03_-_Configure_provider.png?fit=max&auto=format&n=6v_cVPknFpo5qSVB&q=85&s=a3cb35435c5496d52c08135bed6c99d0" width="1328" height="1124" data-path="images/docs/07c6b2f-03_-_Configure_provider.png" />
</Frame>

4. Set default sender name and `from` email address.

<Frame caption="Configure additional settings">
  <img src="https://mintcdn.com/onesignal/6tscVAtiSqz353kV/images/docs/9e6af63-04_-_Configure_additional_settings.png?fit=max&auto=format&n=6tscVAtiSqz353kV&q=85&s=7c34b6e400662d67808226872626e1de" width="1328" height="1124" data-path="images/docs/9e6af63-04_-_Configure_additional_settings.png" />
</Frame>

### 6. Add OneSignal webhooks to Mailgun

Navigate to **Mailgun > Sending > Webhooks > Your Domain > Webhooks** and add:

```
https://onesignal.com/email/hooks/mailgun
```

<Frame caption="Add webhook">
  <img src="https://mintcdn.com/onesignal/Z6xkXGfmy814If53/images/docs/d81f4cc-Screenshot_2023-01-25_at_3.48.04_PM.png?fit=max&auto=format&n=Z6xkXGfmy814If53&q=85&s=30721d7d06a88cae8fc244577f767a89" width="1534" height="1212" data-path="images/docs/d81f4cc-Screenshot_2023-01-25_at_3.48.04_PM.png" />
</Frame>

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

<Frame caption="Change tracking protocol">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/e79e542-Screenshot_2023-01-25_at_3.52.26_PM.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=bfb73b54c1f4a81ae480cdfda0413966" width="2228" height="632" data-path="images/docs/e79e542-Screenshot_2023-01-25_at_3.52.26_PM.png" />
</Frame>

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

<Frame caption="Send test email">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/46aaab5-Screen_Shot_2021-11-18_at_6.00.46_PM.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=5d3969be38e8e9caea691fdb094a54c7" width="1806" height="598" data-path="images/docs/46aaab5-Screen_Shot_2021-11-18_at_6.00.46_PM.png" />
</Frame>

You should receive the test email shortly.

***

## Troubleshooting

See our [Email FAQ](./email-troubleshooting)

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please 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](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>

***

<Check>
  Email setup complete!
  **Next steps:**

  * Return to the [Email Setup guide](./email-setup) to explore OneSignal Email capabilities.
</Check>

***