API de email marketing: envía emails, gestiona contactos y recibe webhooks
Hemero tiene una API REST para enviar emails y gestionar contactos desde tu propio código, y webhooks firmados que avisan a tu servidor cuando alguien se suscribe, se da de baja, rebota, abre o hace clic.
Disponibilidad
La API REST y los webhooks ya están activos en todas las cuentas. Crea una clave en Configuración, pestaña API.
Qué puede hacer la API REST de Hemero
Todos los endpoints están bajo https://hemero.app/v1 y responden JSON. Los errores siempre son un objeto de error con un código y un mensaje. La descripción completa es un archivo OpenAPI en https://hemero.app/openapi.json.
Enviar emails
POST /v1/emails envía un email, POST /v1/emails/batch envía hasta 100 y GET /v1/emails/{id} devuelve el estado de entrega de un email que enviaste por la API.
Contactos
POST /v1/contacts crea o actualiza un contacto con nombre, listas, etiquetas, atributos y zona horaria. GET /v1/contacts/{email} lee uno, GET /v1/contacts los lista del más nuevo al más antiguo con filtros por estado y origen, y POST /v1/contacts/{email}/unsubscribe da de baja y suprime una dirección.
Listas y formularios
GET /v1/lists y GET /v1/forms devuelven los ID y nombres que necesitas para añadir contactos a una lista o para suscribir un webhook a un formulario.
Webhooks
GET, POST y DELETE sobre /v1/webhooks gestionan los endpoints que reciben eventos, así que una herramienta o un script de despliegue puede registrarse sola.
Claves de API y acceso
Los propietarios y administradores crean las claves en Configuración, pestaña API. Envía la clave como token bearer: Authorization: Bearer mt_… La clave se muestra una sola vez al crearla, Hemero guarda solo un hash y puedes revocarla cuando quieras. Cada clave tiene un alcance: solo envío, que permite enviar emails, o acceso total, que además permite contactos, listas, formularios y webhooks. Las peticiones están limitadas a 600 por minuto y por clave.
Enviar un email con curl
El remitente debe ser una dirección de un dominio que hayas verificado en Hemero. El cuerpo necesita html, text o ambos. La cabecera Idempotency-Key es opcional: si envías otra vez la misma clave, recibes el resultado original en lugar de enviar un segundo email.
curl -X POST https://hemero.app/v1/emails \
-H "Authorization: Bearer mt_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1234" \
-d '{"to":"[email protected]","from":"[email protected]",
"subject":"Your order shipped","html":"<p>On its way!</p>"}'
Un email nuevo responde 201 con su id y su estado. Cada email descuenta un email de tu saldo. Se rechazan los destinatarios de tu lista de supresión y los remitentes de un dominio sin verificar.
Webhooks para eventos de email
Añade un endpoint en Configuración, pestaña Webhooks, o con POST /v1/webhooks, y elige los eventos que quieres. La URL debe ser https. Hemero envía un POST con un cuerpo JSON con el nombre del evento, la hora y los datos.
Eventos de contactos
contact.subscribed, contact.unsubscribed, contact.bounced, contact.complained y form.submitted. Un envío de formulario se notifica cuando queda confirmado, así que con doble confirmación llega cuando la persona confirma.
Eventos de email, campañas y automatizaciones
email.delivered, email.opened, email.clicked, email.bounced y email.complained, además de campaign.sent, campaign.paused y automation.paused, por ejemplo cuando Hemero pausa un envío para proteger tu reputación.
Firma
Cada envío lleva una cabecera X-Hemero-Signature con una marca de tiempo y un HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo sin modificar, calculado con el secreto de tu endpoint. Recalcúlalo en tu servidor y compáralo. El secreto se muestra una vez y puedes rotarlo desde Configuración.
Reintentos
Un envío tiene 10 segundos para responder con un código de éxito. Los que fallan se reintentan con una espera creciente, hasta seis intentos. Un endpoint que falla 20 veces seguidas se desactiva, y puedes volver a activarlo. Puedes tener hasta 20 endpoints, y la pestaña Webhooks muestra los envíos recientes y puede mandar una prueba.
Usa Hemero desde un asistente de IA
Hemero también ofrece un conector MCP para que Claude, ChatGPT o Cursor trabajen en tu cuenta. La instalación es un clic y un inicio de sesión en el navegador: mira Agentes de IA (MCP). El asistente actúa con tu rol, se puede limitar a solo lectura y cada conexión se puede revocar.
Lo que la API no hace
La API REST no crea ni envía campañas, no edita plantillas ni segmentos, no crea formularios, no importa contactos en bloque y no borra contactos: trabajas con los contactos de uno en uno, y darlos de baja es lo más parecido a quitarlos. Las campañas y automatizaciones se crean en la app de Hemero. La API no se salta las protecciones: los dominios sin verificar, las direcciones suprimidas y los límites de envío también se aplican. Los emails que envías con ella gastan tu saldo de emails como cualquier otro: mira los precios.
Preguntas
¿Hemero tiene una API de email marketing?
Sí. La API REST envía emails y gestiona contactos, listas y webhooks, y está descrita en un archivo OpenAPI en hemero.app/openapi.json. Las campañas en sí se crean en la app.
¿Cómo me autentico en la API de Hemero?
Crea una clave de API en Configuración, pestaña API, y envíala como Authorization: Bearer seguido de la clave. Usa una clave de solo envío para el código que solo envía emails.
¿Cómo verifico un webhook de Hemero?
Lee la cabecera X-Hemero-Signature, que contiene una marca de tiempo y una firma. Calcula un HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo de la petición sin modificar con el secreto de tu endpoint, y compáralo con la firma.
¿Qué pasa si mi endpoint de webhooks está caído?
Hemero reintenta el envío con una espera creciente, hasta seis intentos. Tras 20 fallos seguidos, el endpoint se desactiva hasta que lo vuelvas a activar.
Construye sobre una plataforma de email con las protecciones incluidas. Crea tu cuenta, genera una clave y envía tu primer email desde código.