Mailgun

Mailgun is the primary email delivery platform used when an application needs to send transactional emails such as account notifications, password resets, receipts, and workflow updates. It is intended for system-generated email rather than ad hoc communication from staff.

Mailgun provides APIs, SMTP delivery options, and webhooks for message events such as delivery, bounce, complaint, and unsubscribe activity. Within our architecture, it should be integrated behind an application notification service rather than called directly from business logic throughout the codebase.

Purpose

Use Mailgun when a system needs to:

• Send transactional emails triggered by application events
• Deliver password resets, confirmations, receipts, and status updates
• Track message delivery, opens, bounces, complaints, or suppressions
• Process email-related webhooks as part of operational workflows

Mailgun is best suited for reliable, application-driven email delivery where templates, observability, and operational control matter.

Recommended Usage

When integrating Mailgun into an application:

• Keep Mailgun-specific code inside a dedicated email or notification service
• Store API keys and domain credentials in environment variables or a secrets manager like Azure Key Vault
• Use reusable templates for common transactional messages
• Capture Mailgun message identifiers in logs for traceability and support
• Handle delivery, bounce, and complaint webhooks asynchronously
• Retry transient failures carefully and use idempotent logic to avoid duplicate sends

This keeps the provider integration isolated and makes it easier to change implementation details without spreading vendor concerns across the application.

Design Considerations

Before adding transactional email functionality, define:

• The application event that triggers the email
• Who the recipients are and how addresses are sourced and validated
• Whether the message must be delivered immediately or can be queued
• What should happen if delivery fails or Mailgun is unavailable
• What message content should be templated, logged, or retained for auditing

Email is better suited than SMS for longer-form content, confirmations, receipts, and communication that may need to be referenced later. Time-sensitive or urgent alerts may still be better handled through additional channels.

Security and Deliverability

Applications using Mailgun should follow these baseline practices:

• Never commit Mailgun API keys, SMTP credentials, or sending-domain secrets to source control
• Use verified sending domains and maintain required DNS records such as SPF, DKIM, and DMARC
• Avoid placing unnecessary sensitive or protected data in email bodies
• Respect unsubscribe, suppression, and complaint handling requirements where applicable
• Separate non-production sending domains, recipients, or routing rules from production traffic when possible

Deliverability depends on sender reputation, domain configuration, and message quality. Email workflows should be designed with bounce handling and suppression management in mind from the beginning.

Any implementation that handles protected data, regulated notifications, or public-facing messaging should be reviewed carefully during code review.

Sending Domains

Domain	Environment
polkfl.app	Production
sandbox0408bb01a8054cc689a056313d27d80b.mailgun.org	Staging

The primary sender address used in production is [email protected].

Testing and Operations

Mailgun integrations should be tested at multiple levels:

• Unit tests should mock the Mailgun client or wrap it behind an interface
• Integration tests should verify request construction, error handling, and webhook processing
• Non-production environments should use test domains, sandbox recipients, or controlled routing where available
• Local development should not send real emails by default

Operationally, teams should monitor bounces, complaints, suppressions, and delivery failures so issues with templates, recipient quality, or domain reputation can be addressed quickly.