Mailgun Setup Guide

NornWeave Documentation

Email Provider Setup Guides

Mailgun Setup Guide

This guide walks through setting up Mailgun as your email provider for NornWeave.

Prerequisites

A Mailgun account (sign up)
A domain you control for sending/receiving email
Access to your domain’s DNS settings

Step 1: Create a Mailgun Domain

Log in to Mailgun

Go to the Mailgun Dashboard and navigate to Sending > Domains.

Add Your Domain

Click Add New Domain and enter your domain (e.g., mail.yourdomain.com).

We recommend using a subdomain like mail. or mg. rather than your root domain.

Configure DNS Records

Mailgun will provide DNS records to add. You’ll need:

TXT record for SPF
TXT record for DKIM
MX records for receiving

Example DNS records:

Type	Name	Value
TXT	mail	`v=spf1 include:mailgun.org ~all`
TXT	smtp._domainkey.mail	`k=rsa; p=...`
MX	mail	`mxa.mailgun.org` (priority 10)
MX	mail	`mxb.mailgun.org` (priority 10)

Verify Domain

After adding DNS records, click Verify DNS Settings in Mailgun.

Step 2: Get API Credentials

Navigate to API Keys

Go to Settings > API Security in the Mailgun dashboard.

Copy Your API Key

Copy your Private API key. It looks like: key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your API key secret. Never commit it to version control.

Step 3: Configure Inbound Routes

Navigate to Receiving

Go to Receiving > Routes in the Mailgun dashboard.

Create a Route

Click Create Route with these settings:

Expression Type: Match Recipient
Recipient: .*@mail.yourdomain.com (catch-all)
Actions:
- Forward: https://your-server.com/webhooks/mailgun
- Store and Notify: Enabled (optional, for debugging)

Test the Route

Send a test email to test@mail.yourdomain.com and check NornWeave logs.

Step 4: Configure NornWeave

Update your .env file:

EMAIL_PROVIDER=mailgun
MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MAILGUN_DOMAIN=mail.yourdomain.com
MAILGUN_REGION=us  # or: eu

Variable	Description
`MAILGUN_API_KEY`	Your private API key
`MAILGUN_DOMAIN`	Your verified domain
`MAILGUN_REGION`	`us` for US region, `eu` for EU region

Step 5: Verify Setup

Restart NornWeave

docker compose restart api

Create a Test Inbox

curl -X POST http://localhost:8000/v1/inboxes \
  -H "Content-Type: application/json" \
  -d '{"name": "Test", "email_username": "test"}'

Send a Test Email

Send an email to test@mail.yourdomain.com from your personal email.

Check Logs

docker compose logs -f api

You should see the incoming webhook being processed.

Auto-Route Setup

NornWeave can automatically create Mailgun routes when you create an inbox. This requires:

Your API key has permission to manage routes
MAILGUN_AUTO_ROUTE=true in your environment

When enabled, creating an inbox will automatically create a matching Mailgun route.

Troubleshooting

Webhook Not Receiving

Verify your server is publicly accessible
Check Mailgun logs for delivery attempts
Ensure the route expression matches your inbox addresses

DNS Verification Failed

DNS changes can take up to 48 hours to propagate
Use dig or nslookup to verify records
Ensure no typos in the DNS values

Emails Going to Spam

Verify SPF and DKIM are properly configured
Check your domain reputation in Mailgun
Start with small volumes to warm up the domain

SendGrid Setup Guide