Al terminar tendrás en tu sitio web un formulario que suscribe a los visitantes a una lista de Notifuse, les envía un correo de confirmación y los marca como activos cuando hacen clic en el enlace.
Antes de empezar
- Un espacio de trabajo con un proveedor de correo definido para Correos de marketing en Configuración › Integraciones. Los correos de confirmación salen por ese proveedor.
- El ID de tu espacio de trabajo. Es el ID que elegiste al crear el espacio de trabajo y aparece en la URL de la consola después de
/console/workspace/. - La dirección de tu instancia de Notifuse, la misma en la que abres la consola. Los ejemplos usan
https://YOUR_NOTIFUSE_HOST. - Una página de tu sitio donde puedas añadir HTML y JavaScript.
Crea una lista pública con doble confirmación
Abre Contactos y haz clic en Nueva lista, junto a Listas en la columna izquierda. Rellena:
- Nombre: por ejemplo “Newsletter”.
- ID: se deriva del nombre, o haz clic en Modificar para escribir el tuyo. Solo letras y cifras, 32 caracteres como máximo. Tu formulario envía este ID, y no se puede cambiar después de crear la lista.
En Suscripción, activa los dos interruptores:
- Lista pública: el endpoint público
/subscribesolo acepta listas públicas. - Doble confirmación: los nuevos suscriptores reciben un correo de confirmación y quedan en Pendiente hasta que hacen clic en su enlace. Este interruptor requiere una Plantilla de confirmación.
En Plantilla de confirmación, elige una plantilla de la categoría Suscripción. Si no tienes ninguna, haz clic en Nueva plantilla en el selector y parte del modelo Confirmación de suscripción. Se abre en el editor de plantillas y vuelve seleccionada cuando la guardas.
El correo de confirmación debe enlazar a
{{ confirm_subscription_url }}. El modelo ya tiene un botón que apunta ahí. En tu propia plantilla, escribe:<a href="{{ confirm_subscription_url }}">Confirm your subscription</a>Haz clic en Crear la lista.
El panel Nueva lista con Lista pública y Doble confirmación activados, y la plantilla de confirmación por elegir Añade el formulario a tu sitio
Esta página es un ejemplo completo que funciona. Sustituye
YOUR_NOTIFUSE_HOST,YOUR_WORKSPACE_IDyYOUR_LIST_ID, y luego pégala en tu sitio o ábrela como archivo para probarla.<!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Subscribe to our newsletter</title> <style> .signup { max-width: 420px; margin: 2rem auto; font-family: system-ui, sans-serif; } .signup label { display: block; margin: 0.75rem 0 0.25rem; font-size: 0.9rem; } .signup input { width: 100%; padding: 0.6rem; border: 1px solid #ccc; border-radius: 6px; box-sizing: border-box; } .signup button { margin-top: 1rem; width: 100%; padding: 0.7rem; border: 0; border-radius: 6px; background: #4f46e5; color: #fff; font-size: 1rem; cursor: pointer; } .signup button:disabled { opacity: 0.6; cursor: wait; } .signup .message { margin-top: 1rem; font-size: 0.9rem; } .signup .message.error { color: #b91c1c; } .signup .message.success { color: #15803d; } </style> </head> <body> <form class="signup" id="signup-form" novalidate> <h2>Subscribe to our newsletter</h2> <label for="first-name">First name (optional)</label> <input id="first-name" name="first_name" type="text" autocomplete="given-name" /> <label for="email">Email</label> <input id="email" name="email" type="email" autocomplete="email" required /> <button type="submit">Subscribe</button> <p class="message" id="signup-message" role="status" aria-live="polite"></p> </form> <script> const NOTIFUSE_HOST = 'https://YOUR_NOTIFUSE_HOST' const WORKSPACE_ID = 'YOUR_WORKSPACE_ID' const LIST_ID = 'YOUR_LIST_ID' const form = document.getElementById('signup-form') const button = form.querySelector('button') const message = document.getElementById('signup-message') function show(text, kind) { message.textContent = text message.className = 'message ' + kind } form.addEventListener('submit', async (event) => { event.preventDefault() const email = form.email.value.trim() const firstName = form.first_name.value.trim() if (!form.email.checkValidity() || email === '') { show('Please enter a valid email address.', 'error') return } const contact = { email } if (firstName) contact.first_name = firstName button.disabled = true show('Subscribing…', '') try { const response = await fetch(NOTIFUSE_HOST + '/subscribe', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ workspace_id: WORKSPACE_ID, contact, list_ids: [LIST_ID] }) }) if (response.ok) { form.reset() show('Almost done: check your inbox and click the link to confirm your subscription.', 'success') } else if (response.status === 429) { show('Too many attempts. Please try again in a few minutes.', 'error') } else { const result = await response.json().catch(() => ({})) show(result.error || 'Something went wrong. Please try again.', 'error') } } catch (error) { show('Network error. Please check your connection and try again.', 'error') } finally { button.disabled = false } }) </script> </body> </html>El mensaje de éxito pide al visitante que revise su bandeja de entrada: en una lista con doble confirmación, no queda suscrito hasta que hace clic en el enlace.
Cómo funciona la llamada de suscripción
Si construyes el formulario con tu propio framework, esta es la llamada que debes reproducir.
POST /subscribees público: no necesita clave API, así que puedes llamarlo sin riesgo desde el navegador.{ "workspace_id": "YOUR_WORKSPACE_ID", "contact": { "email": "visitor@example.com", "first_name": "Ada" }, "list_ids": ["YOUR_LIST_ID"] }Son obligatorios
workspace_id,contactcon unemailválido y al menos una entrada enlist_ids. Los demás campos del contacto, comofirst_nameolast_name, son opcionales.Las respuestas:
Estado Cuerpo Cuándo 200{"success": true}La solicitud se aceptó. 400{"error": "list is not public"}Una lista de list_idsno es pública.400{"error": "invalid contact: invalid email format"}El correo está mal formado. Un campo que falta tiene su propio mensaje, como workspace_id is required.429{"error": "Too many subscription attempts. …"}Se alcanzó un límite de frecuencia. La cabecera Retry-Afterindica la espera en segundos.500{"error": "Failed to subscribe to lists"}Cualquier otro caso, como un ID de lista desconocido o un correo de confirmación que no se pudo enviar. Se aplican además algunas reglas:
- Los límites son 10 solicitudes por minuto para una misma dirección de correo y 50 por minuto desde una misma dirección IP.
- Las direcciones desechables se descartan sin aviso. La respuesta sigue siendo
200y no se crea ningún contacto. - Una solicitud anónima nunca sobrescribe los campos de un contacto que ya está en el espacio de trabajo.
- Un contacto pendiente que vuelve a enviar el formulario recibe otra vez el correo de confirmación. Un contacto activo sigue activo y no recibe nada.
Para CORS, Notifuse define
Access-Control-Allow-Origina partir de la variable de entornoCORS_ALLOW_ORIGIN, que vale*por defecto. Si alojas Notifuse tú mismo y la restringes, añade el origen de tu sitio web. La variable acepta una lista separada por comas.Qué pasa después del envío
En una lista con doble confirmación, Notifuse añade al visitante a la lista como Pendiente y le envía la plantilla de confirmación.
El enlace de ese correo abre el centro de notificaciones, que confirma la suscripción. El contacto pasa de Pendiente a Activo, y Notifuse registra un evento
list.confirmed.Es el evento en el que apoyarte. Una automatización con el disparador Lista › Confirmado solo llega a quienes confirmaron. Consulta Crear una secuencia de bienvenida.
Los contactos que añades desde la consola o con una clave API no reciben el correo de confirmación y pasan directamente a Activo. La excepción es un contacto que se había dado de baja de la lista: si lo vuelves a suscribir desde el formulario, la consola o la API, vuelve a Pendiente y recibe el correo de confirmación.
Comprobar que funciona
- Envía el formulario con una dirección cuyo correo puedas leer. El formulario debe mostrar el mensaje que pide revisar la bandeja de entrada.
- Abre Contactos, busca tu dirección y ábrela. En su panel Listas, la lista aparece como Pendiente.
- Abre el correo de confirmación y haz clic en su enlace. Se abre el centro de notificaciones y confirma la suscripción.
- Vuelve a abrir tu contacto: la lista aparece ahora como Activo. En la pestaña Actividad, el filtro Listas y segmentos muestra el cambio.
El correo de confirmación también aparece en Registros, en la pestaña Mensajes, con el origen Otro. Consulta Registros.
Buenas prácticas
- Indica en el formulario que enviarás un correo de confirmación, y haz que el mensaje de éxito remita a la bandeja de entrada.
- Enlaza tu política de privacidad junto al formulario.
- Mantén el correo de confirmación breve, con el enlace como botón principal. Su versión de texto también debe incluir
{{ confirm_subscription_url }}. - Muestra el campo
errorde una respuesta fallida, o un mensaje claro propio para cada estado. - Prueba el formulario en un móvil además de en un ordenador.
Solución de problemas
400“list is not public”: en Contactos, haz clic en la lista en la columna, luego en Editar lista, y activa Lista pública.400“invalid contact: invalid email format”: la dirección está mal formada. Revisa el campo que tu formulario envía comocontact.email.429“Too many subscription attempts”: alcanzaste el límite de 10 por correo o 50 por IP por minuto, algo fácil durante las pruebas. Espera el tiempo que indicaRetry-After.500“Failed to subscribe to lists”: revisa el ID de lista enlist_idsy que haya un proveedor de correo definido para Correos de marketing, porque el correo de confirmación se envía durante la solicitud.200pero ningún correo de confirmación: busca un envío fallido en Registros › Mensajes. Una dirección desechable recibe200y ningún correo, por diseño.- El navegador bloquea la solicitud (CORS): comprueba que
NOTIFUSE_HOSTes correcto y accesible. En una instancia autoalojada, comprueba queCORS_ALLOW_ORIGINincluye el origen de tu sitio. - El contacto sigue en Pendiente: no ha hecho clic en el enlace. Si envía otra vez el formulario con la misma dirección, se le reenvía el correo de confirmación.
Próximos pasos
- Crea una secuencia de bienvenida que se dispare con Confirmado.
- Listas explica la configuración de las listas y los estados de suscripción.
- Centro de notificaciones es la página que tus suscriptores usan para confirmar y gestionar sus suscripciones.
