> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Añadir un formulario de suscripción con doble confirmación

> Coloca en tu sitio un formulario que añade suscriptores a una lista de Notifuse solo después de que confirmen su dirección.

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.

### 1. 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 `/subscribe` solo 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:

```html
<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](https://www.notifuse.com/docs/assets/screenshots/list_double_optin.png)

### 2. Añade el formulario a tu sitio

Esta página es un ejemplo completo que funciona. Sustituye `YOUR_NOTIFUSE_HOST`, `YOUR_WORKSPACE_ID` y `YOUR_LIST_ID`, y luego pégala en tu sitio o ábrela como archivo para probarla.

```html signup-form.html
<!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.

### 3. Cómo funciona la llamada de suscripción

Si construyes el formulario con tu propio framework, esta es la llamada que debes reproducir. `POST /subscribe` es público: no necesita clave API, así que puedes llamarlo sin riesgo desde el navegador.

```json
{
  "workspace_id": "YOUR_WORKSPACE_ID",
  "contact": {
    "email": "visitor@example.com",
    "first_name": "Ada"
  },
  "list_ids": ["YOUR_LIST_ID"]
}
```

Son obligatorios `workspace_id`, `contact` con un `email` válido y al menos una entrada en `list_ids`. Los demás campos del contacto, como `first_name` o `last_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_ids` no 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-After` indica 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 `200` y 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-Origin` a partir de la variable de entorno `CORS_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.

### 4. 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](https://www.notifuse.com/es/docs/guides/welcome-sequence.md).

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

1. 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.
2. Abre **Contactos**, busca tu dirección y ábrela. En su panel **Listas**, la lista aparece como **Pendiente**.
3. Abre el correo de confirmación y haz clic en su enlace. Se abre el centro de notificaciones y confirma la suscripción.
4. 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](https://www.notifuse.com/es/docs/features/logs.md).

![Ficha de un contacto: la lista Newsletter aparece como Pendiente hasta que el contacto confirma](https://www.notifuse.com/docs/assets/screenshots/contact_pending.png)

## 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 `error` de 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 como `contact.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 indica `Retry-After`.
- **`500` "Failed to subscribe to lists"**: revisa el ID de lista en `list_ids` y que haya un proveedor de correo definido para **Correos de marketing**, porque el correo de confirmación se envía durante la solicitud.
- **`200` pero ningún correo de confirmación**: busca un envío fallido en **Registros** › **Mensajes**. Una dirección desechable recibe `200` y ningún correo, por diseño.
- **El navegador bloquea la solicitud (CORS)**: comprueba que `NOTIFUSE_HOST` es correcto y accesible. En una instancia autoalojada, comprueba que `CORS_ALLOW_ORIGIN` incluye 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](https://www.notifuse.com/es/docs/guides/welcome-sequence.md) que se dispare con **Confirmado**.
- [Listas](https://www.notifuse.com/es/docs/features/lists.md) explica la configuración de las listas y los estados de suscripción.
- [Centro de notificaciones](https://www.notifuse.com/es/docs/features/notification-center.md) es la página que tus suscriptores usan para confirmar y gestionar sus suscripciones.
