One-Click Unsubscribe (Gmail / Yahoo 2024)

POST /api/v1/notifications/unsubscribe — 🌐 Public · Rate limit: 10 req / hour

Gmail and Yahoo's 2024 bulk-sender requirements mandate RFC 8058 one-click unsubscribe — a List-Unsubscribe-Post: List-Unsubscribe=One-Click body sent to the URL in the List-Unsubscribe email header. This endpoint accepts that POST and runs the same side effects as the public GET unsubscribe link: suppression list insert + per-event email-channel downgrade + GDPR consent record.

Request

Query parameters

Headers

Body

Form-urlencoded List-Unsubscribe=One-Click. The body is not load-bearing — the controller reads email + token from the query string. Body presence is the RFC 8058 signal that the mail client supports one-click.

Response

200 OK — ApiResponseOf<UnsubscribeResponseDto>

Valid token

{
  "success": true,
  "data": {
    "success": true,
    "message": "You have been unsubscribed from email notifications."
  }
}

Invalid / expired token

{
  "success": true,
  "data": {
    "success": false,
    "message": "Invalid or expired unsubscribe link."
  }
}

Missing token

{
  "success": false,
  "message": "Missing token."
}

Errors

The endpoint deliberately never returns 4xx for missing or invalid params — 2xx with { success: false } is the timing-safe shape used to deter address enumeration.

Side effects

Identical to the GET handler — both call processUnsubscribe() with a different source flag.

1. Missing token → { success: false, message: 'Missing token.' }. No mutations.
2. Verify token via UnsubscribeTokenService.verifyToken(token, email). Returns { valid, format, userId?, email?, scope?, expired? }.
3. Resolve target user —
   • v2_user_scope: userId from token. If email is missing in the query, look up User.email by ID.
   • v1_email_hex: email from token. Look up User.id by email.
4. Suppress email — emailSuppressionList.findUnique({ where: { email } }); if missing, create with reason: 'user_unsubscribe', provider: null (idempotent).
5. Disable email channel per event — for every row in NotificationDefault:
   • If scope === 'marketing', skip events other than marketing_campaign.
   • Otherwise, notificationPreference.upsert({ update: { email: false }, create: { email: false, push: true, inApp: true, webPush: true, sms: true } }).
6. GDPR consent log — write ConsentRecord row with documentType: 'notification_preference', accepted: false, preferences.action: 'opt_out', preferences.source: 'email_one_click_post', IP + user-agent captured for Art. 7(1) demonstrability.
7. Return { success: true, message: 'You have been unsubscribed from email notifications.' }.

Code samples

# Simulate Gmail's RFC 8058 POST. Token + email come from the
# List-Unsubscribe header URL embedded in the original email.
curl -X POST 'https://api.bio.re/api/v1/notifications/[email protected]&token=v2.user-uuid.marketing.1719072000.abc123def456' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'List-Unsubscribe=One-Click'

type UnsubscribeResponse = {
  success?: boolean;
  message: string;
};

async function oneClickUnsubscribe(
  email: string,
  token: string,
): Promise<UnsubscribeResponse> {
  const url = new URL('https://api.bio.re/api/v1/notifications/unsubscribe');
  url.searchParams.set('email', email);
  url.searchParams.set('token', token);
  const res = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: 'List-Unsubscribe=One-Click',
  });
  const json = await res.json();
  if (!res.ok || !json.success) {
    throw Object.assign(new Error(json?.error?.message ?? 'Unsubscribe failed'), {
      code: json?.error?.code,
    });
  }
  return json.data;
}

List-Unsubscribe: <https://api.bio.re/api/v1/notifications/unsubscribe?email=fan%40example.com&token=v2.user-uuid.marketing.1719072000.abc123def456>, <mailto:[email protected]?subject=unsubscribe&body=token%3D...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Source