Idempotencia

Los errores de red y los tiempos de espera agotados te dejan sin saber si un envío se ha completado. Una clave de idempotencia permite reintentar el envío de forma segura: si Emailit ya aceptó una petición con la misma clave, devuelve la respuesta original en lugar de volver a enviar el email. Esta página es la referencia de la cabecera Idempotency-Key. Para una guía paso a paso, consulta Envíos idempotentes.

Endpoints compatibles

Los demás endpoints ignoran la cabecera. Crear un dominio, una clave de API, una lista de contactos o un contacto ya se puede reintentar de forma segura: una segunda petición con el mismo nombre o email devuelve 409 y el objeto existing en lugar de crear un duplicado.

Enviar una clave

Añade una cabecera Idempotency-Key con un valor único para el email que envías, como un UUID o un ID de tu propio sistema:

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

const response = await fetch('https://api.emailit.com/v2/emails', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `order-${order.id}-confirmation`,
  },
  body: JSON.stringify({
    from: 'Acme <orders@acme.com>',
    to: order.email,
    subject: `Your order #${order.id}`,
    html: '<p>Thanks for your order.</p>',
  }),
});

import os
import requests

response = requests.post(
    "https://api.emailit.com/v2/emails",
    headers={
        "Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}",
        "Idempotency-Key": f"order-{order['id']}-confirmation",
    },
    json={
        "from": "Acme <orders@acme.com>",
        "to": order["email"],
        "subject": f"Your order #{order['id']}",
        "html": "<p>Thanks for your order.</p>",
    },
    timeout=30,
)

Genera la clave una vez por email, antes del primer intento, y envía la misma clave en cada reintento de ese email.

Cómo funcionan las claves

Una petición repetida sigue pasando por la autenticación y por la comprobación de los límites de envío por segundo y diarios, así que puede devolver 401 o 429. Los reenvíos también cuentan para el límite de reenvíos por hora, aunque la respuesta sea una repetición.

Errores

{
  "error": "Invalid Idempotency-Key"
}

{
  "error": "Idempotency key in progress",
  "message": "A request with this Idempotency-Key is already being processed. Retry shortly with the same key."
}

{
  "error": "Idempotency unavailable",
  "message": "Unable to process Idempotency-Key right now. Retry the request with the same key."
}

Emailit nunca envía una petición sin su comprobación de idempotencia: si no puede comprobar la clave, la petición falla con 503 en lugar de arriesgarse a un duplicado.

Elegir buenas claves

• Deriva la clave de aquello sobre lo que notificas, como order-1042-confirmation o password-reset-<token-id>, para que un reintento desde otro worker o tras un reinicio use la misma clave.
• Usa un UUID nuevo solo cuando el email no tenga un ID natural, y guárdalo con la tarea antes del primer intento.
• No reutilices una clave para otro email en un plazo de 24 horas. Recibirías la respuesta del primer email y el segundo no se enviaría.

Ver también