Implementar List-Unsubscribe one-click conforme a RFC 8058

Aprende a implementar List-Unsubscribe y List-Unsubscribe-Post one-click según RFC 8058 para cumplir los requisitos de remitentes masivos de Gmail y Yahoo.

Desde febrero de 2024, Gmail y Yahoo exigen a los remitentes masivos (a partir de 5.000 mensajes/día a sus dominios) ofrecer un mecanismo de baja en un solo clic, implementado conforme al RFC 8058. No es una recomendación: es un requisito que, si no se cumple, se traduce en pérdida de bandeja de entrada. Esta guía explica qué cabeceras debes incluir, cómo procesar las peticiones POST, qué errores son comunes y cómo validar que el flujo funciona.

Por qué importa list-unsubscribe one-click

Antes de RFC 8058, “List-Unsubscribe” era una cabecera opcional con dos sabores: un mailto: o una URL HTTP que abría una página de baja. Los clientes mostraban un enlace adicional, pero muchos usuarios seguían usando el botón “marcar como spam” porque era más rápido. Las quejas dañaban la reputación del remitente aunque hubiera baja disponible.

RFC 8058 estandariza un flujo en el que el cliente de correo (Gmail, Yahoo, Apple Mail, Outlook…) puede ejecutar la baja por sí mismo, en background, con una sola confirmación del usuario. Esto:

• Reduce las quejas de spam, que perjudican mucho más que las bajas.
• Mejora la reputación del dominio al sustituir señales negativas por neutras.
• Cumple los requerimientos de bulk senders de Gmail y Yahoo.

Cabeceras necesarias

Un email transaccional o de marketing que cumpla con RFC 8058 debe incluir tres cabeceras coherentes:

List-Unsubscribe: <mailto:[email protected]?subject=unsubscribe>, <https://tudominio.com/unsubscribe?token=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Y también suele acompañarse de:

List-ID: <newsletter.tudominio.com>

List-Unsubscribe

Acepta dos URIs: mailto: y https:. Lo recomendable es ofrecer ambos para máxima compatibilidad. El orden importa poco; los clientes priorizan HTTPS si está disponible.

List-Unsubscribe-Post

Esta es la novedad de RFC 8058: declara que la URL HTTPS soporta una petición POST con el cuerpo List-Unsubscribe=One-Click. Sin esta cabecera, los clientes no ejecutan la baja automática.

List-ID

No es requisito de RFC 8058 pero sí ayuda a Gmail a separar “listas” dentro de un mismo dominio para que la decisión del usuario aplique al hilo correcto.

Cómo debe responder tu endpoint HTTPS

El servidor debe aceptar POST (no GET) en la URL del List-Unsubscribe. El cuerpo será:

Content-Type: application/x-www-form-urlencoded
List-Unsubscribe=One-Click

Comportamiento esperado:

• Identificar al usuario por el token incluido en la URL.
• Marcar la baja en tu base de datos.
• Responder con un código 2xx (200 idealmente).
• No requerir cookies, login ni redirecciones intermedias.
• No abrir CAPTCHAs.
• No exigir confirmación adicional al usuario.

Si el endpoint pide cualquier interacción humana extra, no cumple RFC 8058.

Ejemplo de respuesta correcta

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 12

Unsubscribed

Manejo de tokens

El token debe ser:

• Único por destinatario y, preferiblemente, por envío.
• No adivinable (no usar el email en plano).
• Idempotente: ejecutar el mismo POST varias veces no debe generar errores.
• Razonablemente perdurable (al menos 30-60 días) para cubrir bajas tardías.

Una implementación habitual es un HMAC firmado con clave secreta del lado servidor que codifica (user_id, list_id, expiry). Validar es leer y verificar la firma; el almacenamiento queda mínimo.

Tokens y enlaces firmados

Si la URL ya pasa por un servicio de tracking que reescribe enlaces, asegúrate de que el endpoint de baja se sirve directamente por tu dominio sin pasar por el wrapper. El POST debe atacar el endpoint final, no un redirector.

El mailto: alternativo

Aunque la prioridad es HTTPS one-click, conviene mantener el mailto: por compatibilidad con clientes antiguos. Cuando el usuario escribe a esa dirección:

• El asunto suele ser unsubscribe o el que pongas en la cabecera.
• Necesitas un proceso (cron o webhook) que parsee esa bandeja y procese las bajas.
• La dirección debe estar autenticada por SPF y DKIM como cualquier otra.

