Email Unsubscribe (Public)

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

Public unsubscribe link target. Reachable from email footers without login. Validates a server-signed HMAC token (sha256 over the email address, truncated to 32 hex chars), then adds the email to the suppression list and flips email: false in every notification preference for the matching user.

Request

Query parameters

No body, no headers required.

Response

200 OK — ApiResponseOf<UnsubscribeResponseDto>

Three response shapes depending on input + validity:

Missing email or token (link without params)

{
  "success": true,
  "data": {
    "message": "Please visit your account settings to manage notification preferences."
  }
}

Invalid token (HMAC mismatch)

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

Valid token

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

Errors

The endpoint does not return 4xx for missing or invalid params — it always returns 200 with a tailored message body. This is deliberate: email links can't enumerate addresses or distinguish "wrong token" from "wrong address".

Side effects

1. Missing email/token → return friendly fallback message. No mutations.
2. Compute expected token — createHmac('sha256', UNSUBSCRIBE_HMAC_SECRET).update(email).digest('hex').slice(0, 32). In dev mode, falls back to 'dev-unsubscribe-secret' if env var is unset.
3. Token mismatch → return { success: false, message: 'Invalid or expired unsubscribe link.' }. No mutations.
4. Token valid — two-pass mutation:
   • Suppress email — emailSuppressionList.findUnique({ where: { email } }); if missing, create with reason: 'user_unsubscribe', provider: null. Idempotent.
   • Disable email channel for the user — prisma.user.findUnique({ where: { email } }) to resolve userId; if found, iterate every notificationDefault.findMany row and notificationPreference.upsert({ update: { email: false }, create: { email: false, push: true, inApp: true, webPush: true, sms: true } }) for each eventKey.
5. Return { success: true, message: 'You have been unsubscribed from email notifications.' }.

Code samples

# Direct call (server-generated token)
curl 'https://api.bio.re/api/v1/notifications/[email protected]&token=abc123def456...32chars'

# Missing-params fallback (returns friendly message)
curl 'https://api.bio.re/api/v1/notifications/unsubscribe'

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

async function unsubscribeFromEmail(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);
  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;
}

<!-- Generated by the email template — token computed server-side via HMAC -->
<a href="https://bio.re/[email protected]&token=ab12cd34...">
  Unsubscribe
</a>

Try it

curl -X GET "https://loading/api/v1/notifications/unsubscribe"

{
  "success": true,
  "data": {
    "success": true,
    "message": "string"
  }
}

Source