Mailgun Setup for HeadlessDomains Reseller Partners

This guide is part of the official HeadlessDomains Partners Program.

As a reseller partner, one of the most common blockers when launching a white-labeled or resold Headless Domains product (such as DeFiWallet.domains or similar) is transactional email — specifically, customers not receiving their login / magic code emails.

This page walks you through exactly what to do in your Mailgun account and what values to paste into your Railway service variables.

Why This Matters

Without working email, your end customers cannot complete the login flow. They enter their email at /account, never receive the code, and the entire customer experience breaks.

By properly configuring Mailgun (a reliable, developer-friendly transactional email service), you give your resold platform professional, branded email delivery with full control.

This is a standard part of onboarding as a HeadlessDomains reseller partner.

What Your Developer Needs

Your developer or ops person needs to add these environment variables to the Railway project (usually the main DeFiWallet or customer-facing service):

Required Variables

MAILGUN_API_KEY=
MAILGUN_DOMAIN=
MAILGUN_FROM_EMAIL=

Optional (Non-US Mailgun Region)

MAILGUN_API_BASE=https://api.eu.mailgun.net/v3

Recommended Additional Variable

PARTNER_SUPPORT_EMAIL=support@yourdomain.com

Once these are set, the customer login flow (email → code → sign in → save DNS record) should work end-to-end.

Step 1: Create or Log Into Your Mailgun Account

1. Go to mailgun.com and sign up (or log in).
2. Mailgun gives you a free trial with a limited number of emails. For production use with real customers, you will eventually need to add a credit card and move out of sandbox mode.

Important for partners: We recommend using a dedicated subdomain for transactional email (e.g. mail.yourdomain.com or mg.yourdomain.com). This keeps your main domain reputation clean.

Step 2: Add and Verify Your Domain in Mailgun

This is the most important step. If the domain is not verified, emails will not send reliably (or at all in production).

1. In Mailgun, go to Sending → Domains → Add New Domain.
2. Enter the subdomain you want to use (example: mail.defiwallet.domains or mg.yourresellerdomain.com).
3. Mailgun will show you several DNS records you must add:
   • TXT record (for verification)
   • CNAME records (for tracking and DKIM)
   • MX records (if you want to receive email at that domain — usually not needed for pure transactional)
4. Add these records in your DNS provider (Cloudflare, Namecheap, etc.).
5. Return to Mailgun and click Verify DNS Settings. It can take a few minutes to propagate.

Once verified, Mailgun will show the domain as "Active".

Pro tip for partners: Document the exact DNS records you added for each customer domain you resell. This makes future onboarding much faster.

Related guide: DNS & Nameserver Management

Step 3: Get Your Mailgun API Key

1. In Mailgun, go to Account Settings → API Keys (or API Security in newer UI).
2. Create a new Private API Key (do not use the public key).
3. Copy the key. It will look something like: key-XXXXXXXXXXXXXXXXXXXX

Store this key securely. You will only need to add it once to Railway.

Step 4: Fill in the Railway Environment Variables

Go to your Railway project → the relevant service (the one running the customer login code) → Variables.

MAILGUN_API_KEY

Paste the full private API key you copied from Mailgun (including the key- prefix).

MAILGUN_DOMAIN

This should be the exact domain (or subdomain) you verified in Mailgun.

Examples:

• mail.defiwallet.domains
• mg.yourreseller.com

Do not include https:// or the full URL — just the domain name.

MAILGUN_FROM_EMAIL

This is the email address that will appear in the "From" field of the login code emails.

Recommended formats for partners:

• login@yourverifieddomain.com
• no-reply@defiwallet.domains
• support@yourresellerdomain.com

The domain part must match (or be a subdomain of) your verified Mailgun domain.

MAILGUN_API_BASE (Only if using EU region)

By default Mailgun uses the US region. If you created your account in Europe, add:

MAILGUN_API_BASE=https://api.eu.mailgun.net/v3

Most partners can leave this blank.

Recommended: Set PARTNER_SUPPORT_EMAIL

This variable is used for support communications and error notifications.

PARTNER_SUPPORT_EMAIL=real-support-email@defiwallet.domains

Use a real monitored inbox (or a support alias you control). This helps the platform send proper branded support emails when customers need help.

Step 5: Test the Full Customer Flow

After adding the variables, deploy/restart the service in Railway if needed.

Test the complete loop:

1. Go to the customer login page (usually /account or the checkout email entry point).
2. Enter a test email address.
3. Check the inbox (and spam folder) for the login code.
4. Enter the code and sign in.
5. Try saving a DNS record as the final customer action.

If the email arrives quickly and the flow completes, you're good.

Common Issues & Troubleshooting

• Emails not arriving at all: Domain not verified in Mailgun, or using sandbox mode with an unapproved recipient.
• Emails going to spam: Check DKIM/SPF records (Mailgun provides them during domain setup). Use a clean from address.
• Wrong region errors: Add the MAILGUN_API_BASE for EU accounts.
• From address rejected: The domain in MAILGUN_FROM_EMAIL must be verified in Mailgun.
• Using sandbox domain: For real customers, move to a verified custom domain (not the default Mailgun sandbox).

As a HeadlessDomains partner, you can reach out to our team for help reviewing your Mailgun DNS records or Railway variable setup.

Best Practices for Reseller Partners

Next Steps as a HeadlessDomains Partner

Once Mailgun is working, the core customer login + DNS record flow should be complete.

Other common partner setup areas include:

• Custom domain / white-label branding
• Railway project templates and environment variable management
• DNS configuration for customer domains
• Support escalation processes

For the full partner onboarding checklist and ongoing support, visit partners.headlessdomains.com.

Related Resources

• Railway Deployments — Multiple guides on deploying and managing apps on Railway
• DNS & Nameserver Management — Deep guide on DNS records (very relevant for Mailgun domain verification)
• Headless Architecture — Understanding the broader headless + reseller model
• DNS-ID — Agent and domain identity infrastructure
• Tech Category — More technical deployment and infrastructure experiments

Need help? As a registered partner, reach out through the partners portal or your dedicated contact.