API de email transaccional: cómo elegirla e integrarla

Imagine que su tienda confirma un pedido y la API de email transaccional devuelve una respuesta correcta. Horas después, el cliente pregunta por la confirmación y atención al cliente solo encuentra «solicitud aceptada». Falta saber qué ocurrió con ese mensaje.

Este ejemplo ilustra el objetivo de la integración: relacionar el evento de negocio, la solicitud y el resultado disponible. Esta guía explica cómo evaluar una API, conectarla con su aplicación, registrar sus eventos y resolver errores antes de pasar a producción.

Qué es una API de email transaccional y cuándo usarla

Una API de email transaccional , también denominada transactional email API , permite que una aplicación solicite el envío de mensajes asociados a eventos concretos: un pedido confirmado, una factura disponible o una solicitud de restablecimiento de contraseña. La aplicación decide el destinatario y el contenido; el servicio de correo procesa la solicitud e informa de los resultados que puede observar.

Este uso de una API de correo electrónico no se limita a operaciones de pago. Si necesita revisar los casos básicos, puede consultar los tipos de emails transaccionales .

API y SMTP: elegir según la integración existente

La decisión depende del sistema y del proveedor. SMTP también puede disponer de informes y webhooks : por ejemplo, Amazon SES permite publicar eventos de mensajes enviados mediante API o SMTP en su sistema de seguimiento .

Si su integración SMTP cubre los requisitos operativos, mantenerla puede ser razonable. El cambio merece una prueba cuando los parámetros, la gestión de errores o la relación con los eventos resulten difíciles de mantener.

Cómo evaluar una API de email transaccional

Antes de programar, convierta los requisitos en pruebas. Para confirmar pedidos, importa conocer qué ocurre si el sistema recibe dos veces el mismo evento o pierde la respuesta del proveedor.

Para una empresa sujeta al RGPD , esta revisión incluye la minimización de datos, el contrato del artículo 28 y, cuando proceda, las transferencias internacionales. Una ubicación de alojamiento no acredita por sí sola el cumplimiento.

En EngageLab, la cuota diaria documentada puede variar. Compruebe la capacidad de su cuenta y el margen para picos; no confunda volumen contratado con ritmo de envío permitido. Para comparar proveedores completos, consulte la comparativa de plataformas de email transaccional .

Cómo integrar una API de email transaccional paso a paso

El siguiente recorrido utiliza EngageLab Email como ejemplo para preparar el dominio, crear las credenciales y relacionar cada solicitud con los registros de la aplicación.

Preparar el dominio, las credenciales y los datos

En EngageLab, la guía de configuración de envío sitúa el dominio en Configuración de envío → Nombre de dominio (Setting → Domain en la documentación en inglés). Añada su dominio y copie en el DNS los registros que muestre su cuenta. La documentación distingue los estados Unverified , Usable y Verified ; exige SPF, DKIM y MX para los registros obligatorios. Verifique el resultado antes de asociarlo al API_USER.

Revise también DMARC y su alineación. Los requisitos de Gmail cambian según el volumen: para remitentes masivos a cuentas personales exige SPF, DKIM y DMARC. Autenticar el dominio no garantiza la bandeja de entrada.

En Configuración de envío → API USER , cree un API_USER de tipo Activador (trigger ) vinculado al dominio y genere su API_KEY. Guarde las credenciales en el servidor, fuera del código público. Prepare un buzón de prueba controlado y una plantilla con versión. Para el pedido del ejemplo, registre antes del envío el evento, el destinatario, la versión y una clave única de notificación.

Enviar una solicitud con EngageLab

Para enviar correos por API se utiliza POST /v1/mail/send . Configure las variables de entorno del ejemplo: usuario, clave y URL base de la región de su cuenta. La documentación del envío publica las direcciones de Singapur, Turquía y Estados Unidos.

Ejemplo didáctico basado en documentación, sin prueba en una cuenta real. Sustituya las direcciones reservadas por su remitente configurado y su buzón de prueba. Con sandbox: true se validan parámetros, pero no se entrega correo.

