Set Up Mailgun

Before You Start

Mailgun sends email only from verified domains. Before you connect Mailgun to Mailrith, confirm which Mailgun domain, API region, and API key you will use.

• A verified Mailgun sending domain: use a domain that Mailgun has approved for sending email.
• The correct region: Mailgun accounts can use the US or EU API region. Choose the same region in Mailrith that Mailgun uses for the sending domain.
• An API key: use a Mailgun key that has permission to send messages from the selected domain.
• A From email on the sending domain: use a From email whose domain matches the verified Mailgun sending domain you enter in Mailrith.
• Webhook access: use webhook access so Mailgun can send permanent failures and spam complaints to Mailrith.

A region mismatch is the most common Mailgun setup problem. If your domain is in the EU region but the Mailrith connection uses US, test emails and event checks can fail even when the API key is valid.

Mailrith Fields

In Mailrith, click Email Delivery Connections in the left sidebar, click Create Connection, choose Mailgun in Select Email Delivery Service, and enter these fields in Connect Email Delivery Service:

• Connection name: enter an internal label, such as "Mailgun EU Newsletter".
• Sending Key: enter the Mailgun API key that sends messages.
• Sending Domain: enter the verified sending domain from Mailgun.
• API Region: choose US or EU to match the Mailgun region for the sending domain.
• From name: enter the sender name subscribers will see.
• From email: enter a sender address that uses the same verified domain as the Sending Domain field.
• Workspaces: choose the Mailrith workspaces that can use this connection.

Mailgun Setup

1. Sign in to Mailgun and open the account that owns the sending domain.
2. Open Sending, then open Domains.
3. If the sending domain is already listed, open your domain and confirm that Mailgun shows it as verified. Also check whether Mailgun lists it in the US region or the EU region.
4. If the sending domain is not listed yet, click Add New Domain.
5. Enter your sending domain, such as mail.example.com or example.com, based on how your team manages sending domains.
6. Choose the Mailgun region for your domain. Choose EU only when your Mailgun account and sending requirements use the EU region; otherwise choose US. The region you choose here must match the API Region you choose in Mailrith.
7. If Mailgun asks for DKIM key length, choose the stronger 2048-bit option unless your DNS provider cannot support it.
8. Click Add Domain.
9. After Mailgun shows DNS records for the new domain, open your DNS provider in another tab and add each record Mailgun provides. These records may include sending authentication, tracking, receiving, SPF, DKIM, or verification records.
10. Return to Mailgun and click Verify, or wait for Mailgun to check the DNS records. Continue only after Mailgun shows your domain as active or verified.
11. Open the account menu or profile menu in Mailgun, then open API Security.
12. Click Add new key.
13. Enter a description such as Mailrith sending, choose the role or permission level your Mailgun account requires for sending, and create the key.
14. Copy the private API key immediately and store it safely. In Mailrith, use the private sending key instead of a public validation key.
15. Return to Email Delivery Connections in Mailrith, click Create Connection, choose Mailgun, and enter the sending key, sending domain, API region, From name, From email, and workspace assignments.
16. Click Save, then use Send Test Email from the connection row.

If the connection cannot be saved or the test email fails, check the spelling of your domain, API region, API key type, From email, DNS verification status, and Mailgun sending restrictions against the Mailgun domain you connected. The From email domain must match the Mailgun sending domain in Mailrith.

Webhooks and Region

Mailgun can send delivery events to Mailrith through the unified delivery-event webhook. Mailrith records permanent failures as bounces and records complaint events as spam complaints.

1. In Mailrith, click Email Delivery Connections, click Webhooks on the Mailgun connection, and copy the delivery-event webhook URL.
2. In Mailgun, open Sending, then open the same sending domain used by the Mailrith connection.
3. Open your domain's webhook settings.
4. Add the Mailrith URL for permanent failure or bounce-related events.
5. Add the same Mailrith URL for complaint or spam complaint events.
6. Save the webhook settings.
7. After the next test or small send, check Mailgun's webhook delivery activity if Mailrith does not show the expected event. A successful check shows Mailgun delivered the event to the Mailrith webhook URL.

Keep the webhook attached to the same domain and region as the Mailrith connection. Events from another Mailgun domain do not represent messages sent through this connection.