Mailgun (Email)

Configure Mailgun to send OTP codes, RSVP confirmations, payment reminders, and other transactional emails.

Prerequisites

• A Mailgun account (free tier available)
• A domain you control with DNS access
• Access to your DNS provider's management panel

Create a Mailgun account

Sign up at mailgun.com. The free tier includes enough volume for most events. You can verify your account later when ready to send to non-test addresses.

Add a sending domain

In the Mailgun dashboard, navigate to Sending → Domains → Add New Domain.

Use a subdomain like mg.tripplan.ing rather than your root domain.

TIP

A subdomain keeps Mailgun's DNS records separate from your main domain records and avoids conflicts with existing email services.

Verify DNS records

Mailgun provides DNS records to add at your DNS provider. Add all required records:

Record type	Name	Purpose
TXT	mg.yourdomain.com	SPF — authorizes Mailgun to send on your behalf
TXT	Various selectors	DKIM — cryptographic email signing
CNAME	email.mg.yourdomain.com	Tracking (optional)
MX	mg.yourdomain.com	Receiving (optional — only if you want inbound)

After adding the records, click Verify DNS Settings in the Mailgun dashboard. DNS propagation can take up to 48 hours, but usually completes within minutes.

Get your API key

1. In the Mailgun dashboard, navigate to API Security (under your account menu)
2. Copy your Private API key — this is the value for MAILGUN_API_KEY

WARNING

The Private API key has full send permissions. Store it as an encrypted secret, never in source control.

Configure tripplan.ing

Map your Mailgun credentials to environment variables:

Mailgun value	Environment variable	Example
Private API key	MAILGUN_API_KEY	key-abc123...
Sending domain	MAILGUN_DOMAIN	mg.tripplan.ing

For local development, add these to .dev.vars:

MAILGUN_API_KEY=key-abc123...
MAILGUN_DOMAIN=mg.tripplan.ing

For production, set these as GitHub Environment secrets (see Environment & Secrets).

Mailgun is configured globally — there is no per-event override. All events share the same sending domain and API key.

Verify it works

1. Start the dev server with make dev
2. Visit /auth on any event subdomain
3. Enter an email address and submit
4. Check the Mailgun dashboard under Sending → Logs for the OTP email

If using dev bypass (ENABLE_DEV_BYPASS=true), emails are skipped in local development. Disable it to test real email delivery.

Troubleshooting

Symptom	Fix
OTP email never arrives	Check Mailgun Logs for delivery status; verify DNS records are verified
"Unauthorized" error in server logs	Confirm MAILGUN_API_KEY is the Private API key, not the public validation key
Email lands in spam	Verify both SPF and DKIM DNS records; use a subdomain sender
DNS verification stuck	Wait for propagation; confirm records match exactly (no trailing dots or extra spaces)
"Domain not found" error	Confirm MAILGUN_DOMAIN matches the verified domain in Mailgun, not your root domain

Related pages

• Environment & Secrets — full environment variable inventory
• Auth System — how the OTP email flow works
• Troubleshooting — general debugging steps