Mailgun integration

Overview

Mailgun is a transactional + marketing email API. The Automize connector covers send, mailing lists, templates, suppressions (bounces / unsubscribes / complaints), events, domain management, and stats.

• Regions: Two production regions: api.mailgun.net (US) and api.eu.mailgun.net (EU). The connector reads the 'region' setting and routes accordingly. A domain is bound to one region – moving between regions requires re-verification.
• Plans: Free tier (5k emails/month, sandbox-only domain). Foundation + Growth + Scale tiers add custom domains, IP pools, deliverability tools, log retention.

Setting up the connection

Auth type: HTTP Basic.

1. In Mailgun → Account Settings → API Security, copy the Private API key (starts with key-).
2. Paste the key as the API key (password field). Username defaults to 'api'.
3. Add the verified Sending domain (e.g. mg.yourcompany.com) – the connector embeds it in the URL path for send/lists/templates calls.
4. Pick region: 'us' (api.mailgun.net) or 'eu' (api.eu.mailgun.net). Wrong region = 401 even with a valid key – domains are region-locked.

Find your credentials at https://app.mailgun.com/app/account/security/api_keys.

Rate limits

No published per-second rate limit on send for paid plans; sandbox is hard-capped at 5 sends to authorized recipients. Suppression / events / stats endpoints throttle around 300 req/min. Connector retries on 429 with backoff.

Data model

Mailgun groups everything under a Domain:

    Domain (mg.example.com)
      ├─ Messages (Send)
      │    └─ Events (delivered, opened, clicked, failed, ...)
      ├─ Suppressions
      │    ├─ Bounces       (hard failures, auto-suppressed)
      │    ├─ Unsubscribes  (user clicked unsubscribe link)
      │    └─ Complaints    (FBL spam reports)
      ├─ Mailing Lists
      │    └─ List Members
      ├─ Templates          (versioned per template name)
      └─ Stats              (aggregated counters per period)

Send paths are domain-scoped: POST /v3/{domain}/messages. So is
every list / template / suppression endpoint. The 'domain'
credential setting drives the URL.

Events are retained 30 days on Growth, 5 days on Foundation. Past
the retention window, events are gone – push to your own log sink
via webhooks if you need longer history.

IDs:

    message_id   in Message-Id: header, e.g. <20260513.abc@mg.example.com>
    event id     short hex, only meaningful inside the events feed
    list address group@mg.example.com (the list IS its address)

Available operations

17 operations available. Click any row to jump to its detail.

Operations

Add Mailing List Member

Add a member to a mailing list

Tips

• POST /lists/{address}/members – body is address + name + vars (JSON). upsert=yes is required to update an existing member; default behaviour 400s on duplicate.

Create Domain

Add a new sending domain

Tips

• Body: name (FQDN, e.g. mg.example.com) + smtp_password (optional) + dkim_key_size (1024|2048) + web_scheme (http|https) + force_dkim_authority + spam_action (disabled|tag|delete).
• Returns sending_dns_records[] and receiving_dns_records[] – add these to your DNS, then call Verify Domain.
• dkim_key_size=1024 is needed when your registrar truncates TXT records >255 chars (some legacy registrars do).

Create Mailing List

Create a new mailing list

Tips

• Body: address (e.g. team@mg.example.com), name, description, access_level (readonly|members|everyone), reply_preference (list|sender).
• access_level=readonly means only admins can post (recommended for announcements). everyone allows external posters – open-relay risk if abused.

Create Template

Create a stored template

Tips

• POST /v3/{domain}/templates – body: name (slug) + description + template (the body, in HTML/Mustache) + engine (mustache|handlebars) + tag (version label, e.g. 'v1').
• First version becomes active automatically. Update via POST /templates/{name}/versions; switch active via PUT with active=yes.

Delete Bounce

Remove a bounced address so it can receive mail again

Tips

• DELETE /v3/{domain}/bounces/{address} – removes the address from the suppression list.
• Re-suppression happens automatically on the NEXT hard bounce; this is for known-good addresses that hit a transient catch-all failure.

Get Domain

Get details for a sending domain

Tips

• GET /v4/domains/{domain} – full domain detail including DKIM key length, SPF state, MX records, web_prefix (tracking CNAME), require_tls flag, smtp_password rotation timestamp.
• Run after Verify Domain to confirm what passed/failed without re-triggering DNS check.

