URL de suscripción

Cada lista de contactos tiene una URL de suscripción: un endpoint público que añade una persona a la lista sin clave de API. Úsala para conectar a una lista un formulario de suscripción de tu sitio web o una herramienta sin código capaz de enviar una petición JSON.

POST https://api.emailit.com/subscribe/{token}

El token es secreto y propio de la lista. Cualquiera que tenga la URL puede añadir direcciones a la lista, así que trátala como una contraseña.

Encontrar la URL

1. Abre la lista. Ve a Email Marketing›Audiences y selecciona la lista.

2. Copia la URL. Selecciona Subscribe URL y copia la URL del cuadro de diálogo.

Con la API, Obtener una lista de contactos devuelve el mismo valor en token.

Formato de la petición

Envía una petición POST con un cuerpo JSON y Content-Type: application/json. No hace falta la cabecera Authorization.

El endpoint solo lee JSON. Los cuerpos codificados como formulario, que es lo que envía un <form> HTML normal, se rechazan con 400 y «Invalid JSON in request body».

Respuestas

Qué hace un alta

• Dirección nueva: Emailit crea el contacto y lo suscribe a la lista.
• Contacto existente que no está en la lista: Emailit actualiza los nombres y los campos personalizados que has enviado y suscribe el contacto.
• Suscriptor existente que se había dado de baja: Emailit lo vuelve a suscribir.
• Suscriptor existente que está suscrito: no cambia nada salvo la fecha de suscripción, y la respuesta sigue siendo 200.

Las altas mediante la URL de suscripción no envían eventos de webhook subscriber.* ni contact.* y no inician las automatizaciones Added to audience. Tampoco cambian el estado de marketing de un contacto: si el contacto se había dado de baja de forma global, las campañas lo siguen omitiendo hasta que lo vuelvas a suscribir en la página Contacts.

Conectar un formulario de suscripción

La URL de suscripción no tiene protección contra bots y solo acepta JSON. La configuración más segura es enviar el formulario a tu propio servidor, comprobarlo allí y llamar a la URL de suscripción desde el servidor. Así el token no aparece en el código fuente de tu página y puedes bloquear el spam antes de que llegue a tu lista.

1. Añade el formulario a tu página. Envíalo a un endpoint de tu propio sitio. El campo oculto website es un honeypot: las personas no lo ven, pero los bots suelen rellenarlo.

   signup.html

   <form id="signup" method="post" action="/newsletter">
     <label for="email">Email</label>
     <input id="email" name="email" type="email" required>
   
     <label for="first_name">First name</label>
     <input id="first_name" name="first_name" type="text">
   
     <!-- Honeypot: hidden from people, often filled in by bots -->
     <div style="position:absolute;left:-10000px" aria-hidden="true">
       <input name="website" type="text" tabindex="-1" autocomplete="off">
     </div>
   
     <button type="submit">Subscribe</button>
     <p class="status" role="status"></p>
   </form>

2. Procesa el formulario en tu servidor. Descarta los envíos que rellenan el honeypot, comprueba un CAPTCHA si usas uno y reenvía los campos a la URL de suscripción como JSON. Guarda el token en una variable de entorno como EMAILIT_SUBSCRIBE_TOKEN. Consulta los ejemplos de servidor más abajo.

3. Pruébalo. Envía el formulario con tu propia dirección y comprueba que apareces en la tabla de suscriptores de la lista.

Ejemplos de servidor

import express from 'express';

const app = express();

app.post('/newsletter', express.urlencoded({ extended: false }), async (req, res) => {
  // Bots fill in the honeypot. Pretend it worked and stop.
  if (req.body.website) return res.redirect(303, '/thanks');

  const response = await fetch(
    `https://api.emailit.com/subscribe/${process.env.EMAILIT_SUBSCRIBE_TOKEN}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: req.body.email,
        first_name: req.body.first_name || undefined,
      }),
    },
  );

  if (!response.ok) {
    const { error } = await response.json().catch(() => ({}));
    return res.status(response.status).send(error || 'Could not subscribe.');
  }

  res.redirect(303, '/thanks');
});

app.listen(3000);

<?php
// Bots fill in the honeypot. Pretend it worked and stop.
if (!empty($_POST['website'])) {
    header('Location: /thanks', true, 303);
    exit;
}

$token = getenv('EMAILIT_SUBSCRIBE_TOKEN');
$ch = curl_init("https://api.emailit.com/subscribe/{$token}");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'email' => $_POST['email'] ?? '',
        'first_name' => $_POST['first_name'] ?? null,
    ]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) {
    http_response_code($status);
    echo json_decode($body, true)['error'] ?? 'Could not subscribe.';
    exit;
}

header('Location: /thanks', true, 303);

curl "https://api.emailit.com/subscribe/$EMAILIT_SUBSCRIBE_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "first_name": "Ada" }'

Si tu página envía el formulario con JavaScript en lugar de recargar la página entera, llama a tu propio endpoint con fetch y deja la llamada a Emailit en el servidor:

document.querySelector('#signup').addEventListener('submit', async (event) => {
  event.preventDefault();
  const form = new FormData(event.target);
  const response = await fetch('/newsletter', { method: 'POST', body: new URLSearchParams(form) });
  event.target.querySelector('.status').textContent = response.ok
    ? 'Thanks, you are subscribed.'
    : 'Something went wrong. Please try again.';
});

Límite de velocidad y volúmenes mayores

La URL de suscripción acepta 30 peticiones por minuto desde cada dirección IP y devuelve 429 por encima de esa cifra. Cuando tu servidor reenvía todas las altas, todas proceden de la IP de tu servidor, así que las 30 por minuto se aplican a todo tu sitio. Si esperas más, llama en su lugar a Añadir un suscriptor desde tu servidor con una clave de API. Ese endpoint también devuelve 409 para las personas que ya están suscritas e inicia las automatizaciones Added to audience, por ejemplo para enviar un email de bienvenida.

Confirmar las altas

La URL de suscripción añade a las personas de inmediato. Emailit no envía un email de confirmación ni pide a la persona que confirme su dirección (doble opt-in).

Si quieres altas confirmadas, incorpora la confirmación a tu propio flujo: cuando alguien envíe el formulario, guarda la petición en tu servidor y envíale un email con un enlace de confirmación que apunte a tu sitio. Llama a la URL de suscripción solo después de que abra ese enlace.

Restablecer la URL

Restablece el token si la URL se ha filtrado o estás recibiendo altas de spam. La URL antigua deja de funcionar de inmediato y devuelve 404.

1. Abre el cuadro de diálogo. En la página de la lista, selecciona Subscribe URL.

2. Restablece. Selecciona Reset token y confirma. Emailit genera una URL nueva.

3. Actualiza tus integraciones. Sustituye el token en todos los sitios donde lo uses, como la variable EMAILIT_SUBSCRIBE_TOKEN de tu servidor.

El token solo se puede restablecer en el panel.

Ver también