Skip to main content
Mailgun is a transactional email service that integrates with the HoopAI Platform for high-deliverability email sending. This guide covers connecting Mailgun, configuring DNS, setting up reply routing, and understanding error codes.

​
Connecting Mailgun to your DNS manager

1

Create a Mailgun account

Sign up at mailgun.com and create a sending domain (e.g., mail.yourdomain.com).
2

Get your DNS records from Mailgun

In your Mailgun dashboard, navigate to Sending > Domains and select your domain. Mailgun will show you the DNS records to add.
3

Add DNS records to your registrar

Log in to your DNS manager (e.g., GoDaddy, Cloudflare, Namecheap) and add the following records:
TypeNameValue
TXTmail.yourdomain.comMailgun SPF record
TXTk1._domainkey.mail.yourdomain.comMailgun DKIM record
CNAMEemail.mail.yourdomain.commailgun.org
MXmail.yourdomain.commxa.mailgun.org (priority 10)
MXmail.yourdomain.commxb.mailgun.org (priority 10)
4

Verify in Mailgun

Return to your Mailgun domain settings and click Verify DNS Settings. DNS propagation may take up to 48 hours.
5

Connect Mailgun in the HoopAI Platform

Go to Settings > Email Services, select Mailgun, and enter your Mailgun API key and domain.

​
Setting up replies in Mailgun

When contacts reply to emails sent through Mailgun, you need to configure routes in Mailgun so those replies are delivered back into the platform.
1

Open Mailgun routes

In your Mailgun dashboard, navigate to Receive > Routes.
2

Create a new route

Click Create Route and set up a filter expression to match inbound emails to your sending domain.
3

Set the action

Set the action to Forward and enter the inbound webhook URL provided by the HoopAI Platform.
4

Save the route

Save and test the route by sending a test reply to an email sent through Mailgun.
The inbound webhook URL for Mailgun routes is available in Settings > Email Services > Mailgun in the HoopAI Platform.

​
Unsubscribe settings in Mailgun

Mailgun automatically adds an unsubscribe link to emails when the feature is enabled. You can customize unsubscribe behavior in both Mailgun and the HoopAI Platform.

​
To change unsubscribe settings in Mailgun

1

Go to sending settings

In your Mailgun dashboard, navigate to Sending > Domain Settings and select your domain.
2

Scroll to unsubscribe settings

Find the Unsubscribe Tracking section and toggle it on or off.
3

Customize the unsubscribe page

Optionally customize the unsubscribe page URL to redirect contacts to your own branded page after unsubscribing.
Disabling Mailgun’s unsubscribe tracking does not disable the unsubscribe link added by the HoopAI Platform. Both are required for CAN-SPAM and GDPR compliance.

​
Mailgun suppressions and DND

When a contact unsubscribes, bounces, or marks an email as spam through Mailgun, the HoopAI Platform automatically updates the contact’s Do Not Disturb (DND) settings for email:
Mailgun eventDND behavior
Permanent bounceEmail DND enabled automatically
Spam complaintEmail DND enabled — cannot be removed by user
UnsubscribeEmail DND enabled
Soft bounce (30003, 30005, 30006)Temporary DND
To remove a contact from Mailgun’s suppression list: delete the address from the Mailgun suppressions list, validate the email, and then re-enable it in the contact record.

​
Error codes library — Mailgun

These are soft bounces that Mailgun will retry automatically. Common codes include 421 (service temporarily unavailable) and 450 (mailbox unavailable).
These are hard bounces. The address is invalid or the receiving server has permanently rejected the message. Remove these addresses from your list. Common codes include 550 (user unknown), 551 (user not local), and 552 (mailbox full — permanent).
These codes indicate the receiving carrier is temporarily unable to deliver the message (SMS context, but also seen in email relay failures). These result in temporary DND.
Permanent delivery failure — the message was blocked by the carrier or recipient. Results in permanent DND.
Regularly export and review your Mailgun suppression list to identify problematic addresses and keep your sending reputation healthy.
Last modified on March 4, 2026