curl --request POST \
  "${ENGAGELAB_EMAIL_BASE_URL:?Configurar URL regional}/v1/mail/send" \
  --user "${ENGAGELAB_API_USER:?Configurar usuario}:${ENGAGELAB_API_KEY:?Configurar clave}" \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data-binary @- <<'JSON'
{
  "from": "Tienda Ejemplo <pedidos@mail.example.com>",
  "to": ["prueba@example.net"],
  "body": {
    "subject": "Confirmación del pedido 4821",
    "content": {
      "html": "<p>Su pedido 4821 ha quedado confirmado.</p>",
      "text": "Su pedido 4821 ha quedado confirmado."
    },
    "settings": {
      "send_mode": 0,
      "return_email_id": true,
      "sandbox": true
    }
  },
  "custom_args": {
    "business_event_id": "evt-pedido-4821",
    "notification_type": "order_confirmation"
  },
  "request_id": "demo-sandbox-pedido-4821-v1"
}
JSON

El identificador de negocio permite relacionar la notificación con el pedido sin incluir su contenido completo. Para la prueba de entrega, cambie sandbox a false y asigne un request_id nuevo, distinto del ensayo de validación. Ese paso sí solicita un envío.

Guardar la respuesta y relacionarla con el evento

Una respuesta de aceptación puede tener esta estructura; los identificadores siguientes son ficticios y corresponden al ensayo de envío, no a una entrega comprobada:

{
  "email_ids": ["demo-email-4821"],
  "request_id": "pedido-4821-confirmacion-v1"
}

Al enviar emails por API, guarde el estado HTTP, el resultado, la hora y los identificadores junto a la notificación. Si falta la respuesta, registre «resultado desconocido». Evite que una excepción del cliente borre el hecho de que la solicitud pudo salir. Al terminar esta fase debe poder localizar el intento desde el pedido, aunque todavía no conozca la entrega.

Cómo seguir los envíos con webhooks de entrega

Un webhook comunica eventos de forma asíncrona. La aplicación debe interpretar cada uno por su significado, no resumir todo como «enviado».

La protección de la privacidad de Mail limita la interpretación de las aperturas. Su ausencia no justifica reenviar una confirmación.

Relacionar el evento con el pedido

En Send Settings → WebHook , configure la URL receptora y los eventos necesarios. Este fragmento simplificado de la estructura de EngageLab utiliza datos ficticios y omite campos:

{
  "server": "email",
  "message_id": "demo-email-4821",
  "itime": 1794484800000,
  "status": {
    "message_status": "delivered",
    "status_data": { "email_id": "demo-email-4821" }
  },
  "custom_args": {
    "business_event_id": "evt-pedido-4821",
    "notification_type": "order_confirmation"
  }
}

El estado está en status.message_status . En este caso, status.status_data.email_id enlaza con la respuesta inicial. En el evento de aceptación se utiliza email_ids , en plural; los eventos de interacción tienen otra estructura.

Validar, guardar y confirmar la recepción

Utilice HTTPS y verifique la firma según el procedimiento oficial : calcula MD5 de la concatenación de X-WebHook-Timestamp , X-WebHook-AppKey y la APP KEY. Esta última es el secreto; no debe confundirse con la cabecera AppKey. Aplique controles contra repeticiones compatibles con las reentregas legítimas.

Tras validar y guardar el evento de forma duradera, devuelva HTTP 200 dentro de los 3 segundos documentados. Procese después las tareas lentas. Si no puede guardarlo, no confirme una recepción satisfactoria.

El procesamiento debe tolerar duplicados. message_id no está documentado como identificador único de cada evento: deduplicar solo por él podría eliminar estados distintos. Para detectar reentregas idénticas, pruebe una clave que combine mensaje, tipo, hora de origen y huella del contenido normalizado. Valide que no elimine eventos legítimos. Mantenga el historial y evite que un sent recibido tarde sustituya una entrega ya registrada. Limite el acceso y la conservación de estos datos.

Cómo gestionar errores, reintentos y duplicados

Antes de repetir una solicitud, clasifique qué sabe de ella. Distinga el estado HTTP de los códigos internos del proveedor y de los errores de entrega recibidos después.

Los ejemplos de códigos proceden de la documentación de envío y de las reglas de la API . Un error 5xx tampoco debe interpretarse automáticamente como prueba de que no hubo aceptación.

Hay tres mecanismos distintos: la aplicación repite una llamada a la API; el servicio de correo reintenta su entrega; el proveedor reenvía un webhook sin confirmar. Reenviar un webhook no vuelve a enviar el email. Antes de crear otro mensaje, compruebe si el original sigue en proceso.

