Mailgun is a developer-first email API used for transactional and marketing sends by SaaS applications, marketplaces, and product teams. Unlike drag-and-drop marketing platforms, Mailgun does not inject an unsubscribe link automatically; you place the appropriate merge variable in your template, enable the Unsubscribes feature at the domain level, and Mailgun handles the click, the suppression, and the RFC 8058 headers. This guide covers the three unsubscribe variables Mailgun exposes, the domain configuration, the API for managing suppressions programmatically, and the common misconfigurations that break one-click compliance for Gmail and Yahoo.
Mailgun unsubscribe link: quick reference
| Item | Value |
|---|---|
| Domain-wide tag | %unsubscribe_url% |
| Tag-scoped tag | %tag_unsubscribe_url% |
| Mailing list tag | %mailing_list_unsubscribe_url% |
| Feature toggle | Sending > Tracking > Unsubscribes (per domain) |
| Suppression API | GET/POST/DELETE /domains/{domain}/unsubscribes |
| RFC 8058 one-click | Yes, when Unsubscribes is ON and variable is in the body |
The three unsubscribe variables in Mailgun
Mailgun exposes three distinct unsubscribe scopes. Picking the right one for the message context is the single most important decision because it defines what happens to the recipient’s suppression state on future sends.
Scope 1: domain-wide unsubscribe
%unsubscribe_url%The most common variable. When the recipient clicks, Mailgun adds the address to the domain’s global suppression list. Every subsequent send from that domain to that address is blocked automatically, regardless of message tag, mailing list, or campaign. Use this for marketing sends where a single opt-out should stop all promotional messages.
Scope 2: tag-scoped unsubscribe
%tag_unsubscribe_url%The recipient is suppressed only for messages carrying the same tag that was set on the original message. This is the correct choice when you send multiple distinct product surfaces from the same Mailgun domain (product notifications, weekly digest, marketing) and want to let recipients opt out of one surface without affecting the others. Set the tag on the send via the o:tag API parameter or the X-Mailgun-Tag SMTP header.
Scope 3: mailing list unsubscribe
%mailing_list_unsubscribe_url%Only meaningful when the send goes through Mailgun’s native Mailing Lists feature. The recipient is removed from the specific mailing list; other lists on the same domain still deliver. This variable is a no-op if the send is a single-recipient API call rather than a mailing list broadcast.
Enable the Unsubscribes feature on your domain
Placing the variable in the template is not enough. Mailgun only replaces the variable and emits the List-Unsubscribe header when the Unsubscribes tracking is enabled at the domain level.
- Log in to the Mailgun Control Panel
- Go to Sending > Domain settings, select the sending domain
- Open the Tracking tab
- Toggle Unsubscribes to ON. Confirm the tracking domain is HTTPS (Mailgun requires TLS for the unsubscribe click endpoint)
- Optionally set a custom unsubscribe redirect URL. This is where recipients land after confirming the opt-out; the default is a Mailgun-hosted “You have been unsubscribed” page
If Unsubscribes is OFF, Mailgun renders the variable as an empty string and does not add the List-Unsubscribe header. The recipient sees a broken (empty) unsubscribe link and the message fails RFC 8058 compliance silently.
Template example: HTML and MIME
In your HTML template, wrap the variable in an anchor tag:
<p style="font-size:14px;color:#666">
<a href="%unsubscribe_url%">Unsubscribe from this list</a>
</p>For plain-text templates, include the URL in a visible line:
To unsubscribe from these emails, visit: %unsubscribe_url%Mailgun replaces the variable at send time. The delivered message contains a signed URL scoped to the recipient and domain (or tag/list, depending on the variable). Clicking the URL processes the unsubscribe idempotently; repeated clicks are safe.
Managing unsubscribes via the Mailgun API
For programmatic use cases (importing suppressions from another platform, exposing an unsubscribe endpoint in your own app, syncing with a CRM), Mailgun provides a full REST API under /v3/{domain}/unsubscribes.
Check if an address is unsubscribed:
curl -s --user "api:YOUR_API_KEY"
"https://api.mailgun.net/v3/mg.example.com/unsubscribes/user@example.com"Add an address to the suppression list (useful when migrating from another ESP):
curl -s --user "api:YOUR_API_KEY"
-F address="user@example.com"
-F tag="marketing"
"https://api.mailgun.net/v3/mg.example.com/unsubscribes"Remove an address (re-subscribe, only after explicit consent from the recipient):
curl -s -X DELETE --user "api:YOUR_API_KEY"
"https://api.mailgun.net/v3/mg.example.com/unsubscribes/user@example.com"Subscribe to Mailgun webhooks to receive real-time unsubscribed events for downstream systems (CRM, analytics, revenue attribution). Configure webhooks in Sending > Webhooks > Unsubscribed.
RFC 8058 one-click compliance in Mailgun
Since February 2024, Gmail and Yahoo require senders exceeding 5,000 daily emails to those providers to support one-click unsubscribe via the List-Unsubscribe-Post header defined in RFC 8058. Mailgun emits the correct headers automatically when three conditions hold:
- Unsubscribes tracking is ON for the sending domain (Sending > Tracking > Unsubscribes)
- The message body contains at least one of
%unsubscribe_url%,%tag_unsubscribe_url%, or%mailing_list_unsubscribe_url% - The sending domain is authenticated with DKIM (Mailgun handles this automatically once the domain is verified in the Domains page) and SPF, plus DMARC published on the parent domain
Verify by inspecting a delivered message header:
List-Unsubscribe: <mailto:unsubscribe@mg.example.com?subject=unsubscribe>, <https://email.mg.example.com/unsubscribe/...>
List-Unsubscribe-Post: List-Unsubscribe=One-ClickTesting your Mailgun unsubscribe link
- Send a test message with the variable in the body. Use the Mailgun API or the SMTP relay to send to a controlled Gmail address
- Verify the delivered email. Open in Gmail, click three dots, “Show original”, confirm the
List-UnsubscribeandList-Unsubscribe-Postheaders are present - Click the visible unsubscribe link. Confirm the redirect to Mailgun (or your custom URL) and check the suppressions list for the address in Sending > Suppressions > Unsubscribes
- Test the one-click POST flow:
curl -X POST -d "List-Unsubscribe=One-Click" "https://email.mg.example.com/unsubscribe/..."Expected response: HTTP 200. The address should now appear as unsubscribed in the Mailgun dashboard within seconds, and subsequent sends to that address from the same domain should be blocked automatically with a 451 recipient unsubscribed response in the delivery log.
Common issues and how to fix them
The unsubscribe link is empty in delivered emails
Unsubscribes tracking is OFF for the domain. Fix by enabling it in Sending > Domain settings > Tracking. There is no per-message override; the toggle is domain-wide.
Mailgun returns “Tracking domain is not HTTPS”
Since 2023, Mailgun refuses to enable Unsubscribes tracking on domains where the tracking subdomain uses HTTP. Fix by configuring TLS on the tracking subdomain via Mailgun’s managed certificate (Sending > Domain settings > DNS records > Managed HTTPS). Propagation takes a few minutes.
Gmail does not recognize the one-click header
Two common causes: the message body has no unsubscribe variable (Mailgun then omits the header), or DKIM is misconfigured. Verify DKIM in Sending > Domain settings; the record should show a green DKIM checkmark for the exact selector Mailgun signs with.
Recipient unsubscribed on one Mailgun domain still receives from another
By design. Suppression lists are per-domain, not per-account. If you send from multiple sending domains (product notifications from notify.example.com, marketing from news.example.com), the unsubscribe on one does not propagate to the other. To keep both in sync, subscribe to the unsubscribed webhook and mirror the suppression via the API to the other domain.
Suppressed addresses cannot be re-added to a mailing list
Correct behavior. Mailgun blocks any send to a suppressed address, including additions to a mailing list. To re-add, delete the suppression via DELETE /unsubscribes/{address} only after obtaining explicit re-consent from the recipient; otherwise you are sending unsolicited mail to a known opt-out, which is a CAN-SPAM violation.
Related unsubscribe guides
Mailgun competes with several developer-first email APIs, each with a different unsubscribe model:
- SendGrid unsubscribe link: uses
{{{unsubscribe}}}, closest Mailgun competitor at scale, similar API model - Postmark unsubscribe link: uses
{{{ pm:unsubscribe }}}, transactional-focused with per-broadcast-list scoping - Amazon SES unsubscribe link: no automatic variable, headers must be set explicitly (or use Subscription Management)
- Loops unsubscribe link: uses
{{ unsubscribeUrl }}, modern developer alternative for SaaS product email - Resend unsubscribe link: uses
{{{RESEND_UNSUBSCRIBE_URL}}}, JavaScript-first API alternative - Messagebird (SparkPost) unsubscribe link: embedded, no template variable needed
For the full 222-platform reference table and the compliance landscape, see the pillar guide How to add an unsubscribe link: the complete 2026 guide. For the legal side, see CAN-SPAM Act, GDPR, and global unsubscribe laws.
Mailgun unsubscribe FAQ
Do transactional emails from Mailgun need an unsubscribe link?
Pure transactional messages (password resets, order confirmations) are exempt from CAN-SPAM’s unsubscribe requirement. GDPR still requires an opt-out for any marketing content mixed with transactional. Best practice is to add the %unsubscribe_url% variable in a footer even for transactional sends; the header is emitted, the visible link is present, and Gmail treats the message better even when technically not required.
Should I use the webhook or the API to sync unsubscribes to my system?
Use the webhook. The unsubscribed event fires within seconds of the click and is delivered with signature verification. Polling the API costs rate-limit budget and adds latency. Use the API only for on-demand lookups (checking a specific address before send) or for the initial bulk sync during onboarding.
Can I import a suppression list from another ESP into Mailgun?
Yes. Use the API to POST addresses to /unsubscribes individually, or use the bulk import in Sending > Suppressions > Import (CSV file). Mailgun accepts up to 100,000 addresses per import file; larger lists must be split.
Can I use my own domain for the unsubscribe URL?
Yes, and you should. Configure a tracking subdomain (for example email.example.com) with CNAME records to Mailgun. Once verified, unsubscribe URLs use your subdomain instead of email.mailgun.net. This preserves brand consistency and reduces the risk of links being flagged by mailbox providers.
Does Mailgun track unsubscribe rate per tag or per message?
Yes. The Analytics tab shows unsubscribe rate broken down by tag, by domain, and by time window. For per-message tracking, subscribe to the unsubscribed webhook and aggregate downstream; Mailgun does not expose per-message-id unsubscribe rate directly in the UI.
About the Author
Alaa · LinkedIn
Email infrastructure specialist with 8+ years of hands-on experience in SMTP, deliverability, and email verification. I’ve configured and troubleshot mail systems across Postfix, Exchange, and cloud relays, managed IP reputation and warmup campaigns, and built verification pipelines processing millions of addresses. My work spans DNS authentication (SPF, DKIM, DMARC, BIMI), bounce handling, blocklist monitoring, and compliance frameworks including CAN-SPAM and GDPR. I write every article on SMTPedia to give email professionals, developers, and marketers the accurate, RFC-grounded reference they need.
About SMTPedia
SMTPedia is an independent email industry reference covering SMTP, IMAP, POP3, email deliverability, marketing platforms, DNS authentication, and email verification. Every article is researched from official provider documentation, IETF RFCs, and industry best practices. Settings and configurations are verified quarterly.
We are cited as a source by ChatGPT, Microsoft Copilot, and thousands of email professionals worldwide. Learn more about our editorial process.
