Tu aplicación envía datos estructurados a un endpoint HTTP y recibe una respuesta con el resultado del mensaje o un error. Esa solicitud y respuesta son la superficie de trabajo de una API de correo electrónico.
¿Qué gestiona una API de correo electrónico?
Un endpoint de envío acepta destinatarios, un asunto y contenido en texto o HTML. También puede aceptar encabezados, etiquetas, plantillas y archivos adjuntos cuando el proveedor los admite.
Un endpoint de eventos o webhook informa lo que ocurrió después de la aceptación. Los eventos comunes incluyen entrega, rebote, queja, apertura y clic. Una API de recepción convierte el correo entrante en mensajes estructurados para tu aplicación en lugar de obligarte a consultar un buzón.
¿En qué se diferencia una API de correo electrónico de SMTP?
SMTP requiere que tu aplicación abra una conexión, se autentique, envíe comandos y lea códigos de respuesta. Una API de correo electrónico usa solicitudes HTTP en su lugar, así que una biblioteca cliente puede encargarse de la reutilización de conexiones, la codificación JSON, los reintentos y el análisis de respuestas.
Elige una API cuando tu aplicación ya usa HTTP, necesita eventos estructurados o se ejecuta en un entorno donde abrir conexiones SMTP resulta incómodo. Elige un relay SMTP cuando una biblioteca de correo o un servidor de correo existente ya habla SMTP. Las dos vías pueden entregar el mismo mensaje.
| Tarea | API de envío | Relay SMTP | API de buzón |
|---|---|---|---|
| Enviar un mensaje | Sí | Sí | Responder o redactar |
| Recibir correo procesado | Algunos proveedores | No | Sí |
| Leer historial de conversación | Algunos proveedores | No | Sí |
| Observar la entrega | Eventos o webhooks | Códigos de respuesta más eventos | Estado del mensaje y eventos |
Los productos usan el término API de correo electrónico para conjuntos de capacidades diferentes. Revisa el esquema del proveedor antes de asumir que una sola API cubre todas las filas.
¿Qué debe incluir una solicitud a la API?
Envía los campos que tu proveedor requiere. Registra el identificador de mensaje devuelto. Mantén tu propia clave de idempotencia cuando un reintento no deba crear un envío duplicado. Valida los destinatarios antes de enviar. Guarda los secretos en tu servidor.
Una solicitud transaccional ilustrativa tiene from, to, subject, text, category: transactional y una clave de idempotencia almacenada en el servidor. Usa un dominio de envío verificado antes de enviarla.
La respuesta HTTP indica que el servicio aceptó la solicitud. Los eventos de entrega, rebote y queja llegan después, así que una respuesta de aceptación no confirma la llegada a la bandeja de entrada.
Usa webhooks para los eventos posteriores en lugar de tratar una solicitud aceptada como prueba de que el mensaje llegó a la bandeja de entrada. Los eventos de entrega y queja describen lo que ocurrió después de la aceptación.
¿Cómo envío con Bird?
Llama a createEmailMessage API de Bird con tu clave API del espacio de trabajo, remitente, destinatarios, contenido y metadatos opcionales. La guía de envío de correo electrónico muestra los campos de solicitud y respuesta.
Para respuestas y correo entrante, crea un buzón y consume sus eventos de mensaje y entrega. La guía de buzones cubre esos endpoints y nombres de webhook.
En resumen
- Una API de correo electrónico expone el envío y los eventos de mensajes a través de HTTP.
- La respuesta confirma la aceptación por parte de API, no la llegada a la bandeja de entrada.
- Las claves de idempotencia hacen posibles los reintentos seguros.
- Bird ofrece APIs de envío y buzón con guías para cada vía.