Resend - automatización - email - Node.js
5 min lectura

Evita correos duplicados en tu app con claves de idempotencia de Resend

Una guía práctica para reintentar emails de bienvenida con Resend sin duplicarlos: clave estable, código Node.js, pruebas y límite de 24 horas.

Evita correos duplicados en tu app con claves de idempotencia de Resend

Tu app envía un correo de bienvenida cuando alguien crea una cuenta. La solicitud llega a Resend, pero tu servidor pierde la respuesta por un corte de red. El trabajador reintenta y la persona recibe dos mensajes iguales. Si además el alta activa otros procesos, esa repetición se vuelve difícil de diagnosticar. Para este caso, una clave de idempotencia hace que varios intentos del mismo envío compartan una sola operación.

No es un lanzamiento de hoy: Resend anunció estas claves el 1 de mayo de 2025 y su documentación actual las admite en el envío individual y por lotes. La utilidad esta semana es concreta para quien conecta formularios, webhooks de pago o colas de trabajo y necesita reintentos sin correos repetidos.

La decisión de diseño: una clave por mensaje lógico

La clave debe representar el evento que justifica ese correo, no el intento de red. Para un mensaje de bienvenida, welcome-user/123 puede identificar al usuario 123. Para un recibo, usa el identificador estable del pago o pedido: receipt/order-456. Si generas un UUID nuevo en cada reintento, Resend verá operaciones distintas y enviará ambas. Si reutilizas una misma clave para todos los usuarios, provocarás conflictos o bloquearás mensajes legítimos.

Resend conserva la relación entre clave, cuerpo y respuesta durante 24 horas. Si repites la misma solicitud en ese plazo, devuelve el mismo ID sin enviar de nuevo. Si cambias destinatario, asunto o HTML y conservas la clave, devuelve un conflicto 409 invalid_idempotent_request. Esto protege contra un error común: una clave correcta con un contenido que ya no es el mismo.

Decide qué debe pasar si el usuario cambia de correo justo entre dos intentos. No edites silenciosamente el cuerpo de un trabajo ya encolado. Conserva los datos del primer evento para poder repetir la misma petición, o cancela ese trabajo y crea un evento nuevo con su propia clave. Documenta esa decisión porque un mensaje de bienvenida, una factura y un aviso de seguridad pueden tener reglas distintas.

Ejemplo en Node.js

Necesitas una API key y un dominio verificado. Instala el SDK con npm install resend, guarda RESEND_API_KEY en el entorno del servidor y evita ponerla en el navegador. Este ejemplo está pensado para ejecutarse después de confirmar en tu base de datos que el usuario existe; el userId debe provenir de tu sistema, no del texto libre de un formulario.

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

export async function sendWelcome({ userId, email }) {
  const message = {
    from: 'Equipo <hola@tu-dominio.com>',
    to: [email],
    subject: 'Bienvenido a tu cuenta',
    html: '<p>Tu cuenta ya está lista.</p>',
  };

  const { data, error } = await resend.emails.send(message, {
    idempotencyKey: `welcome-user/${userId}`,
  });

  if (error) throw error;
  return data.id;
}

En un reintento del mismo evento, mantén exactamente el mismo userId, destinatario y mensaje. Guarda el ID de correo devuelto junto con el evento de bienvenida en tu base de datos. El snippet sigue el contrato oficial del SDK; no se envió un correo real desde este entorno porque no hay una cuenta ni dominio de Resend configurados aquí.

Cómo probarlo sin engañarte con un “funciona”

  1. En una cuenta de prueba con dominio verificado, envía a una dirección propia y anota el ID que devuelve Resend.
  2. Repite la llamada con la misma clave y el mismo cuerpo antes de 24 horas. Compara el ID y revisa la bandeja: debe existir un solo correo.
  3. Cambia el asunto, conserva la clave y comprueba que aparece 409 invalid_idempotent_request. No reintentes ese error indefinidamente: corrige la clave o decide que se trata de otro mensaje lógico.
  4. Haz dos solicitudes simultáneas. Resend documenta otro 409 concurrent_idempotent_requests mientras la primera sigue en curso; espera y reintenta la misma solicitud.

Una clave del proveedor no reemplaza tu propio registro. Pasadas 24 horas, el mismo evento podría volver a enviar el correo si tu cola lo reintenta. Mantén en tu base un estado duradero por evento y el ID devuelto; para flujos críticos usa una cola o patrón outbox con una restricción única del evento. Tampoco confundas “Resend aceptó la petición” con “el destinatario lo leyó”: la entrega y los rebotes se verifican por los estados y webhooks del proveedor.

Si el correo corresponde a un pago, crea el evento a partir de tu pedido interno y verifica antes la firma y el estado del webhook de la pasarela. La idempotencia del email solo evita repetir ese email durante su ventana; no valida que el pago sea auténtico ni impide crear dos pedidos. Cada efecto secundario necesita su propia clave y su propio estado.

Antes de activar una automatización masiva, revisa el plan y límites vigentes y prueba con tu propio buzón. La ganancia no es mandar más correos: es poder repetir una operación incierta sin duplicar el mensaje durante la ventana documentada.

Recibe lo nuevo en tu correo

Workshops gratis, herramientas y novedades de IA aplicadas a negocio, sin humo.

🎓 Workshops en vivo🛠️ Herramientas nuevas⚡ Novedades de IA

Sin spam. Te das de baja cuando quieras.

Comentarios

Aún no hay comentarios. Sé el primero.

Deja un comentario