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