Guía práctica
URL de suscripción
Cada lista de contactos tiene una URL de suscripción que añade personas sin clave de API. Conoce el formato de la petición, cómo cambia con el doble opt-in, cómo llamarla de forma segura, sus límites y cómo restablecerla.
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. Es un endpoint para peticiones POST, no una página: si la abres en un navegador, no se suscribe nadie.
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
-
Abre la lista. Ve a Email MarketingAudiences y selecciona la lista.
-
Copia la URL. Selecciona Subscribe URL y copia la URL del cuadro de diálogo. El cuadro de diálogo también muestra una petición de ejemplo e indica si el doble opt-in está activado.
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.
emailstringobligatoriofirst_namestringlast_namestringcustom_fieldsobjectEl 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
| Estado | Cuerpo | Cuándo |
|---|---|---|
200 |
{ "message": "Subscribed successfully", "status": "subscribed" } |
El doble opt-in está desactivado y la persona se ha añadido, se ha vuelto a suscribir o ya estaba suscrita. |
202 |
{ "message": "Check your inbox to confirm the subscription.", "status": "pending" } |
El doble opt-in está activado: se ha enviado el email de doble opt-in y la persona se une cuando hace clic en su enlace. Las personas que ya están suscritas, o que se han vuelto a dar de alta justo después de la primera vez, reciben la misma respuesta sin un email nuevo. |
400 |
{ "error": "Missing required field: email" } o { "error": "Invalid email format" } |
Falta el email o tiene un formato incorrecto, o el cuerpo no es JSON. |
403 |
{ "error": "Workspace suspended" } o { "error": "Workspace scheduled for deletion" } |
El espacio de trabajo está suspendido o programado para su eliminación, así que no acepta altas. |
404 |
{ "error": "Audience not found" } |
El token es incorrecto o se ha restablecido, o la lista está archivada. |
422 |
{ "error": "...", "usage": { ... } } |
La lista ha alcanzado su límite de suscriptores. |
429 |
Más de 30 peticiones en un minuto desde la misma dirección IP o, cuando el doble opt-in o el email de confirmación están activados, demasiadas altas en la lista o desde tu red en la última hora. Vuelve a intentarlo cuando pasen los segundos que indica la cabecera retry-after. |
|
503 |
{ "error": "The double opt-in email could not be sent. Please try again later.", "code": "..." } |
El doble opt-in está activado, pero el email de doble opt-in no se ha podido enviar, por ejemplo porque el dominio de envío no está verificado o el espacio de trabajo no tiene créditos. La persona no se añade. |
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, y la respuesta sigue siendo
200.
Con el doble opt-in activado, un contacto nuevo se crea de inmediato, los nombres y los campos personalizados de un contacto existente no se modifican, y la suscripción espera hasta que la persona hace clic en el enlace del email de doble opt-in.
Una suscripción nueva envía eventos de webhook subscriber.created (o subscriber.updated si la persona se vuelve a suscribir), inicia las automatizaciones Added to audience y envía el email de confirmación de la lista si está activado. Las altas no envían eventos contact.* y no 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.
-
Añade el formulario a tu página. Envíalo a un endpoint de tu propio sitio. El campo oculto
websitees un honeypot: las personas no lo ven, pero los bots suelen rellenarlo.<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> -
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. -
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 >= 300) {
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. Cuando el doble opt-in o el email de confirmación están activados, las altas también tienen límites de uso razonable por lista y por red, porque cada una envía un email. 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, y acepta "double_opt_in": true para pedir la confirmación.
Confirmar las altas
Activa el doble opt-in en la pestaña Settings de la lista para que todas las altas mediante la URL de suscripción confirmen primero su dirección. La URL devuelve entonces 202, Emailit envía el email de doble opt-in desde tu dominio verificado y la persona se une cuando hace clic en su enlace. Tu formulario puede mostrar «Revisa tu bandeja de entrada» cuando recibe 202.
Para dar la bienvenida a las personas una vez que están en la lista, activa el email de confirmación de la lista.
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.
-
Abre el cuadro de diálogo. En la página de la lista, selecciona Subscribe URL.
-
Restablece. Selecciona Reset token y confirma. Emailit genera una URL nueva.
-
Actualiza tus integraciones. Sustituye el token en todos los sitios donde lo uses, como la variable
EMAILIT_SUBSCRIBE_TOKENde tu servidor.
El token solo se puede restablecer en el panel.