Dos casos que debe resolver la aplicación

El pedido dispara dos veces la confirmación. Reserve de forma atómica una notificación única por evento, tipo y destinatario, por ejemplo mediante una restricción en la base de datos. Dos procesos concurrentes deben encontrar el mismo registro. Si necesita reintentar la misma solicitud, mantenga su identificador y su contenido.

EngageLab documenta que request_id evita repeticiones durante 1 hora y devuelve el resultado anterior. Esa ventana complementa la deduplicación del negocio; no la sustituye. No reutilice la clave para contenido diferente ni presuponga protección después de ese plazo. Valide este comportamiento en su integración.

La solicitud de restablecimiento agota el tiempo de espera. Conserve el resultado como desconocido y consulte registros o eventos. Dentro de la ventana aplicable, puede repetir la misma solicitud con la misma clave. Si ya caducó el enlace o se completó el cambio de contraseña, detenga los nuevos intentos. La aplicación debe rechazar el enlace caducado aunque un correo ya aceptado llegue tarde.

Si el contrato permite reintentos, configure esperas progresivas, cierta variación aleatoria y un máximo; respete las indicaciones del servicio. Al agotar el plazo, cierre o escale el caso con un motivo registrado. No convierta una consulta sin resultados o la falta de apertura en una orden de reenvío.

Qué comprobar antes de pasar a producción

Complete esta matriz con buzones controlados y simulación de fallos. Para probar direcciones inválidas o bloqueos, utilice respuestas simuladas o un entorno autorizado; no genere envíos a terceros. Cada fila necesita una evidencia enlazada, un responsable concreto y un resultado.

Añada una prueba de firma incorrecta: el receptor debe rechazarla sin modificar el pedido. Compruebe también que una reentrega legítima no queda bloqueada por sus controles.

Acuerde umbrales con el equipo: antigüedad de solicitudes sin resultado, retraso de callbacks, errores, cuotas y duplicados. Mida por separado el tiempo desde el evento de negocio hasta la aceptación y desde la generación del webhook hasta su recepción.

Calcule la tasa de entrega como entregas confirmadas divididas entre mensajes únicos aceptados para envío real de la misma cohorte, con un plazo de observación definido. Excluya sandbox y muestre los pendientes sin retirarlos del denominador. Lleve aparte las solicitudes cuya aceptación desconoce. En un restablecimiento, mida además la acción confirmada por el backend. Asigne quién recibe la alerta y qué evidencia necesita para intervenir.

Preguntas frecuentes sobre la API de email transaccional

¿Necesito una API si mi aplicación ya envía correos por SMTP?

No necesariamente. Mantenga SMTP si permite cubrir envío, seguimiento y errores con un mantenimiento asumible. Una prueba con su flujo más exigente ayudará a justificar el cambio.

¿Una respuesta correcta de la API confirma la entrega del email?

No. Confirma la aceptación de la solicitud según el contrato del servicio. La entrega requiere evidencia posterior y tampoco demuestra la ubicación en la bandeja de entrada.

¿Cómo se evitan los correos duplicados al reintentar una solicitud?

Combinando una notificación única en la aplicación con la deduplicación documentada del proveedor. Conserve la misma clave para la misma solicitud y controle su caducidad; crear otra clave en cada intento anula esa protección.

¿Qué hacer si no llegan los webhooks?

Revise la suscripción, la URL, el acceso y las respuestas del receptor. Contraste después con los registros: los reintentos del webhook son limitados. La consulta de estados de EngageLab documenta caché de 10 minutos y un límite de 60 consultas por minuto y cuenta: úsela para reconciliar respetando esas condiciones. La ausencia de un callback no prueba un fallo de envío.

¿Se pueden añadir promociones a un email transaccional?

Solo tras revisar los requisitos aplicables a las comunicaciones comerciales. En España, el artículo 21 de la LSSI exige solicitud o autorización previa, con una excepción limitada para relaciones contractuales anteriores, datos obtenidos lícitamente y productos o servicios propios similares; también exige oposición sencilla y gratuita. Etiquetar el mensaje como transaccional no elimina esas condiciones. Mantener separadas las promociones facilita su gestión.

La integración estará preparada cuando su equipo pueda explicar qué pasó con cada aviso, qué evidencia lo acredita y qué acción corresponde. Empiece con una confirmación de pedido y complete el recorrido antes de ampliar los envíos.