​

Preferences & unsubscribe

1. Compliance (CAN-SPAM, GDPR): el destinatario debe poder darse de baja con un click.
2. Deliverability (RFC 8058): Gmail/Yahoo exigen List-Unsubscribe + One-Click para bulk desde feb-2024.
3. Higiene (UX): si alguien dice que no quiere ver un tipo de notificación, no se la mandamos aunque la flow esté activa.

​

Tabla notification_suppressions

​

Resolución de matches

1. scope='all' con el canal → bloquea todo. Devuelve esa row.
2. scope='category' + scope_value === category → bloquea. Devuelve esa row.
3. scope='template' + scope_value === templateId → bloquea. Devuelve esa row.
4. Sin match → null. Send procede.

​

Endpoints

​

Públicos (token-auth)

• Endpoint RFC 8058 One-Click. Mail clients (Gmail, Yahoo) postean aquí con body vacío cuando el usuario clickea Unsubscribe en su inbox.
• Verifica HMAC del token y upserta el row.
• Response 200 idempotente. 400 si token inválido (mail clients reintentan en el siguiente click).

• Landing page HTML. Confirma la cancelación + lista las suppressions actuales del usuario + footer con dirección Vivla.
• También aplica el opt-out (algunos MUAs hacen GET primero como “preview” — tratamos el intent como legítimo, idempotente).

​

Autenticados (Auth0)

• Lista las suppressions del usuario logueado.
• Envelope v1: { object: 'list', data: [...], has_more: false, next_cursor: null }.

• Re-subscribe: borra una suppression del usuario logueado.
• 204 No Content.

​

Tokens HMAC

uid → user_id (uuid)
ch  → channel
sc  → scope
sv  → scope_value (opcional)
exp → unix epoch seconds (default 30 días)

• UNSUBSCRIBE_TOKEN_SECRET — secret de firma (requerido para emitir headers).
• UNSUBSCRIBE_TOKEN_SECRETS_ACCEPTED — CSV de secrets antiguos que aún verifican durante una rotación. Soporta cero-downtime: emite con el nuevo, acepta con todos.

​

Operaciones comunes

SELECT s.channel, s.scope, s.scope_value, s.source, s.created_at
FROM notification_suppressions s
JOIN users u ON u.id = s.user_id
WHERE u.email = 'foo@example.com'
ORDER BY s.created_at DESC;

DELETE FROM notification_suppressions
WHERE user_id = (SELECT id FROM users WHERE email = 'foo@example.com')
  AND channel = 'email'
  AND scope = 'category'
  AND scope_value = 'promotional';

INSERT INTO notification_suppressions (user_id, channel, scope, scope_value, source, reason)
VALUES (
  (SELECT id FROM users WHERE email = 'foo@example.com'),
  'email',
  'category',
  'promotional',
  'manual_admin',
  'User requested via support ticket #1234'
);

​

Decisiones de diseño

​

Por qué HMAC y no rows en DB

​

Por qué scope=category default

​

Por qué redundar GET y POST con el mismo efecto

​

Ver también

• Email — cómo el motor inyecta los headers List-Unsubscribe + List-Unsubscribe-Post.
• Automations — sección “Suppressions (opt-out)” con el flujo del motor.
• apps/backend/src/notifications/preferences/ — código del módulo.