RFC 8058 One-Click Unsubscribe: How to Implement It (Complete 2026 Guide)

Two Headers Most Senders Get Wrong — and Get Throttled by Gmail For

Since February 2024, Gmail and Yahoo require one-click unsubscribe on any marketing email sent at volume above 5,000 messages per day. The standard is RFC 8058 — a 9-page IETF spec that almost nobody implements correctly the first time. Get it wrong and Gmail throttles you, Yahoo bounces you, and your reputation craters in 48 hours.

This guide is the engineer’s and lifecycle marketer’s playbook to RFC 8058 in 2026: what the spec actually requires, the exact headers to add, the POST endpoint to build, and the gotchas that bite even mature senders.

The 60-second model: RFC 8058 is two HTTP-style headers (List-Unsubscribe and List-Unsubscribe-Post), one POST endpoint that processes the unsubscribe without requiring a click-through, and a hard rule: receiving the POST must remove the recipient from your list within 2 days.

What RFC 8058 Actually Requires

RFC 8058 is an extension to RFC 2369. It defines a way for mailbox providers (Gmail, Yahoo, Apple Mail) to surface a single unsubscribe button next to the sender name, and to fire that unsubscribe via HTTP POST — no click-through to a confirmation page.

The two required headers

List-Unsubscribe: <https://yourdomain.com/u/abc123>, <mailto:unsub@yourdomain.com?subject=unsubscribe>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Anatomy of the headers

• List-Unsubscribe — the URL (and optional mailto fallback) where unsubscribe happens.
• List-Unsubscribe-Post — the literal string List-Unsubscribe=One-Click tells the receiver this URL handles a POST without confirmation.
• Both headers MUST be present for RFC 8058 compliance.
• The URL MUST accept HTTP POST — not just GET.

How the One-Click POST Works

1. User clicks the unsubscribe button in Gmail.
2. Gmail’s servers send an HTTP POST to your List-Unsubscribe URL.
3. The POST body contains List-Unsubscribe=One-Click as form data.
4. Your endpoint immediately removes the recipient from the list.
5. Your endpoint returns HTTP 200.

Critical: no user interaction allowed

Gmail’s server hits your endpoint — not the user’s browser. There is no opportunity to show a confirmation page, ask for a reason, or collect feedback at this step. You can ask later in a follow-up email, but the unsubscribe itself MUST happen on the POST.

Building the Unsubscribe Endpoint

Minimal Node.js / Express implementation

app.post('/u/:token', async (req, res) => {
  const { token } = req.params;
  const isOneClick = req.body['List-Unsubscribe'] === 'One-Click';

  // Verify token (HMAC-signed, encodes contact_id + list_id + expiry)
  const payload = verifyToken(token);
  if (!payload) return res.status(400).end();

  // Suppress immediately
  await suppressContact(payload.contact_id, payload.list_id, 'one-click');

  // Audit log
  await logUnsubscribe({
    contact_id: payload.contact_id,
    method: isOneClick ? 'rfc8058' : 'manual',
    timestamp: new Date(),
  });

  return res.status(200).end();
});

Token Design: Don’t Use Sequential IDs

The token in the URL is sensitive — if guessable, attackers can mass-unsubscribe your contacts. Best practice:

• HMAC-signed JWT or signed token with contact_id, list_id, send_id, and expiry.
• Single-use idempotency — subsequent POSTs with the same token return 200 but no-op.
• 90-day expiry — expired tokens still suppress (because the user clicked unsubscribe), but should be flagged for audit.

The Five Most Common RFC 8058 Mistakes

1. Missing List-Unsubscribe-Post header. Without it, Gmail won’t fire the one-click POST — the link becomes a regular GET requiring user click-through.
2. Endpoint requires GET, not POST. Common when teams reuse an existing unsubscribe page. RFC 8058 explicitly requires POST.
3. Endpoint returns 302 redirect. The receiver expects 200. A redirect can be interpreted as failure.
4. Suppression takes more than 2 days. Gmail’s rules require the recipient be removed within 2 days. Real-time suppression is the safest path.
5. Missing CSRF or rate-limiting. The POST endpoint is publicly callable; protect against abuse with token signature + rate limits.

Gmail and Yahoo’s Hard Requirements

Testing Your Implementation

Three tools to verify RFC 8058 before you scale:

1. Mail-Tester.com — sends a test campaign through real receivers, reports whether headers are present and parseable.
2. MX Toolbox Email Header Analyzer — paste the raw email source, see the headers parsed.
3. curl — manually POST to your endpoint and verify suppression takes effect within seconds.

The curl test

curl -X POST https://yourdomain.com/u/abc123 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "List-Unsubscribe=One-Click"

The endpoint should return 200, and the recipient should appear in your suppression table within seconds.

How EmailSendX Handles RFC 8058 Automatically

Implementing RFC 8058 yourself is a one-time engineering project. EmailSendX handles it for every campaign automatically:

• RFC 8058-compliant headers on every marketing email by default.
• HMAC-signed tokens with 90-day expiry and idempotency.
• Real-time suppression — POST hits the suppression list within milliseconds.
• Per-workspace audit log — compliance teams can verify every unsubscribe.
• Custom unsubscribe domain — unsubscribe links use your branded tracking domain, not ours.

FAQ: RFC 8058 One-Click Unsubscribe

Is RFC 8058 only required for Gmail and Yahoo?

Officially, yes — but Apple Mail, Outlook.com, and most major receivers honor it too. Implement once, benefit everywhere.

Do I still need a visible unsubscribe link in the email body?

Yes. RFC 8058 is in addition to the visible link, not a replacement. CAN-SPAM and GDPR both still require a clear, conspicuous unsubscribe option in the email body.

What happens if my POST endpoint is down?

Gmail retries for a window, then falls back to the GET URL. If your endpoint is down for > 24 hours, you risk Gmail flagging your campaign as non-compliant.

Can I confirm the unsubscribe with a follow-up page?

Not on the POST itself. You can show a confirmation if the user also clicks the visible link (which is a GET). The POST must be silent and immediate.

Do transactional emails need RFC 8058?

Strictly transactional email (receipts, password resets, account confirmations) is exempt. Anything marketing — including newsletters, promos, lifecycle emails — requires it above the 5k/day threshold.