# Mailgun

> Page: https://docs.plotwork.dev/connectors/mailgun. Index of every page: https://docs.plotwork.dev/llms.txt

Send your organisation's email through your own Mailgun account, in its US or its EU region, from an address on your domain. Plotwork takes the Mailgun domain from the From address, so the two must be the same.

## TL;DR

| Question | Answer |
|---|---|
| What do I need? | A Mailgun account with your sending domain added and verified. |
| Which key? | A sending key for that domain, which can only send. |
| Which region? | The one your domain is in: US or EU. Choose it on the Connectors tab; US is the default. |
| Which domain? | The part of the From address after the `@`. It must be the domain you added at Mailgun and the domain you verified in Plotwork. |
| Where does Plotwork send? | `https://api.mailgun.net/v3/<domain>/messages` in the US, or `https://api.eu.mailgun.net/v3/<domain>/messages` in the EU, with the key as the password of the user `api`. |

## Choose the domain first

Mailgun is often set up on a subdomain, such as `mg.acme.com`. Plotwork sends to the Mailgun domain named by the From address, so:

| Mailgun domain | From address | Domain to verify in Plotwork |
|---|---|---|
| `acme.com` | `plotwork@acme.com` | `acme.com` |
| `mg.acme.com` | `plotwork@mg.acme.com` | `mg.acme.com` |

Plotwork matches the domain exactly, so a Mailgun subdomain must be verified in Plotwork as itself.

## 1. Verify the domain at Mailgun

1. In Mailgun, choose the region, US or EU, and add the sending domain in it. A domain belongs to one region.
2. Publish the DNS records Mailgun shows: the SPF and DKIM records, and the tracking and MX records if you use them.
3. Wait until Mailgun shows the domain as verified.

## 2. Make a sending key

1. In Mailgun, open the sending domain's settings and create a sending API key for it. A sending key works for that one domain and can only send messages.
2. Give it a name that says what it is for, such as `Plotwork`.
3. Copy the key. Mailgun shows it once.

An account API key also works, but it can do everything in the account. Prefer the sending key.

## 3. Fill in the connector

| Field in Plotwork | What to enter |
|---|---|
| Provider | Mailgun |
| API token | The sending key from step 2 |
| From address | An address on the Mailgun domain, such as `plotwork@mg.acme.com` |
| Region | US or EU, where the domain is |

Then send a test from the Connectors tab.

## If the test fails

| Answer | Likely cause |
|---|---|
| The provider did not accept the token | The key was revoked or mistyped, or it is a sending key for another domain. |
| The provider refused the email | The From address is not on the Mailgun domain, or the domain is not verified there yet. |
| Either of the two above | The region on the Connectors tab is not the region the domain is in. |
| The provider could not be reached | Mailgun is down or slow. Try again later. |

## See also

| Page | Why |
|---|---|
| [Email through your own domain](https://docs.plotwork.dev/connectors/email.md) | Every step, including verifying the domain in Plotwork |
| [Connectors](https://docs.plotwork.dev/connectors/overview.md) | Which email goes through the connector |
| [How your token is protected](https://docs.plotwork.dev/connectors/security.md) | How Plotwork keeps the key |
| [Mailgun documentation](https://documentation.mailgun.com) | Mailgun's own guides to domains, regions and API keys |