Skip to main content

Mailgun

Prerequisites​

Prerequisites

Before setting up the Mailgun integration, ensure you have:

Create a Mailgun API Key​

Mailgun uses API keys for authentication. You'll need the API key from your Mailgun domain.

  1. Sign in to your Mailgun account
  2. Navigate to Sending > Domain Settings or go to your domain's settings
  3. In the Domain Information section, you'll find your API Key
  4. Click Reveal to show the API key, then copy it
  5. Alternatively, you can find your API key in Settings > API Keys
warning

Make sure to securely store your API key. You can regenerate it if needed, but you'll need to update it in DashX if you do.

Mailgun Domains

Mailgun organizes sending by domains. Each domain has its own API key. Make sure you're using the API key for the domain you want to send from.

Verify your domain​

Domain verification in Mailgun allows you to send emails from your domain and improves deliverability.

  1. In the Mailgun dashboard, navigate to Sending > Domains
  2. Click Add New Domain
  3. Enter your domain name (e.g., yourdomainname.com) and click Add Domain
  4. Choose your domain type:
    • Send Only: For sending emails only
    • Send & Receive: For both sending and receiving emails
  5. Select your DNS provider from the dropdown (or select Other if your provider isn't listed)
  6. Mailgun will generate DNS records that need to be added to your domain
  7. You'll see several DNS records:
    • TXT record for domain verification: This verifies domain ownership
    • TXT record for SPF: This authorizes Mailgun to send emails
    • CNAME records for DKIM: These enable DKIM signing (typically 2 records)
  8. Add these records to your domain's DNS settings:
    • Copy the Host and Value from the Mailgun console
    • Add them as the corresponding record type (TXT or CNAME) in your DNS provider
    • The exact process varies depending on your DNS provider (Route 53, Cloudflare, GoDaddy, etc.)
  9. After adding all records, return to the Mailgun console
  10. Click Verify DNS Settings or wait for automatic verification
  11. Verification may take a few minutes to several hours depending on DNS propagation. The status will change from Unverified to Verified once Mailgun detects the records
tip

DNS propagation can take up to 48 hours, but typically completes within a few hours. You can check your DNS records using tools like dig or online DNS checkers to verify they're properly configured.

Set up SPF​

Sender Policy Framework (SPF) helps prevent email spoofing by specifying which mail servers are authorized to send emails on behalf of your domain.

  1. Mailgun automatically includes SPF configuration in the domain verification process
  2. The SPF record will be included in the DNS records provided during domain verification
  3. If you need to add SPF manually or modify an existing SPF record:
    • In your domain's DNS settings, add or modify a TXT record with the following:
      • Name/Host: @ or yourdomainname.com (depending on your DNS provider)
      • Type: TXT
      • Value: v=spf1 include:mailgun.org ~all
  4. The include:mailgun.org part authorizes Mailgun to send emails on behalf of your domain
  5. The ~all means "soft fail" - emails from unauthorized servers will be marked but not rejected
note

If you already have an SPF record, you should modify it to include include:mailgun.org rather than creating a duplicate. Multiple SPF records are not allowed. For example, if you have v=spf1 include:_spf.google.com ~all, change it to v=spf1 include:_spf.google.com include:mailgun.org ~all.

Set up DKIM​

DomainKeys Identified Mail (DKIM) adds a digital signature to your emails, allowing recipients to verify that emails were sent and authorized by the owner of the domain.

  1. Mailgun automatically includes DKIM configuration in the domain verification process
  2. The DKIM CNAME records will be provided during domain verification (typically 2 records)
  3. Add the DKIM CNAME records to your domain's DNS settings:
    • Each record will have a name like [selector]._domainkey.yourdomainname.com
    • The values will be CNAME records pointing to Mailgun's DKIM endpoints
  4. After adding the records, Mailgun will automatically detect them and enable DKIM signing
  5. You can verify DKIM status in the Domain Settings section of your Mailgun dashboard
info

DKIM signing status will show as Verified in the Mailgun dashboard once all CNAME records are properly configured and detected. This typically takes a few minutes to a few hours after adding the DNS records.

Set up DMARC​

Domain-based Message Authentication, Reporting, and Conformance (DMARC) builds on SPF and DKIM to provide instructions on how to handle emails that fail SPF or DKIM checks.

  1. In your domain's DNS settings, add a TXT record with the following:
    • Name/Host: _dmarc.yourdomainname.com
    • Type: TXT
    • Value: v=DMARC1; p=none; rua=mailto:dmarc-reports@yourdomainname.com
  2. Replace dmarc-reports@yourdomainname.com with an email address where you want to receive DMARC aggregate reports
  3. The p=none policy means "no action" - this is recommended for initial setup to monitor without affecting email delivery
  4. As you gain confidence, you can change the policy to:
    • p=quarantine - Move failing emails to spam/junk folder
    • p=reject - Reject emails that fail DMARC checks
tip

Start with p=none to monitor your email authentication without impacting delivery. Review DMARC reports regularly and gradually tighten the policy as you verify that your legitimate emails are passing SPF and DKIM checks.

Set up BIMI (Optional)​

Brand Indicators for Message Identification (BIMI) allows you to display your brand logo in supported email clients, enhancing brand recognition and trust.

  1. Prepare your logo:
    • Create an SVG version of your brand logo
    • The logo must meet BIMI specifications:
      • SVG format
      • Square aspect ratio (1:1)
      • Maximum file size: 32KB
      • Must be publicly accessible via HTTPS
  2. Host the logo:
    • Upload the SVG file to a publicly accessible HTTPS URL (e.g., https://yourdomainname.com/logo.svg)
    • Ensure the server has a valid SSL certificate
  3. Add BIMI record to DNS:
    • In your domain's DNS settings, add a TXT record with the following:
      • Name/Host: default._bimi.yourdomainname.com
      • Type: TXT
      • Value: v=BIMI1; l=https://yourdomainname.com/logo.svg
    • Replace the URL with the actual location of your hosted logo
note

BIMI is currently supported by a limited number of email clients (including Gmail for verified senders). Even if not all clients support it, setting up BIMI doesn't negatively impact email delivery and prepares you for broader adoption.

Configure webhook events (Optional)​

Mailgun can send webhook events for email delivery, bounces, opens, clicks, and other events. This is useful for tracking email performance in DashX.

  1. In the Mailgun dashboard, navigate to Sending > Webhooks
  2. Click Add Webhook
  3. Configure the webhook:
    • Webhook URL: Enter your DashX webhook URL
      • To get the webhook URL: Log in to your DashX workspace, navigate to the Integrations section, find your Mailgun integration, and copy the webhook URL
    • HTTP Authorization: Optional, for additional security
    • Events: Select the events you want to receive:
      • delivered: Email was successfully delivered
      • failed: Email delivery failed
      • opened: Email was opened
      • clicked: Link in email was clicked
      • unsubscribed: Recipient unsubscribed
      • complained: Recipient marked email as spam
      • bounced: Email was bounced
      • dropped: Email was dropped
  4. Click Save Webhook
info

Webhook events are optional but recommended for tracking email performance and engagement metrics in DashX. Without webhooks, you'll still be able to send emails, but you won't receive delivery status updates.

Set up receiving email (Optional)​

If you want to receive emails through Mailgun, follow these additional steps:

Set up MX Records​

  1. In the Mailgun dashboard, navigate to Receiving > Routes
  2. Mailgun will provide MX records that need to be added to your domain
  3. In your domain's DNS settings, add MX records:
    • Name/Host: @ or yourdomainname.com (or a subdomain like mg.yourdomainname.com)
    • Type: MX
    • Priority: 10
    • Value: mxa.mailgun.org (Priority 10)
    • Value: mxb.mailgun.org (Priority 10)
  4. After adding the MX records, Mailgun will be able to receive emails for your domain
info

If you're already using another mail provider (like Google Workspace, Microsoft 365) for your root domain, consider using a subdomain like mg.yourdomainname.com for Mailgun email receiving to avoid conflicts.

Configure Routes​

Routes define how Mailgun processes incoming emails.

  1. In the Mailgun dashboard, navigate to Receiving > Routes
  2. Click Create Route
  3. Configure the route:
    • Expression: Define which emails this route matches (e.g., match_recipient(".*@yourdomainname.com"))
    • Actions: Define what to do with matching emails:
      • Forward to URL: Forward to your DashX webhook URL
      • Store: Store in Mailgun
      • Stop: Stop processing
  4. Click Create Route
tip

Routes allow you to process incoming emails and forward them to DashX via webhooks. This is useful for handling support emails, notifications, and other inbound email scenarios.

Next steps​

After completing the setup:

  1. Verify your email authentication setup: Use free online tools to verify that your SPF, DKIM, and DMARC records are properly configured:

    These tools will help you verify that all DNS records are correctly configured and that your emails will pass authentication checks.

  2. Test email sending: Test sending emails through the DashX console:

    • Log in to your DashX workspace
    • Navigate to the Broadcasts section
    • Create a new Broadcast
    • Select your verified domain as the sender
    • Send a test email and verify that it's delivered
    • Verify that SPF, DKIM, and DMARC authentication passes

  3. Monitor email metrics: Monitor your email performance through the DashX console:

    • Navigate to the Broadcasts section in your DashX workspace
    • View sending statistics, delivery rates, and engagement metrics
    • Monitor bounce and complaint rates to maintain a good sender reputation
    • Use these metrics to optimize your email campaigns

  4. Review Mailgun statistics: Check your Mailgun dashboard for additional insights:

    • Navigate to Analytics to see email performance metrics
    • View Logs to see recent email activity
    • Monitor Suppressions to manage bounces and unsubscribes
tip

Mailgun offers a free tier with 5,000 emails per month for the first 3 months, then 1,000 emails per month. For higher volumes, consider upgrading to a paid plan. Make sure to monitor your sending limits to avoid hitting rate limits.