Back to Docs

Unsubscribe Flow UX Recipe

A frictionless offboarding pattern that preserves goodwill and meets legal requirements.

Core Principles

One-Click

No re-authentication. No surveys. The link itself is the authority.

🔒

Idempotent

Clicking twice changes nothing. Always show the same success state.

📬

Confirmation

Send a final email confirming the action. No marketing. Just closure.

Token Design

The unsubscribe link carries a signed token with a short TTL. Structure:

{
  "sub": "user_abc123",
  "list": "product_updates",
  "iat": 1716500000,
  "exp": 1716586400
}

Sign with HMAC-SHA256. Validate server-side. Reject expired or tampered tokens with a generic “link invalid” page.

Page States

1

Loading

Skeleton pulse while the token is verified. Under 400ms ideally.

2

Success

Green checkmark, “You’ve been unsubscribed”, and a single CTA back to the homepage.

3

Already Unsubscribed

Same visual as success but copy reads “You were already unsubscribed.”

4

Error / Invalid Link

Red indicator. “This link is invalid or has expired.” Offer a link to account settings.

Email Template

Sent after the unsubscribe is processed:

Subject: You’ve been unsubscribed

We’ve removed you from Product Updates. You won’t receive any more emails from this list.

If this was a mistake, you can re-subscribe anytime in your account settings.