# mod\_mailgun

Source: https://zotonic.com/docs/3098/mod_mailgun

URI: https://zotonic.com/id/3098

Language: en



Relay outgoing email through the Mailgun HTTP API and receive delivery and engagement events through a signed webhook. Requires `mod_email_status`.

Setup and configuration
-----------------------

Enable `mod_mailgun` on the site. Configure its per-site `m_config` values in the Mailgun panel under **System > Mail settings**. Saving these settings requires an administrator with configuration-edit permission:

| Key                          | Meaning                                                                          |
| ---------------------------- | -------------------------------------------------------------------------------- |
| `mod_mailgun.domain`         | Sending domain configured in Mailgun.                                            |
| `mod_mailgun.api_url`        | Full API base URL including the domain, without a trailing slash. Defaults to `https://api.mailgun.net/v3/` followed by `domain`. |
| `mod_mailgun.api_key`        | API key used for HTTP Basic authentication with username `api`.                  |
| `mod_mailgun.webhook_secret` | Signing key used to verify incoming webhook requests.                            |

For example, a domain of `mg.example.com` uses the default API base URL `https://api.mailgun.net/v3/mg.example.com`. The administration panel also provides a regional endpoint example. Configure both the sending domain (or a complete API URL) and the API key before sending mail.

Outgoing mail and address status
--------------------------------

The `email_send_encoded` observer posts the encoded MIME message to `<api_url>/messages.mime`. This path uses the HTTP API and does not require SMTP relay settings. If both `api_url` and `api_key` are empty, the observer returns `undefined`, leaving delivery to other handlers. Setting either value activates the API path; this presence check does not verify the credentials or service availability. A domain alone does not activate it.

An HTTP 200 response means Mailgun accepted the message. Other HTTP responses are returned as temporary failures; delivery to the recipient is reported separately by the webhook.

Manual `email_status` changes synchronize the address with Mailgun's bounce list: blocking adds it and clearing removes it. Non-manual status changes are ignored. The exported `mailgun_block/2` and `mailgun_clear/2` helpers return the HTTP client result, or `ok` when the API is unconfigured. These Erlang helpers do not perform an ACL check; callers must authorize manual changes.

Webhook
-------

Configure Mailgun to post events to the site's absolute `/mailgun-webhook` URL and set `webhook_secret` to the matching signing key. The dispatch name is `mailgun_webhook`; in templates use `{% url mailgun_webhook absolute_url %}`. The endpoint accepts JSON POST requests authenticated by an HMAC signature, without requiring a Zotonic user session.

Delivered messages are reported as `relayed`, opened and clicked events mark the address as read, and failed events update delivery status. Spam complaints emit a final `email_failed` notification. Unsubscribe events are logged and ignored. See `controller_mailgun_webhook` for the event mapping.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/3098?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/3098?language=en>)