Saltar al contenido
Docs

Guía práctica

Usa la cabecera Idempotency-Key para reintentar con seguridad las peticiones de envío y de reenvío. Formato de la clave, la ventana de 24 horas, repeticiones, respuestas 409 y 503, y estrategias para elegir la clave.

Actualizado el 1 oct 2026

Las redes fallan. Cuando se agota el tiempo de espera de una petición de envío, no puedes saber si Emailit la ha recibido, y volver a enviarla podría hacer que tu cliente recibiera el email dos veces. Una cabecera Idempotency-Key hace que el reintento sea seguro: Emailit procesa la primera petición y devuelve la misma respuesta a cualquier repetición con la misma clave.

Cómo funciona

Añade una cabecera Idempotency-Key a POST /emails o a POST /emails/{id}/forward.

  1. Primera petición. Emailit reserva la clave para tu espacio de trabajo y procesa la petición.
  2. Éxito. Emailit guarda la respuesta durante 24 horas. Cualquier petición con la misma clave dentro de ese plazo recibe la respuesta guardada con 200, y no se crea ningún email nuevo.
  3. Fallo. Si la petición falla, por ejemplo con un 400 o un 402, Emailit libera la clave. Corrige el problema y reinténtalo con la misma clave.
  4. Solapamiento. Si llega una segunda petición mientras la primera todavía se está procesando, recibe 409 y no se envía nada. Reinténtalo al poco tiempo con la misma clave.

Las claves están limitadas a tu espacio de trabajo, así que dos espacios de trabajo pueden usar la misma clave sin conflictos.

Formato de la clave

Regla Valor
Longitud De 1 a 256 caracteres
Caracteres Letras A–Z y a–z, dígitos 0–9, guion - y guion bajo _
Ámbito Por espacio de trabajo
Ventana 24 horas desde la primera respuesta correcta

Una clave con otros caracteres, como : o /, se rechaza con 400 Invalid Idempotency-Key.

Elegir una clave

Obtén la clave a partir del evento que provoca el email, para que todos los caminos de reintento generen la misma clave:

Email Clave de ejemplo
Recibo de un pedido order-1042-receipt
Restablecimiento de contraseña password-reset-7f3c9a1e (el ID del token de restablecimiento)
Resumen semanal digest-user-881-2026-w40
Tarea en segundo plano El ID de la tarea, o un UUID que generas al poner la tarea en cola y guardas con ella

Evita las claves que cambian entre intentos, como las marcas de tiempo o un UUID generado dentro del bucle de reintentos. Hacen que cada reintento parezca una petición nueva.

Enviar con una clave de idempotencia

Los ejemplos de Node.js, Python y PHP reintentan cuando hay errores de red y con las respuestas 409, 429 y 5xx, reutilizando la misma clave cada vez. El ejemplo de cURL usa el reintento integrado de curl, que cubre los tiempos de espera agotados, 429 y la mayoría de las respuestas 5xx.

Terminal
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  --retry 3 \
  -d '{
    "from": "Acme <orders@acme.com>",
    "to": "ada@example.com",
    "subject": "Receipt for order 1042",
    "text": "Thanks for your order."
  }'

Respuestas

Estado Cuándo Qué hacer
200 Primera petición correcta, o una repetición suya en un plazo de 24 horas Usa la respuesta. Una repetición tiene el mismo cuerpo, incluido el mismo id.
400 Invalid Idempotency-Key La clave está vacía, es demasiado larga o tiene caracteres no válidos Corrige la clave.
409 Idempotency key in progress Todavía se está procesando una petición con la misma clave Espera un momento y reinténtalo con la misma clave.
503 Idempotency unavailable Emailit no ha podido acceder a su almacén de idempotencia, así que ha rechazado la petición para no arriesgarse a un duplicado Reinténtalo con la misma clave.
Cualquier otro error La petición ha fallado y la clave se ha liberado Corrige la causa y reinténtalo con la misma clave.

Los límites de velocidad se comprueban antes que la clave, así que un reintento puede recibir igualmente 429. Espera lo que indique la cabecera retry-after y vuelve a enviar la misma clave.

¿Te ha resultado útil esta página?

Gracias por tu opinión.

Gracias. Leemos todos los mensajes.