API de email transaccional: envía emails desde tu propio código
Una petición envía un recibo, un cambio de contraseña o una notificación desde tu dominio verificado. Los webhooks firmados avisan a tu app de lo que pasó con cada email.
Qué es una API de email transaccional
Los emails transaccionales son los mensajes uno a uno que tu producto envía por algo que hizo una persona: el recibo de un pedido, un cambio de contraseña, un aviso de envío. Son distintos de las campañas, que envías a una lista. La API REST de Hemero permite a tu backend enviarlos desde los mismos dominios verificados que tus campañas.
Cómo enviar tu primer email por la API
Verifica un dominio
Agrega y verifica un dominio de envío en Dominios. La API solo envía desde direcciones de un dominio que hayas verificado. Mira entregabilidad para ver cómo.
Crea una clave de API
Abre Configuración, luego API, y haz clic en Nueva clave de API. Elige Solo envío para email transaccional o Acceso completo si también quieres gestionar contactos. El token se muestra una sola vez, así que guárdalo bien; Hemero solo conserva un hash. Pueden crear claves los propietarios y administradores.
Envía una petición
Haz un POST a /v1/emails con tu clave como token Bearer. El ejemplo más abajo es la forma real de la petición.
Revisa el resultado
Un email nuevo devuelve 201 con un id y un estado. Usa GET /v1/emails/:id para leer su estado más tarde, o mira Emails recientes de la API en Configuración.
Escucha los eventos
En Configuración, luego Webhooks, agrega un endpoint y elige eventos como email.delivered, email.opened, email.clicked, email.bounced y email.complained.
Ejemplo: enviar un email con curl
Cambia mt_... por tu clave y usa en from una dirección de tu dominio verificado. La URL base es https://hemero.app/v1. Hemero responde 201 con el id del email cuando acepta el mensaje.
curl -X POST https://hemero.app/v1/emails \
-H "Authorization: Bearer mt_..." \
-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>"}'
Qué puede hacer la API
Enviar un email
#POST /v1/emailsCampos: to, from, subject, y html o text (o ambos). Opcionales: replyTo, cabeceras personalizadas y metadatos libres que GET /v1/emails/:id devuelve. From puede ser una dirección o Nombre <dirección> de un dominio verificado.
Reintentos seguros
#idempotenciaAñade una cabecera Idempotency-Key y una petición repetida devuelve el email original en lugar de enviarlo y cobrarlo dos veces.
Hasta 100 de una vez
#POST /v1/emails/batchEnvía una lista de emails en una sola petición. La respuesta indica cuáles se enviaron y cuáles fallaron, con el motivo de cada uno.
Webhooks firmados
#eventosHemero envía un JSON firmado a tu URL. Verifica la cabecera X-Hemero-Signature con el secreto de tu endpoint. Las entregas fallidas se reintentan con espera creciente, y un endpoint que falla 20 veces seguidas se desactiva.
Contactos y listas
#acceso completoCon una clave de Acceso completo también puedes crear y leer contactos, darlos de baja, listar tus listas y formularios y gestionar endpoints de webhooks.
Descripción OpenAPI
#/openapi.jsonUna descripción legible por máquinas de la API está publicada en hemero.app/openapi.json, lista para tu generador de código o tu cliente de API.
Cuánto cuesta
Cada destinatario de cada email por API usa un email de tu cupo, igual que un destinatario de campaña, y se te devuelve si el envío falla. Starter cuesta 19 US$ al mes con 25.000 emails, y los paquetes de pago por uso no vencen; mira los precios. La API en sí no tiene costo extra. Toda cuenta nueva empieza con 500 emails gratis cuando se verifica el email de su propietario.
Límites, sin rodeos
Se rechazan las direcciones suprimidas
Si el destinatario está en tu lista de supresión, la API rechaza el email con un error de suprimido. Eso protege tu reputación y no es algo que convenga esquivar.
Transaccional no es marketing
Hemero no agrega un enlace de baja a los emails por API. Úsala para mensajes que la persona espera. Para promociones, envía una campaña.
Los límites siguen aplicando
El envío se detiene con un error claro si no te quedan emails, tu dominio no está verificado o se alcanza un límite diario o de remitente nuevo. Los emails por API no se retienen por el calentamiento del dominio, pero cuentan para su volumen. Las peticiones tienen un límite de 600 por minuto por clave.
Mantén tu clave en secreto
Quien tenga la clave puede enviar como tu dominio. Usa claves de Solo envío para enviar, revoca una clave en Configuración si se filtra y nunca la pongas en código de navegador.
Preguntas
¿Cómo envío emails con una API?
Verifica un dominio, crea una clave de API en Configuración y haz un POST con un cuerpo JSON con to, from, subject y html a /v1/emails, con una cabecera Authorization Bearer. La respuesta te da el id del email.
¿Qué diferencia hay entre email transaccional y de marketing?
El email transaccional es un mensaje uno a uno que dispara la acción de una persona, como un recibo o un cambio de contraseña. El de marketing es una campaña enviada a una lista. En Hemero el primero va por la API y el segundo por campañas.
¿Puedo enviar el mismo email dos veces por error?
No si envías una cabecera Idempotency-Key. Una petición repetida con la misma clave devuelve el primer email en lugar de enviar otro.
¿Cómo sé si un email se entregó o rebotó?
Lee su estado con GET /v1/emails/:id, o agrega un endpoint de webhook y escucha email.delivered, email.bounced y eventos similares.
¿Hay un archivo OpenAPI?
Sí, en hemero.app/openapi.json. Describe la API pública y se puede importar en la mayoría de los clientes de API.
¿Puedo enviar desde cualquier dirección?
Solo desde direcciones de un dominio que hayas verificado en Hemero. Una petición desde cualquier otro dominio se rechaza.
¿Listo para enviar desde tu código? Crea una cuenta, verifica tu dominio y haz tu primera petición a la API.