# Set Up Mailgun

> Mailgun requires a verified sending domain, a sending key, and a correctly matched API region — selecting the wrong region is the most common setup error, so confirm it before saving.

- Human page: https://mailrith.com/docs/setup-mailgun
- Category: Campaigns & Delivery
- Reading time: 10 min read

## What this guide covers
Connect Mailgun using a sending key and verified domain, with region selection and a single webhook endpoint for delivery event tracking.

## Sections
- Before You Start
- Mailrith Fields
- Mailgun Setup
- Webhooks and Region

## Visual Reference
![Mailrith email delivery connections page showing connected providers with action controls.](https://mailrith.com/docs/screenshots/email-delivery-connections.png)

The Email Delivery Connections page lists every connected provider. From here you can add a new connection, send a test email, view webhook endpoints, and assign connections to workspaces.

## Before You Start

Mailgun sends through verified domains. Before connecting Mailgun to Mailrith, confirm the domain, region, and key you plan to use.

- **A verified Mailgun sending domain:** this is the domain Mailgun has approved for sending.
- **The correct region:** Mailgun accounts can use the US or EU API region. Mailrith must match the region where the domain exists.
- **An API key:** use a key that can send messages for the selected domain.
- **A From email on the domain:** the From email needs to use the verified sending domain or otherwise be allowed by Mailgun.
- **Webhook access:** needed to forward permanent failures and spam complaints to Mailrith.

Region mismatch is the most common Mailgun setup problem. If your domain is in the EU region but Mailrith is set to US, tests and event checks can fail even when the API key is correct.

## Mailrith Fields

In Mailrith, click [Email Delivery Connections](https://mailrith.com/docs/email-delivery-connections.md) in the left sidebar, click **Create Connection**, choose **Mailgun** in **Select Email Delivery Service**, and enter these fields in **Connect Email Delivery Service**:

- **Connection name:** an internal label, such as "Mailgun EU Newsletter".
- **Sending Key:** the Mailgun key used to send messages.
- **Sending Domain:** the verified sending domain in Mailgun.
- **API Region:** US or EU, matching the Mailgun domain region.
- **From name:** the sender name subscribers see.
- **From email:** the sender address using the verified domain.
- **Workspaces:** the Mailrith workspaces allowed to use the connection.

## Mailgun Setup

1. Sign in to Mailgun and open the account that owns the sending domain.
2. Open **Sending**, then open **Domains**.
3. If the domain you want to use is already listed, open it and confirm it is verified. Also note whether the domain belongs to the US region or EU region.
4. If the domain is not listed yet, click **Add New Domain**.
5. Enter the domain you want to send from, such as **mail.example.com** or **example.com**, depending on how your team manages sending domains.
6. Choose the Mailgun region for the domain. Use EU only if your Mailgun account and sending requirements are meant to use the EU region; otherwise use US. This choice must match the **API Region** you choose in Mailrith.
7. If Mailgun asks for DKIM key length, choose the stronger 2048-bit option unless your DNS provider has a specific limitation that prevents it.
8. Click **Add Domain**.
9. Mailgun will show DNS records for the new domain. Open your DNS provider in another tab and add the records Mailgun provides. These may include records for sending authentication, tracking, receiving, SPF, DKIM, or verification.
10. Return to Mailgun and click **Verify** or wait until Mailgun checks the DNS records. Do not continue until Mailgun shows the domain as active or verified.
11. Open the account menu or profile menu in Mailgun, then open **API Security**.
12. Click **Add new key**.
13. Enter a description such as **Mailrith sending**, choose the role or permission level your Mailgun account requires for sending, and create the key.
14. Copy the private API key immediately and store it safely. Use the private sending key in Mailrith, not a public validation key.
15. Return to [Email Delivery Connections](https://mailrith.com/docs/email-delivery-connections.md) in Mailrith, click **Create Connection**, choose **Mailgun**, and enter the sending key, sending domain, API region, From name, From email, and workspace assignments.
16. Click **Save**, then use **Send Test Email** from the connection row.

If the test fails, check the domain spelling, region, API key type, From email, DNS verification status, and whether the Mailgun account or domain has sending restrictions.

## Webhooks and Region

Mailgun can forward delivery events to Mailrith through the unified delivery-event webhook. Mailrith uses permanent failures as bounces and complaint events as spam complaints.

1. In Mailrith, click **Email Delivery Connections**, click **Webhooks** on the Mailgun connection, and copy the delivery-event webhook URL.
2. In Mailgun, open **Sending**, then open the same sending domain used by the Mailrith connection.
3. Open the domain's webhook settings.
4. Add the Mailrith URL for permanent failure or bounce-related events.
5. Add the same Mailrith URL for complaint or spam complaint events.
6. Save the webhook settings.
7. After the next test or small send, check Mailgun's webhook delivery activity if Mailrith does not show the event you expected.

Keep the webhook attached to the same domain and region as the Mailrith connection. Events from a different Mailgun domain will not represent the messages this connection sent.

## Related Guides
- [Email Delivery Connections](https://mailrith.com/docs/email-delivery-connections.md): Mailrith is provider-agnostic — you connect your own email delivery service and Mailrith handles campaign logic, subscriber targeting, and engagement tracking on top of it.
- [Broadcasts](https://mailrith.com/docs/broadcasts.md): Broadcasts are for newsletters, product launches, announcements, and any message that goes out once to selected subscribers — compose, target, test, and send or schedule from a single workflow.
- [Sequences](https://mailrith.com/docs/sequences.md): Sequences send a series of emails over time as subscribers progress through the steps — ideal for onboarding, nurture campaigns, and educational content that should unfold over days or weeks.