Ir al contenido

Guía para desarrolladores · Formularios de suscripción

Crea tu propia experiencia de suscripción.

Conserva tu HTML, diseño y framework. Conecta tu formulario a uno publicado de smartest.email mediante su endpoint público de suscripción.

Esta guía incluye

Configuración pública e inscripciones desde cualquier origen web

Consentimiento, validación, respuestas y límites de solicitudes

Usa la URL de tu formulario.

Crea un formulario con un campo de correo y una casilla de consentimiento obligatorios y publícalo. La pestaña Instalación muestra la URL exacta.

URL base

https://api.smartest.email/api/v1/public/forms/{FORM_ID}

Utiliza la URL que aparece en la pestaña Instalar de tu formulario. Sustituye FORM_ID por el ID de tu formulario publicado en los ejemplos siguientes.

1

Crear

Define los campos y un texto de consentimiento claro.

2

Publicar

Los formularios nuevos son borradores; las rutas públicas devuelven 404 hasta su publicación.

3

Integrar

Usa el código de inserción o llama a los dos endpoints públicos siguientes.

Usa tu propio formulario HTML.

Se admite el envío directo. Crea y publica un formulario en smartest.email para definir campos y consentimiento y usa su ID en tu web. Puedes elegir el tipo integrado sin instalar el widget.

Tu web puede enviar con JavaScript fetch(), o tu servidor puede reenviar la suscripción como JSON. El endpoint público no necesita clave API, token de acceso ni script de smartest.email.

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

Sustituye FORM_ID por el UUID del formulario publicado. Envía Content-Type: application/json con el contenido siguiente.

Solicitud JSON · tras el consentimiento del visitante
{
  "data": {
    "email": "visitor@example.com"
  },
  "consent": true
}

Establece consent según la elección explícita del visitante y muestra el consentimiento y el aviso de privacidad. Mantén consent en el nivel superior; coloca los campos de contacto configurados en data. Incluye todos los campos obligatorios del formulario publicado.

Un formulario HTML simple necesita un adaptador

El endpoint solo acepta JSON. Un <form method="post" action="…"> envía datos codificados en URL o multipart y recibe 415 JSON body required. Usa el ejemplo JavaScript para navegador de abajoo envía a tu servidor para que reenvíe JSON a smartest.email.

Obtener la configuración pública mantiene los textos y la validación alineados con el formulario publicado. No es necesario para cada envío. Tu integración gestiona su mensaje de éxito o redirección; el endpoint siempre responde con JSON.

Muestra los campos publicados.

Este endpoint público no necesita token. Consúltalo al mostrar el formulario y usa los nombres de campos, consentimiento y URL de privacidad en tu interfaz.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}

Devuelve 200 con datos seguros de visualización de un formulario activo. Cada consulta correcta aumenta las vistas; evita el sondeo periódico.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/embed.js

Script de widget integrado o emergente listo para usar. Usa la URL exacta de Instalación si no necesitas una interfaz propia.

GET
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/landing

Página de suscripción alojada de un formulario activo.

GET /api/v1/public/forms/{FORM_ID} · ejemplo de respuesta
{
  "id": "FORM_ID",
  "name": "Newsletter",
  "organizationName": "Example Studio",
  "type": "embedded",
  "fields": [
    { "name": "email", "type": "email", "label": "Email address", "required": true },
    { "name": "consent", "type": "checkbox", "label": "I agree to receive email updates.", "required": true }
  ],
  "styling": {},
  "successAction": {},
  "privacyUrl": "https://example.com/privacy"
}

La respuesta puede incluir más campos configurados, opciones y reglas de validación. successAction describe el comportamiento del widget; el envío directo sigue devolviendo la respuesta JSON genérica siguiente. El script y la página alojada devuelven 404 para formularios borrador, no publicados, no válidos o desconocidos.

Envía el consentimiento con los datos.

Envía JSON tras la elección explícita del visitante de recibir marketing. El consentimiento va en el nivel superior, no dentro de data.

POST
https://api.smartest.email/api/v1/public/forms/{FORM_ID}/submit

Sin token. Envía Content-Type: application/json y {data:{email:...},consent:true}. Devuelve el mismo éxito genérico para direcciones nuevas y existentes.

HTML + JavaScript de navegador · correo y consentimiento
<form id="signup-form">
  <fieldset id="signup-fields" disabled>
    <legend>Subscribe to email updates</legend>
    <label id="email-label" for="signup-email">Email address</label>
    <input id="signup-email" type="email" autocomplete="email" required>
    <label for="signup-consent">
      <input id="signup-consent" type="checkbox" required>
      <span id="consent-label"></span>
    </label>
    <a id="privacy-link" href="/privacy">Privacy notice</a>
    <button id="signup-submit" type="submit">Subscribe</button>
  </fieldset>
  <p id="signup-status" role="status" aria-live="polite"></p>
