Unsubscribe

The Unsubscribe system manages notification opt-out workflows compliant with RFC 8058 (One-Click Unsubscribe). The UnsubscribeController at /api/v1/notifications/unsubscribe handles email link unsubscribes, API-based unsubscribes, preference management, and resubscription.

Unsubscribe via Email Link

When a user clicks the unsubscribe link in an email, they are directed to this endpoint which returns an HTML confirmation page.

Endpoint: GET /api/v1/notifications/unsubscribe

GET /api/v1/notifications/unsubscribe?token=unsub-token-abc&reason=too-frequent

One-Click Unsubscribe (RFC 8058)

Supports the List-Unsubscribe-Post header for one-click unsubscribe in email clients.

Endpoint: POST /api/v1/notifications/unsubscribe/one-click

POST /api/v1/notifications/unsubscribe/one-click?token=unsub-token-abc

Unsubscribe via API

Endpoint: POST /api/v1/notifications/unsubscribe

curl -X POST "http://localhost:8085/api/v1/notifications/unsubscribe?token=unsub-token-abc" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Too many emails" }'

Get Subscription Status

Endpoint: GET /api/v1/notifications/unsubscribe/status

curl "http://localhost:8085/api/v1/notifications/unsubscribe/status?tenantId=550e8400-e29b-41d4-a716-446655440000&email=alice@acme.com" \
  -H "Authorization: Bearer ${TOKEN}"

Update Subscription Preferences

Endpoint: PUT /api/v1/notifications/unsubscribe/preferences

curl -X PUT "http://localhost:8085/api/v1/notifications/unsubscribe/preferences?tenantId=550e8400-...&userId=user-001&email=alice@acme.com" \
  -H "Content-Type: application/json" \
  -d '{
    "alerts": true,
    "reports": true,
    "billing": true,
    "marketing": false
  }'

Resubscribe

Endpoint: POST /api/v1/notifications/unsubscribe/resubscribe

curl -X POST http://localhost:8085/api/v1/notifications/unsubscribe/resubscribe \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "550e8400-...",
    "email": "alice@acme.com",
    "category": "reports",
    "channel": "EMAIL"
  }'

Unsubscribe Statistics

Endpoint: GET /api/v1/notifications/unsubscribe/stats/{tenantId}

Unsubscribe History

Endpoint: GET /api/v1/notifications/unsubscribe/history/{tenantId}

Available Categories

Endpoint: GET /api/v1/notifications/unsubscribe/categories

Tracking & Analytics API Reference