Mailgun

Connect Mailgun to GoodPostal for powerful API-based email sending with HMAC-SHA256 webhook verification.

Prerequisites

• A Mailgun account
• A verified sending domain in Mailgun
• Your API key and domain name

Setup Steps

1. 1

   Get your API key

   In the Mailgun dashboard, go to Settings > API Keys. Copy your private API key (starts with key-).
2. 2

   Note your sending domain

   Go to Sending > Domains and note your verified sending domain (e.g., mg.yourdomain.com).
3. 3

   Add the provider in GoodPostal

   Go to Configure > Email Providers, click "Add Provider", select Mailgun, and enter your API key and domain.
4. 4

   Leave webhook setup switched on

   Set up webhooks automatically is checked by default. Leave it checked and GoodPostal configures your Mailgun webhooks for you, as described below.

API Configuration

API Key: key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Domain: mg.yourdomain.com
Region: us or eu (must match your Mailgun account region)

Webhook Setup

You do not add Mailgun webhooks by hand. GoodPostal registers them on your sending domain over the Mailgun API.

1. 1

   Leave automatic setup checked

   When you add Mailgun, the Set up webhooks automatically checkbox is already on. Leave it on and save the connection.
2. 2

   GoodPostal configures Mailgun for you

   GoodPostal registers the seven webhook events listed below on your sending domain and reads your webhook signing key from Mailgun so it can verify incoming events. There is nothing to copy or paste. If an event already points at a webhook of your own, GoodPostal leaves yours alone.
3. 3

   Re-run it whenever you need to

   Open Configure > Email Providers, select your Mailgun connection, and use Re-configure webhooks on the Webhook & Tracking card. Use this after you rotate an API key or if setup did not finish the first time.

Events GoodPostal Tracks

• Delivered Messages
• Opened Messages
• Clicked Links
• Permanent Failures (bounces)
• Temporary Failures
• Complained (spam reports)
• Unsubscribes

Signature Verification

Mailgun signs webhook payloads using HMAC-SHA256 with your webhook signing key. Each webhook request includes:

timestamp: Unix timestamp of the event
token: Random string for uniqueness
signature: HMAC-SHA256(timestamp + token, signing_key)

GoodPostal verifies the signature automatically. Events that fail verification are rejected with a 401 response.

Troubleshooting

• Authentication failed - Verify your API key and, on an EU account, check that the Region field says eu in lowercase
• Domain not found - Ensure the domain is verified and active in Mailgun
• Webhook signature mismatch - Use Re-configure webhooks on the provider page so GoodPostal re-reads your current signing key from Mailgun

See also: Webhook Configuration Guide