Mailgun Mass Mailing Integration

Odoo's default SMTP struggles with bulk volume and frequently lands in spam. Mailgun handles the deliverability and sending infrastructure, so large campaigns actually reach inboxes and reliable delivery and engagement data comes back into Odoo. Instead of guessing whether a campaign was received, the client sees the actual result of each message, and addresses that permanently fail or complain are suppressed automatically to protect the sending reputation of the domain.

The Mailgun account, the sending domain and the domain verification are configured directly in Mailgun and are not managed from Odoo. Verification requires the DNS records provided by Mailgun to be published on the domain, which normally includes the SPF and DKIM TXT records for authentication, the MX records when inbound routing is used, and the CNAME record used for open and click tracking. Open tracking, click tracking and the unsubscribe handling are enabled on the domain in the Mailgun dashboard. Once the domain shows as verified, the SMTP credentials and the private API key generated by Mailgun are used in Odoo.

In Odoo, only the outgoing mail server is added. A new outgoing mail server is created with the Mailgun SMTP host and port, the Mailgun SMTP username, which is normally the postmaster address of the verified domain, and the corresponding SMTP password. TLS is used for the connection, and the server is tested with the standard connection test before it is used. The from address on the mass mailing must belong to the verified domain, otherwise Mailgun rejects the message.

Alongside the mail server, the private API key, the sending domain and the region are stored so the integration can submit campaigns through the Mailgun API and read the account data. The region matters because Mailgun maintains separate US and EU endpoints and an account created in one region cannot be reached through the other. The webhook signing key is stored as well and is used to verify that incoming event notifications actually originate from Mailgun.

A mass mailing is prepared in the usual way by selecting the mailing list or the recipient domain and designing the email body. When the mailing is sent, Odoo splits the recipients into batches and submits each batch through the Mailgun API using recipient variables, so every contact receives an individual message with personalised values rather than a shared distribution message.

For each recipient, Mailgun returns a message ID which is stored on the mailing trace created in Odoo. This message ID is the key used to reconcile later events with the correct recipient. The batch size respects the rate limits of the Mailgun plan, and any batch rejected by the API is logged with the error returned by Mailgun, so the cause, such as an invalid address or an unverified sender, is visible directly from the mailing.

Odoo exposes a webhook endpoint which is registered in Mailgun for the events required by the client, typically delivered, opened, clicked, permanent failure, temporary failure, complained and unsubscribed. Each incoming request is validated using the signing key together with the timestamp and token supplied by Mailgun, and requests that fail the signature check are rejected.

When a valid event is received, the message ID in the payload is used to locate the mailing trace and the state of that trace is updated. Delivered events mark the trace as delivered, open and click events record the interaction with its timestamp, and failure events record the reason and the response returned by the receiving server. Because events are processed as they arrive, the statistics on the mailing reflect the real delivery result rather than an estimate.

Permanent failures and spam complaints are treated as final. When such an event is received, the recipient address is added to the Odoo blacklist automatically and the reason reported by Mailgun is stored on the entry, so the client can see why an address was excluded. Unsubscribe events received from the Mailgun unsubscribe link are handled in the same way and are reflected on the mailing list subscription of the contact.

Temporary failures do not blacklist the address immediately. The failure is recorded on the trace and the bounce counter of the partner is increased, which allows repeatedly failing addresses to be identified and cleaned without removing a contact after a single transient error such as a full mailbox.

In addition to the webhooks, a scheduled action periodically reads the Mailgun suppression lists for bounces, complaints and unsubscribes and compares them with the Odoo blacklist. This keeps both systems aligned even if a webhook notification was missed during a temporary outage, and it also imports addresses that were suppressed directly in Mailgun or by another application sending through the same domain.

The mass mailing form shows the counters built from the trace records, including the number of messages sent, delivered, opened, clicked, bounced and marked as spam, together with the corresponding rates. Since these values are derived from the events reported by Mailgun, the reporting in Odoo matches the reporting in the Mailgun dashboard and can be used directly to evaluate a campaign.