Un buen patrón: [email protected] con sufijo (subaddressing) para identificar al destinatario sin tener que parsear el cuerpo.

Cuándo es obligatorio

Las reglas de bulk senders de Gmail y Yahoo aplican a:

• Cualquier remitente que envíe 5.000+ mensajes/día a Gmail (o a Yahoo).
• Cualquier dominio con DMARC publicado y aplicando enforcement.

Aunque tu volumen sea bajo, conviene implementarlo igual: la fricción de no tenerlo es mucho mayor que la de añadirlo.

Para envíos transaccionales puros (recibos, OTPs, password reset), el RFC permite no incluir bajas porque el destinatario no eligió suscribirse. Pero los criterios de Google son estrictos: si el mensaje es promocional aunque venga de un sistema transaccional, debe llevar List-Unsubscribe.

Validación práctica

Inspección de cabeceras

Envía un correo de prueba a una cuenta de Gmail. Abre el mensaje, “Mostrar original” y busca en las cabeceras:

List-Unsubscribe: <mailto:...>, <https://...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Gmail debe mostrar el botón “Unsubscribe” o “Cancelar suscripción” junto al remitente.

Test del POST

Desde curl:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d "List-Unsubscribe=One-Click" \
     "https://tudominio.com/unsubscribe?token=TEST_TOKEN"

Debe responder 2xx y la baja debe estar reflejada en tu base de datos.

Comprobación de SPF y DKIM

El email que lleva las cabeceras de baja también debe pasar SPF, DKIM y alinear con DMARC. Sin alineamiento, los clientes no muestran el botón.

Cómo afecta a la reputación

Implementar List-Unsubscribe one-click correctamente:

• Reduce el porcentaje de “marcar como spam”.
• Aumenta el de bajas legítimas, que es una señal neutral en lugar de negativa.
• Cumple el requisito formal de los bulk senders.

No esperes un salto inmediato en bandeja: el efecto es gradual, a medida que las quejas medias bajan y los proveedores reasignan reputación.

Errores frecuentes

Endpoint que pide confirmación

Es el error más común. Mostrar una página de “¿Estás seguro?” rompe el flujo one-click. La confirmación, si la quieres, debe darse en un email posterior, no antes.

Solo HTTPS o solo mailto

RFC 8058 funciona con HTTPS, pero los clientes antiguos pueden caer en mailto:. Ofrecer ambos no cuesta nada.

List-Unsubscribe-Post ausente

Sin esta cabecera, los clientes no ejecutan el POST automático. Verifica que se incluye en cada envío masivo.

Token reutilizado entre usuarios

Si el token no es único, un atacante puede dar de baja a otros. Firma siempre con clave secreta y vincula al destinatario.

Baja que tarda en aplicarse

El usuario no espera ver el siguiente envío y aun así recibirlo. La baja debe procesarse inmediatamente y bloquear cualquier envío en cola.

URL bloqueada por captcha o WAF

Algunos WAFs aplican challenges agresivos a peticiones POST sin sesión. Whitelistea el endpoint o configura una excepción para que el cliente pueda completar el flujo sin obstáculos.

No quitar al usuario también de campañas operacionales

Una baja conforme a RFC 8058 elimina al usuario solo de la lista identificada. Pero si tu sistema mete al mismo usuario en varios flujos de marketing, asegúrate de aplicar la baja a todos los relevantes.

Cómo encajarlo en una arquitectura existente

Si usas un ESP

La mayoría de plataformas modernas (Klaviyo, Mailchimp, Brevo, Sendgrid, Customer.io, Marketo) ya generan estas cabeceras automáticamente. Tu trabajo es:

• Activar la opción si no viene por defecto.
• Confirmar que el dominio de unsubscribe es el tuyo, no uno genérico del ESP.
• Verificar que el flujo no incluye páginas intermedias.

Si tienes infraestructura propia

Necesitas:

• Una librería de generación de tokens HMAC.
• Un endpoint HTTPS dedicado a /unsubscribe.
• Un proceso que parse el mailto: de bajas.
• Sincronización con todas tus listas de envío.

Empieza por el endpoint HTTPS: cubre el 95 % del tráfico.

Recursos relacionados

Si quieres profundizar, prueba estas herramientas gratuitas: Domain Health, mail tester, validador SPF y validador DMARC.

¿Necesitas que alguien lleve tu canal de email entero? Abalola Mail es la agencia de email marketing y retención para ecommerce de Abalola para ecommerce: estrategia, producción y operación del stack sobre Klaviyo, Mailchimp o Brevo.