Get Stats

Get total domain statistics by event type

Tips

• GET /v3/{domain}/stats/total – aggregated counts per resolution (hour|day|month). event[] takes multiple values: accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored.
• Date format is 'Wed, 13 Nov 2024 12:34:56 +0000' – RFC2822, NOT ISO 8601. Get this wrong and you get an empty stats series, no error.

List Bounces

List bounced addresses for a domain

Tips

• Returns hard bounces only (permanent failures). Soft bounces (temporary) live in /events with event=failed&severity=temporary.
• Pagination via 'paging.next' URL – pass it back as the URL on the next call.

List Complaints

List spam complaints

Tips

• FBL (Feedback Loop) spam reports – recipients who clicked 'Mark as spam' in their mail client.
• Auto-suppressed: complained addresses bounce future sends with 605 until manually removed.

List Domains

List all sending domains on the account

No input parameters.

Tips

• GET /v4/domains – paginated. Filter by state=active|unverified|disabled. authority returns the sending-IP pool the domain is on.
• Custom-tracking-CNAME state is exposed under tracking.click.* – useful for catching half-setup domains.

List Events

Query delivery events (accepted, delivered, failed, opened, clicked)

Tips

• begin/end are RFC2822 strings or epoch seconds. Filter by event=delivered|failed|opened|clicked. ascending=yes to read in order.
• Events retained 30 days on Growth, 5 days on Foundation.

List Mailing List Members

List members of a mailing list

Tips

• GET /v3/lists/{address}/members/pages – paginated. subscribed=yes filters to opted-in members only.

List Mailing Lists

List mailing lists on the account

No input parameters.

Tips

• Account-wide list of mailing lists (group addresses). Filter by limit + skip; address filter on the exact list address (no wildcard).

List Templates

List stored templates for a domain

Tips

• Stored Templates (the modern templating system). Mustache + handlebars syntax with named versions.
• Each template has an active version; older versions are kept for rollback.

List Unsubscribes

List unsubscribed addresses

Tips

• Users who clicked the standard %unsubscribe_url% link or who replied with 'unsubscribe' (if you've configured the inbound rule).
• Tag-specific unsubscribes (mg's per-list unsubs) show up here with a 'tag' field – respect them across lists if the user wants global removal.

Send Email

Send an email via your sending domain

Tips

• Mandatory: from, to, subject, plus text OR html. Multiple to= recipients send a single email; use recipient-variables for personalised batch sends (up to 1000 recipients/call).
• Tracking: o:tracking=yes, o:tracking-clicks=htmlonly, o:tracking-opens=yes. Per-message override of domain defaults.
• Tags (o:tag) and Variables (v:my-var) show up in events + webhooks. Use them for cost attribution.

Errors

• 400 – Sandbox domain restriction – sandbox can only send to authorized recipients added under Domain Settings.
• 401 – Wrong region. Domain in EU, key from US (or vice versa). Check region setting.
• 402 – Free plan limit hit, or unpaid invoice. Open Account Settings → Billing.

Verify Domain

Trigger DNS verification on a domain

Tips

• Triggers DNS re-check for SPF/DKIM/MX/CNAME. State flips to 'active' once all records validate.
• DKIM key length defaults to 2048 – some legacy registrars truncate TXT records >255 chars; if validation fails, request a 1024-bit key from support.

FAQ

Region – US or EU?

Pick based on data residency requirements (GDPR scope for EU customer email). Once a domain is in a region, it's stuck – moving requires deleting + recreating + re-verifying DNS.

Why are emails landing in spam from a verified domain?

SPF/DKIM/DMARC alignment, IP reputation, content. Check stats → spam complaints + the Deliverability tool. Cold IPs (new Pro plan with dedicated IP) need a 2-4 week warmup ramp.

Hard bounce vs soft bounce – do both auto-suppress?

Hard bounces auto-add to the suppression list (won't be sent to again). Soft bounces don't – Mailgun retries internally for ~8h before giving up. Use list-events with severity=temporary to find them.

Sandbox domain – production-blocker?

Yes. Sandbox sends only to authorized recipients you've added by hand. Add a custom domain (mg.yourcompany.com), verify DNS, and use that for any real traffic.

Related connectors

• Postmark
• Resend
• Sendgrid
• Brevo
• Aws-ses