técnico · respuesta con fuentes
Clave de idempotencia: cómo evitar envíos de correo electrónico duplicados
Una clave de idempotencia es un valor único que genera el cliente y envía en una solicitud a la API para garantizar que una operación se ejecute exactamente una vez. Si la solicitud se reintenta con la misma clave, el servidor reconoce el duplicado y devuelve la respuesta original sin volver a procesar la acción.
Funcionamiento técnico
Cuando un cliente envía una solicitud con una clave de idempotencia, el servidor almacena la clave y la respuesta resultante en una caché. Si llega una solicitud posterior con la misma clave, el servidor omite la lógica de ejecución y se limita a devolver la respuesta almacenada. Este mecanismo es fundamental en los sistemas distribuidos, donde un tiempo de espera de red agotado puede dejar al cliente sin saber si la solicitud llegó al servidor.
Por qué importa a los remitentes
En el correo transaccional, enviar el mismo mensaje dos veces puede empeorar la experiencia del usuario y aumentar las denuncias de spam. Las claves de idempotencia permiten a los desarrolladores implementar una lógica de reintentos agresiva para las llamadas de red fallidas sin arriesgarse a enviar correos duplicados al destinatario. Esto garantiza la fiabilidad y la coherencia en todo el flujo de entrega.
Consideraciones operativas
Las claves deberían generarse con un UUID o con una cadena aleatoria de alta entropía para evitar colisiones. Los servidores suelen hacer caducar estas claves al cabo de 24 horas. Los desarrolladores deben asegurarse de que la clave esté ligada a la intención concreta del mensaje: cambiar el cuerpo del correo o el destinatario manteniendo la misma clave debería producir un error y no un éxito almacenado en caché.
Ejemplo de implementación
Una aplicación SaaS genera una clave única para un correo de restablecimiento de contraseña. La aplicación llama a la API de correo, pero la conexión se corta antes de recibir respuesta. La aplicación reintenta la solicitud con la misma clave. La API ve que la clave ya existe y devuelve un 200 OK sin enviar un segundo correo al usuario. Las herramientas gratuitas de SendHQ ayudan a los desarrolladores a gestionar su infraestructura de correo de forma eficiente.
Gestión de errores
Si una solicitud se modifica pero se envía con una clave de idempotencia existente, el servidor debería devolver un error de conflicto. Así se evita reutilizar por accidente claves para mensajes distintos. Para gestionarlo correctamente, hay que capturar estos conflictos y generar una clave nueva para el payload de la solicitud actualizada.
Preguntas habituales de los equipos
¿Una clave de idempotencia es lo mismo que un Message-ID?
No. El servidor asigna el Message-ID después del procesamiento, mientras que el cliente asigna la clave de idempotencia antes de enviar la solicitud.
¿Qué ocurre si caduca la clave de idempotencia?
Si la clave caduca en la caché del servidor, un reintento se tratará como una solicitud nueva, lo que puede provocar el envío de un correo duplicado.
¿Qué tipo de dato es el mejor para las claves de idempotencia?
UUID v4 es el estándar del sector porque ofrece una probabilidad de colisión insignificante en sistemas distribuidos.
Fuentes primarias
- Documentación de SendGrid — Twilio SendGrid
- Documentación para desarrolladores de Postmark — Postmark