</form>
<script type="module">
  const endpoint = "https://api.smartest.email/api/v1/public/forms/FORM_ID";
  const form = document.querySelector("#signup-form");
  const fields = document.querySelector("#signup-fields");
  const button = document.querySelector("#signup-submit");
  const status = document.querySelector("#signup-status");
  let ready = false;
  let submitting = false;

  form.addEventListener("submit", async event => {
    event.preventDefault();
    if (!ready || submitting || !form.reportValidity()) return;
    submitting = true;
    button.disabled = true;
    try {
      const response = await fetch(endpoint + "/submit", {
        method: "POST",
        credentials: "omit",
        headers: { "Content-Type": "application/json", "Accept": "application/json" },
        body: JSON.stringify({
          data: { email: document.querySelector("#signup-email").value.trim() },
          consent: document.querySelector("#signup-consent").checked
        })
      });
      const result = await response.json();
      status.textContent = result.message || "Please try again.";
      if (response.ok) form.reset();
    } catch {
      status.textContent = "Please try again.";
    } finally {
      submitting = false;
      button.disabled = false;
    }
  });

  try {
    const response = await fetch(endpoint, { credentials: "omit" });
    if (!response.ok) throw new Error("Signup form unavailable");
    const config = await response.json();
    document.querySelector("#email-label").textContent =
      config.fields.find(field => field.name === "email").label;
    document.querySelector("#consent-label").textContent =
      config.fields.find(field => field.name === "consent").label;
    if (config.privacyUrl) {
      document.querySelector("#privacy-link").href = config.privacyUrl;
    }
    ready = true;
    fields.disabled = false;
  } catch (error) {
    status.textContent = error.message;
  }
</script>

Sustituye FORM_ID por el UUID del formulario y configura el enlace alternativo /privacy a tu propio aviso si el formulario no tiene privacyUrlconfigurada. Este ejemplo cubre los dos campos obligatorios; muestra y envía también los demás campos obligatorios de la configuración publicada.

Respuesta aceptada

JSON
{"success":true,"message":"Thank you for subscribing."}

La respuesta no indica si una dirección existe. Los contactos existentes suscritos y dados de baja mantienen su estado; solo una nueva dirección aceptada añade un suscriptor y un registro de consentimiento.

Envía solo nombres presentes en el array publicado fields . Debes incluir los campos obligatorios. Envía casillas adicionales como booleanos, números como cadenas numéricas y fechas como YYYY-MM-DDy valores de selección exactamente como en options. La API valida de nuevo los datos en el servidor.

La propiedad opcional website en el nivel superior es una trampa antispam. Omítela o déjala vacía en un envío normal. Un valor no vacío devuelve el éxito genérico sin añadir un contacto; no es un campo para la web del visitante.

Gestiona errores y límites de tráfico.

Los endpoints públicos permiten solicitudes GET, POST y OPTIONS entre orígenes con Content-Type y Accept. Usa credentials: omit en el navegador; no hacen falta cookies de cuenta, cabecera Authorization ni clave API.

EstadoSignificado
200Configuración o envío aceptado; una dirección duplicada recibe la misma respuesta.
400 / 415JSON mal formado / la solicitud no es application/json.
404Formulario desconocido, borrador, no publicado o no válido.
409La cuenta ha alcanzado su límite de contactos.
413 / 422Contenido mayor de 16 KiB / consentimiento o datos no válidos.
429Límite alcanzado; el navegador puede usar retry_after en el JSON. Las integraciones de servidor también pueden leer Retry-After.

Los errores usan {"error":true,"message":"..."}; los errores de límite también incluyen retry_after en segundos. Los formularios permiten hasta 30 solicitudes por IP y minuto, incluidos hasta 10 envíos. La política de seguridad de contenido de tu sitio debe permitir https://api.smartest.email en connect-src; el widget integrado también lo necesita en script-src.

Cuando tu propio servidor reenvía los envíos, estos comparten la IP de salida de ese servidor a efectos del límite de solicitudes.

Consentimiento y entrega

Una nueva suscripción aceptada crea un contacto suscrito y guarda el consentimiento, la hora y el origen indicado. Tu interfaz debe mostrar el consentimiento y el aviso de privacidad antes del envío. El origen no prueba la identidad. Este endpoint usa opt-in simple: no envía confirmación ni verifica la propiedad de la dirección.