Coastal Elements

Appearance

Mailgun ​

This document describes the integration of Mailgun as an email provider in the Campaign Service. It covers API usage, best practices, error handling, and architecture considerations.

How Mailgun Works ​

  • API: HTTP REST (POST to https://api.mailgun.net/v3/[domain]/messages or batch endpoints).
  • Authentication: API key (stored in secrets manager). Use per-domain keys or a single key scoped to the sending domain.
  • Capabilities: open/click tracking, tagging, templates (Mailgun templates can be used but rendering is usually done in-app), batch sending via recipient-variables.
  • Best practices:
    • Use a verified domain with correct SPF, DKIM, and DMARC records.
    • Use Mailgun webhooks for delivered, dropped, bounced, opened, clicked, complained.
    • Respect suppression lists; do not re-send to addresses in Mailgun suppression without a deliberate flow.
    • Use message headers: X-Mailgun-Variables, X-Mailgun-Tag for analytics.
  • Response handling:
    • 200/202 -> accepted. Treat as success and persist provider message id for later correlation.
    • 4xx -> client errors (bad request, validation): treat as non-retriable unless transient (e.g., rate-limit headers suggest retry-after).
    • 5xx or 429 -> transient: retry with exponential backoff. Observe Retry-After header if present.
  • Webhook security: validate Mailgun signature (timestamp + token + signature) and timestamp window.

Key notes for Mailgun-only: ​

  • Use Mailgun webhook endpoint protected by signature verification and a narrow ingress rule (IP or firewall) if possible.
  • Persist Mailgun message-id returned on send for later correlation with webhook events.
  • Respect Mailgun suppression lists; optionally sync suppression state into your DB.
  • Monitor API error rates and use a circuit-breaker to avoid cascading failures; without fallback the circuit-breaker should trigger alerts and optionally pause campaigns.

Tracking & bounce-rate (short) ​

  • Mailgun provides webhooks for delivered/opens/clicks/bounces/complaints; verify signatures and enqueue events for durable processing.
  • Compute delivered_count from delivered & bounce events, then calculate:
    • open_rate = unique_opens / delivered_count
    • click_rate = unique_clicks / delivered_count
  • Alert on high hard-bounce or complaint rates and consider automated account suspension for repeat offenders.

What Mailgun can't do (limitations) ​

  • Guaranteed open accuracy: opens are an undercount because many clients block images or proxy requests.
  • Perfect deliverability: Mailgun helps with deliverability but cannot guarantee inbox placement; IP/domain warm-up and reputation work are still required.
  • Deep AWS integration: Mailgun is not native to AWS (no IAM/SNS tight integration); SES offers smoother IAM/SNS/SQS workflows inside AWS.
  • Built-in scaling policy: you still need to monitor quotas and apply throttling/backpressure in your application; Mailgun exposes rate-limit responses but does not auto-scale your app.

Main considerations — Mailgun ​

  • Quick onboarding and developer-friendly REST API.
  • Strong built-in tracking and tagging features; convenient webhooks for event capture.
  • Use when you need fast setup, rich per-message metadata, and a provider-managed deliverability offering.
  • Operationally: ensure suppression lists are respected and signatures are validated. Monitor request quotas and set circuit-breakers for 5xx/429 patterns.