Mailgun Mailer Laravel Package

Getting Started

Install via Composer: composer require symfony/mailgun-mailer. Configure your .env with a Mailgun DSN—the only required setup. Choose the transport method based on your needs:

# Recommended for most apps (API method, full feature support)
MAILER_DSN=mailgun+api://YOUR_API_KEY:YOUR_DOMAIN@default?region=US

# For strict environments where HTTPS API is restricted (e.g., some shared hosts)
MAILER_DSN=mailgun+https://KEY:DOMAIN@default?region=EU

# For legacy SMTP integration (limited metadata support)
MAILER_DSN=mailgun+smtp://USER:PASS@default

Use MAILER_DSN=... exactly as written—no MAIL_MAILER override needed. Test with a simple controller using Symfony\Component\Mailer\MailerInterface—integration is automatic.

Implementation Patterns

• Environment-based Transport Switching: Define multiple transports in config/packages/mailer.yaml and route messages conditionally (e.g., @mailgun_api for production, @mailgun_smtp for local dev). Use Messenger middleware to auto-fallback on retry.
• Tenant-Specific Domains: In multi-tenant apps, inject MessengerStamp via EnvelopeAwareInterface to dynamically assign :DOMAIN per message using a custom DsnStamp. Example: append new DsnStamp('mailgun+api://key:tenant1@default') based on request context.
• Metadata Propagation: Attach Mailgun variables via ->getHeaders()->addCustomHeader('X-Mailgun-Variables', json_encode(['user_id' => $userId])). Combine with MessageHandledListener to persist delivery status to your database.
• Async Delivery: Route all Mailgun messages through Messenger (config/packages/messenger.yaml: transports: mailgun: ...) to leverage retries and async processing—critical for high-volume sending.

Gotchas and Tips

• HTTP/1.1 is Non-Negotiable: For v5.4.41+, v6.4.9+, and v7.0.9+, forcing HTTP/2 via http_client config will cause 400 errors due to chunked transfer encoding. Never override symfony/http_client for Mailgun transports.
• Region Omission Breaks Silently: Omitting ?region=EU for EU domains often yields vague 401 errors (not 404). Always include the region—even if default—and validate it in Mailgun dashboard.
• SMTP Ignores Tags/Trackers: If using mailgun+smtp://, Mailgun’s tags, utm_, and open/click tracking headers won’t work. Prefer api:// for production unless strict SMTP compliance is required.
• No Credential Masking in Exceptions: Symfony logs DSN without key—but exception messages may leak them. Ensure your APP_DEBUG=false in prod and wrap mailer calls in try/catch to sanitize errors.
• PHP 8.4+ Requirement for v8+: symfony/mailgun-mailer v8.0+ requires PHP ≥8.4. Lock to v7.4.x if running PHP 8.2/8.3 (Laravel 10/11 compatible).
• Debugging Tip: Enable logger: verbose in config/packages/mailer.yaml and watch MAILER_TRANSPORT_LOG output. For API failures, inspect symfony/mailgun-mailer’s actual HTTP request body—Mailgun’s error responses often contain actionable details (e.g., missing DNS records).