Después del pago, tu aplicación tiene un pedido y un destinatario que necesita un recibo. Usa una API de correo electrónico para enviar el mensaje. Registra la respuesta junto al pedido.
El envío es solo el primer paso. Tu aplicación también necesita una forma de reintentar una solicitud. Necesita saber qué pasó con el mensaje después del envío.
¿Cómo se convierte un evento de aplicación en un correo electrónico?
Tu aplicación transforma una transacción completada o una solicitud de cuenta en una operación de envío. El servicio de correo se encarga de la entrega después del envío.
Para un recibo, la secuencia es:
- Tu aplicación confirma que el pedido está listo para un recibo.
- Selecciona al destinatario y proporciona los datos del pedido como contenido o valores de plantilla.
- Envía la solicitud y guarda el ID de mensaje devuelto junto al pedido.
- Actualiza el registro de envío cuando llegan los eventos de entrega.
Una API de correo electrónico puede admitir tanto mensajes transaccionales como de marketing. Usar una API no convierte el contenido promocional en transaccional ni elimina las obligaciones de CAN-SPAM.
¿Qué significa una respuesta exitosa?
Una respuesta exitosa de envío registra lo que el servicio aceptó. Es independiente de la decisión posterior del servidor de correo receptor.
El estado 202 de HTTP significa que la solicitud fue aceptada para procesamiento. El procesamiento no ha terminado, así que esa respuesta no confirma la entrega.
La respuesta exacta depende de la API. El endpoint de envío de Bird, por ejemplo, devuelve un mensaje en cola con un id. Guarda ese ID junto al pedido o evento de cuenta para poder asociar los resultados posteriores con la solicitud original.
Si la validación falla, Bird devuelve 422 con un error que explica por qué se rechazó la solicitud.
¿Cómo evitan los reintentos los mensajes duplicados?
Una clave de idempotencia identifica una operación lógica de envío a través de los reintentos. Una API que la soporte puede reconocer una solicitud repetida en lugar de crear otro envío.
Por ejemplo, un recibo del pedido 8472 puede usar la clave receipt/order-8472. Reintenta la misma solicitud con esa clave si la conexión se corta antes de recibir la respuesta.
Una clave nueva identifica una operación diferente. Por lo tanto, tu aplicación necesita conservar la clave original a lo largo de sus propios reintentos y reinicios.
La idempotencia tiene una ventana de retención definida por el proveedor. Una vez que esa ventana expira, la misma clave puede procesarse como una solicitud nueva.
¿Cómo informan los webhooks sobre la entrega?
Un webhook envía un evento a tu aplicación cuando cambia el estado del mensaje. Permite que tu aplicación actualice sus registros después de la respuesta inicial de la API.
Los eventos de correo electrónico de Bird distinguen estos resultados:
| Evento | Qué establece |
|---|---|
email.delivered | El servidor de correo receptor aceptó la responsabilidad del mensaje |
email.deferred | Un fallo temporal de entrega se reintentará |
email.bounced | El servidor receptor rechazó la entrega |
email.rejected | El mensaje no llegó a un intento de entrega |
La aceptación del servidor no confirma la colocación en la bandeja de entrada ni la lectura. Un servidor receptor también puede reportar un rebote posterior después de haber aceptado el mensaje.
Tu handler de webhook debe verificar la firma del remitente y gestionar las entregas duplicadas. El contrato de webhook de Bird requiere deduplicación usando webhook-id.
¿Qué cambian las plantillas?
Una plantilla almacenada separa el contenido reutilizable del mensaje de los valores proporcionados en cada envío. Tu aplicación puede proporcionar un número de pedido y un nombre de cliente sin ensamblar el cuerpo completo del correo.
Con las plantillas de Bird, un envío nombra una plantilla publicada y proporciona sus parámetros. La plantilla provee el asunto y el cuerpo.
Una plantilla no decide cuándo un pedido está completo ni si un restablecimiento de contraseña está autorizado. Esas decisiones permanecen en tu aplicación.
¿En qué se diferencia de un relay SMTP o una plataforma de marketing?
Una API HTTP y un relay SMTP son interfaces de envío diferentes. Una plataforma de marketing también gestiona el trabajo de campañas, como seleccionar una audiencia y programar un envío.
| Interfaz o producto | Qué proporciona tu aplicación |
|---|---|
| API de correo electrónico | Una solicitud HTTP estructurada con destinatarios y contenido o una plantilla |
| Relay SMTP | Una conversación SMTP que envía destinatarios y un mensaje de correo formateado |
| Plataforma de marketing | Contenido de campaña, selección de audiencia e instrucciones de envío |
SMTP define el intercambio para enviar un mensaje y sus destinatarios. Puede transportar correo transaccional o de marketing.
El relay SMTP de Bird y HTTP API usan el mismo producto de entrega, incluidos eventos y gestión de supresiones. Elegir SMTP no elimina esas capacidades.
¿Cómo envías correo electrónico transaccional a través de Bird?
Llama a POST /v1/email/messages con un remitente verificado, destinatarios y contenido en línea o una plantilla publicada. Configura category: "transactional" para correo operativo. La respuesta es 202 Accepted con un ID de mensaje; la entrega continúa de forma asíncrona.
Usa una Idempotency-Key para cada envío lógico. Bird conserva una respuesta completada durante tres horas. Un reintento después de esa ventana puede crear otro mensaje, así que mantén tu propio registro de eventos de negocio completados.
Suscríbete a los eventos de correo electrónico y asocia email_id y recipient_id con tus registros. Un mensaje con múltiples destinatarios tiene resultados independientes para cada destinatario.
Para seleccionar un proveedor, la lista de verificación de servicios de correo electrónico transaccional cubre las capacidades de entrega y operativas a comparar.