Enlaces de cancelación de suscripción
Un destinatario de tu correo de marketing tiene dos formas de cancelar la suscripción: el botón de cancelación que muestra su proveedor de correo y un enlace en el cuerpo del mensaje. Incluimos ambos en cada envío marketing, reportamos cada cancelación como un evento de webhook y registramos la cancelación de la dirección para que tu siguiente campaña la omita. Configurar la categoría correctamente es la única parte que te corresponde.
Configura la categoría
Una cancelación de suscripción solo tiene sentido para correo del que un destinatario puede optar por no recibir, por eso la categoría va primero. Un envío es category: "marketing" por defecto, así que el correo de campaña, boletín y anuncios se gestiona correctamente sin trabajo adicional. Configura category: "transactional" de forma explícita en correo operativo y lo dejamos tal cual. Un recibo o un restablecimiento de contraseña no tiene enlace de cancelación y nunca se bloquea por una cancelación previa del destinatario.
Dos obligaciones respaldan esto. Los remitentes masivos están obligados por Gmail y Yahoo a ofrecer cancelación de suscripción con un clic en correo de marketing, y un enlace visible en el cuerpo del mensaje es un requisito legal aparte en la mayoría de los mercados. Un envío marketing incluye ambos.
El botón de cancelación de suscripción con un clic
Este es el control de cancelación que los proveedores de correo muestran en el encabezado del mensaje. Proviene de un par de encabezados, List-Unsubscribe y List-Unsubscribe-Post, y los proveedores solo ofrecen la versión de un solo toque cuando ambos están presentes y el endpoint de cancelación acepta un POST no autenticado sin paso de confirmación. Ese es el contrato que Gmail y Yahoo verifican.
El correo de marketing sale con esos encabezados ya incluidos, sin importar cómo lo envíes: un broadcast desde el panel, o un mensaje marketing a través de POST /v1/email/messages. Nada que construir, nada que alojar.
Como nosotros gestionamos ese par de encabezados en correo de marketing, establecer tu propio List-Unsubscribe o List-Unsubscribe-Post en un envío marketing se rechaza con un 422. En un envío transactional no añadimos encabezado de cancelación, y puedes establecer el tuyo a través del campo headers si tienes motivo para hacerlo.
Un destinatario que usa el botón del proveedor produce un evento email.list_unsubscribed.
El enlace en el cuerpo del mensaje
La segunda vía es un enlace visible de cancelación en el propio mensaje. Añadimos uno al cuerpo HTML de tus envíos marketing, para que el destinatario siempre tenga algo que hacer clic. También puedes añadir tu propio enlace apuntando a un centro de preferencias que alojes tú, y el nuestro permanece junto a él como el mínimo normativo.
Por defecto, el enlace aparece como un pie de página pequeño al final del cuerpo. Para elegir tú la ubicación, coloca la variable reservada {{ bird.unsubscribe_url }} donde quieras el enlace:
Ejemplo de código
<p>
You received this because you subscribed to our newsletter. You can {{ bird.unsubscribe_url }} at
any time.
</p>Entonces renderizamos el enlace ahí en lugar de añadir el pie de página, como un ancla cuyo texto dice "unsubscribe". También puedes usarlo como valor de href (<a href="{{ bird.unsubscribe_url }}">Leave this list</a>) para mantener tu propio texto y estilo.
La sustitución ocurre solo en la copia saliente, así que al leer el mensaje de vuelta a través de API obtienes tu contenido original con la variable intacta.
Personaliza la página de destino en Email > Unsubscribe page. Configura el nombre del remitente, el fondo, el texto y los colores de los botones. El nombre del remitente toma por defecto el nombre de tu organización. Usa el enlace de ejemplo para previsualizar el resultado.
Un destinatario que usa el enlace en el cuerpo del mensaje produce un evento email.unsubscribed, distinto de email.list_unsubscribed para que puedas distinguir las dos vías.
Qué hace una cancelación de suscripción
Dejamos de enviar correo al destinatario sin que tú actúes sobre el webhook. Cualquiera de los dos eventos registra la dirección del destinatario como cancelada para correo no transaccional, lo que significa:
- Los envíos marketing a esa dirección se rechazan con email.rejected y rejection_reason: "recipient_suppressed". Ese motivo reporta cualquier bloqueo a nivel de destinatario, ya sea una supresión o una preferencia declarada, así que es el que debes usar en ambos casos.
- Los envíos transactional siguen pasando, porque una cancelación de suscripción indica que el destinatario no quiere más campañas. La dirección en sí sigue funcionando.
Una cancelación de suscripción es una preferencia declarada, no una supresión: aparece en la pestaña Preferences de Email > Suppressions y en la página de detalle del contacto, no en la lista de supresiones. Solo esa dirección se ve afectada, y el registro muestra quién canceló y cuándo.
Los eventos de webhook te permiten replicar la cancelación en tu propia base de datos, cambiar una marca de suscripción o registrarla. Ambos incluyen los campos identificativos de cada evento de correo: email_id, recipient_id, workspace_id, la dirección recipient y su recipient_role. También incluyen tags y metadata del envío original, para que puedas conciliar con tus registros sin otra consulta, y broadcast_id con el nombre del broadcast del que formó parte el correo, o null cuando el envío no tuvo un broadcast detrás. Un enlace de cancelación de correo enviado antes de que añadiéramos el campo no nombra ningún broadcast, así que una cancelación a través de ese enlace reporta null en ambos eventos, haya o no un broadcast detrás del envío. Suscríbete a ellos de la misma forma que a cualquier otro evento de correo; la referencia de eventos contiene los payloads completos.
Una cancelación de suscripción es la declaración del propio destinatario, así que no puedes eliminarla a través de API de supresiones como harías con una supresión. Para reanudar el envío a esa dirección, registra un opt-in en Contacts > Preferences, o llama a POST /v1/preferences con status: granted. Esa página a nivel de espacio de trabajo registra declaraciones para todos los canales, mientras que la pestaña en Email > Suppressions muestra las de correo electrónico. En cualquier caso, anular su cancelación requiere consented_at, el momento en que el destinatario dio su consentimiento, y el opt-in solo surte efecto cuando ese momento es posterior a la cancelación que revierte.
Próximos pasos
- Categorías: por qué marketing es lo que hace que una cancelación de suscripción surta efecto
- Supresiones: la lista de hechos de entregabilidad y en qué se diferencia de una preferencia declarada
- Eventos de correo: los payloads completos de email.unsubscribed y email.list_unsubscribed
- Requisitos de Gmail y Yahoo: dónde se exige la cancelación de suscripción con un clic para remitentes masivos
- Webhooks: suscribir un endpoint, verificación de firma y reintentos
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Ver la guíaGetting started with emailExplorar la funcionalidadEmailSeguir la ruta de aprendizajeBuild your first integrationGuía de implementaciónSend your first email
Prueba el ejercicio y obtén un resumen de implementación