¿Cómo debe implementar un equipo de producto la API de correo de Resend de forma segura?

Defina la operación del producto antes de la solicitud al proveedor

Empiece con una operación acotada de la aplicación, como la verificación de una cuenta, un recibo, una alerta de seguridad o una notificación que el destinatario solicitó. El endpoint público del producto debe autorizar al llamante, el inquilino, la clase de mensaje, la identidad del remitente, los destinatarios y la plantilla antes de que exista cualquier payload para Resend. No permita que un navegador envíe `from`, `to`, HTML u opciones del proveedor arbitrarios mientras tiene una credencial reutilizable. Cree un registro interno de salida duradero que contenga una clave de evento de la aplicación, el inquilino, la revisión de la plantilla, el remitente aprobado, el conjunto de destinatarios y el estado actual. Un worker puede traducir ese registro a la solicitud al proveedor. Este límite mantiene las claves de API y el contenido de mensajes no confiable lejos de los clientes, hace que la prevención de duplicados se pueda probar y permite al producto cambiar de proveedor sin reescribir cada flujo de negocio. Separe en el modelo interno los mensajes transaccionales de los que dependen del consentimiento, para que las preferencias, las supresiones y las decisiones ante incidentes sigan siendo explícitas.

Verifique el dominio exacto que se usa en la dirección From

Agregue en Resend un dominio que usted controle y publique los registros DNS que se muestran para ese dominio. Verifique el dominio o subdominio organizativo real que se usa en la dirección From visible, en lugar de suponer que una identidad principal no relacionada lo cubre. Revise la política SPF y DMARC existente antes de cambiar el DNS, y nunca cree un segundo registro SPF para el mismo nombre de host. Use un subdominio de envío con un propósito específico cuando los requisitos de aislamiento, de responsabilidad o de migración lo justifiquen. Cuando el panel indique la verificación, revise un mensaje de prueba recibido para confirmar la dirección From visible, la identidad de firma DKIM, la ruta de retorno, los resultados de autenticación y el comportamiento de las respuestas. La verificación del proveedor demuestra que una identidad configurada superó su comprobación de configuración. No demuestra el consentimiento del destinatario, la aceptación por el servidor receptor, la llegada a la bandeja de entrada ni una buena reputación. Conserve la responsabilidad sobre el DNS y el historial de cambios fuera del panel del proveedor, para que la rotación y la reversión sigan siendo posibles.

Cree una clave de API de mínimo privilegio para cada carga de trabajo

Resend documenta claves de API con niveles de acceso y restricción opcional por dominio. Un worker de envío debe usar una clave limitada al acceso de envío y, cuando la arquitectura lo permita, al único dominio del que es responsable esa carga de trabajo. Mantenga la administración de la gestión, los dominios, los webhooks y la cuenta bajo una autoridad separada. Cree claves distintas para desarrollo, staging y producción, para que un entorno inferior no pueda enviar con la identidad de producción ni consumir sus límites. Guarde cada secreto directamente en un almacén de secretos administrado, expóngalo solo al proceso de servidor que lo necesita y páselo como autorización Bearer sobre HTTPS. No copie la clave en el control de versiones, en artefactos de compilación, logs, plantillas, analítica, tickets ni prompts. La rotación debe ensayarse: cree un reemplazo con el mismo alcance, actualice el worker, verifique el tráfico controlado y la correlación de eventos, y luego revoque la clave anterior. Genere alertas ante fallos inesperados de autenticación y autorización, porque pueden indicar un vencimiento, una revocación, una desviación del alcance o la exposición del secreto.

Un trabajo duradero y un intento de envío idempotente

Reserve el trabajo de salida interno antes de llamar a Resend. Derive un valor de idempotencia a partir de un dato estable del producto, como el inquilino, el tipo de operación y el ID inmutable del evento de la aplicación, no a partir de un intento de reintento aleatorio. Envíe ese valor en el encabezado `Idempotency-Key`. Resend documenta actualmente que estas claves evitan solicitudes de correo duplicadas, vencen a las 24 horas y pueden tener como máximo 256 caracteres. Esa ventana del proveedor es útil, pero no es una garantía completa contra duplicados a nivel de producto. Mantenga una restricción de unicidad sobre la clave de evento interna para los flujos de negocio más largos, serialice los workers que puedan reclamar el mismo trabajo y guarde el ID de correo del proveedor que devuelve una solicitud correcta. Si un tiempo de espera de red vuelve ambigua la aceptación, deje el trabajo en estado desconocido y concílielo con los logs o eventos del proveedor antes de reenviar. Reutilizar una misma clave estable para la misma operación lógica es más seguro que generar una clave nueva en cada reintento de transporte.

Construya y valide la solicitud de correo de forma deliberada

El endpoint de envío de correo de Resend acepta una dirección From, destinatarios, un asunto y el contenido del mensaje, con opciones documentadas como texto, HTML, contenido renderizado con React, plantillas, Cc, Bcc, reply-to, encabezados, adjuntos, etiquetas y entrega programada. Exponga solo el subconjunto que el producto necesita. Valide la sintaxis de las direcciones y la propiedad del inquilino, limite la cantidad de destinatarios y de adjuntos por debajo de los límites del proveedor, rechace la inyección de saltos de línea en los encabezados y construya el contenido relacionado con MIME mediante bibliotecas mantenidas o campos de confianza del proveedor. No coloque credenciales, datos personales sensibles ni entradas de clientes sin restricciones en las etiquetas o los encabezados. Guarde la revisión de la plantilla y las variables saneadas en lugar de registrar el contenido completo. Un adaptador interno debe devolver un resultado acotado, como el ID aceptado por el proveedor o un fallo clasificado, sin filtrar detalles de la respuesta del proveedor al código de negocio. Así es posible actualizar nombres de campos específicos del proveedor, versiones del SDK o límites de solicitudes sin cambiar el contrato de eventos del producto.

Clasifique las respuestas de la API y los límites de uso antes de reintentar

Trate la respuesta HTTP como una observación más dentro del flujo. Una respuesta de envío correcta devuelve un identificador de correo que debe guardarse con el trabajo interno, pero no garantiza la aceptación en el destino ni la llegada a la bandeja de entrada. Corrija los errores de validación, autenticación, dominio, permisos y payload en lugar de reintentarlos a ciegas. Resend documenta límites de solicitudes a la API y devuelve encabezados de límite de frecuencia y de cuota, con campos que describen la capacidad restante, el momento del restablecimiento y la espera antes de reintentar; ante una respuesta 429 hay que esperar el intervalo documentado, con jitter adicional. Reintente los fallos de transporte y los errores de servidor elegibles con backoff exponencial, una cantidad finita de intentos y la misma clave de idempotencia lógica mientras se aplique su ventana documentada. Los fallos ambiguos requieren conciliación, porque el proveedor podría haber aceptado el correo aunque el cliente no haya recibido la respuesta. Genere alertas cuando los fallos repetidos se agrupen por dominio, plantilla, clave o inquilino, pero mantenga las credenciales, el contenido completo y los datos innecesarios de los destinatarios fuera de los logs operativos.

Autentique las solicitudes de webhook antes de procesar los eventos

Configure un endpoint HTTPS dedicado para webhooks y conserve el cuerpo exacto sin procesar de la solicitud. Resend documenta la firma de webhooks mediante encabezados compatibles con Svix y secretos de firma. Verifique el ID del webhook, la marca de tiempo y la firma sobre el payload sin modificar antes de analizar el JSON o volver a serializarlo, y use el flujo de verificación oficial o una biblioteca compatible mantenida. Rechace las solicitudes no válidas o caducadas, limite el tamaño de las solicitudes y mantenga el secreto de firma separado de la clave de envío. Tras la autenticación, guarde o encole el evento de forma duradera antes de confirmarlo, para que la caída de un proceso no descarte en silencio la evidencia de entrega. Los sistemas de entrega pueden reintentar y duplicar webhooks, así que use el identificador del evento como clave de deduplicación y haga que las transiciones de estado sean monótonas. Un evento posterior o duplicado no debe sobrescribir un resultado final más informativo solo porque llegó en último lugar. Registre los fallos de verificación y el retraso de los eventos como señales operativas, sin conservar el contenido sin procesar de los mensajes más allá del periodo de retención necesario.

Modele los eventos del proveedor sin exagerar la entrega

Resend publica tipos de eventos de correo con nombre, entre ellos sent, delivered, delivery delayed, bounced, complained, failed, opened y clicked. Asigne esos nombres del proveedor a un modelo de estados interno con el tipo de evento original, el ID de correo del proveedor, el ID del evento, la marca de tiempo, el alcance de destinatarios y los datos de diagnóstico disponibles. Un evento sent describe el avance en el proveedor. Un evento delivered informa la entrega según la semántica de eventos documentada por Resend, pero el éxito SMTP en un sistema receptor sigue sin revelar la carpeta final del destinatario. Las aperturas y los clics son observaciones de interacción, no pruebas de entrega, y las tecnologías de privacidad pueden afectarlas. Los rebotes, las quejas y los fallos permanentes deben actualizar el estado de seguridad del destinatario antes de la siguiente decisión de envío. Mantenga el historial de eventos del proveedor en modo de solo anexar y derive el estado visible para el usuario a partir de reglas explícitas. Así se conserva la evidencia para soporte y se evitan reintentos inseguros una vez que la responsabilidad se transfirió o un destinatario dio una señal negativa.

Pruebe las rutas de fallo y recuperación con destinatarios controlados

Use una clave que no sea de producción, un subdominio verificado controlado y buzones propiedad del equipo. Pruebe el contenido en texto y HTML, el comportamiento de reply-to, los límites de adjuntos, las claves de idempotencia estables y los identificadores del proveedor almacenados. Envíe dos veces el mismo trabajo lógico y confirme que los controles de la aplicación y del proveedor no crean un duplicado no deseado. Pruebe un payload no válido, un dominio incorrecto, una clave revocada, permisos insuficientes, un límite de frecuencia, un tiempo de espera agotado en el transporte, un rebote, una queja, un retraso en la entrega, un webhook duplicado, un cuerpo modificado respecto de la firma, una marca de tiempo de webhook caducada y la rotación del secreto de firma. Confirme que la recepción de eventos es duradera antes de la confirmación y que la seguridad del destinatario bloquea un trabajo posterior. Pruebe la rotación del DNS y la eliminación del proveedor sin borrar registros no relacionados. Los paneles deben cubrir los fallos de envío, la latencia, los fallos de verificación de webhooks, el retraso de los eventos, los rebotes, las quejas y las colas de conciliación. Revise la documentación vigente de Resend y la configuración de la cuenta en el lanzamiento, porque las cuotas, los límites, los campos de los eventos y los permisos disponibles pueden cambiar con independencia del código desplegado de la aplicación.

Compare las capacidades publicadas de las API antes de migrar

SendHQ publica un contrato OpenAPI 3.1 para su API de correo electrónico con alcance por espacio de trabajo, incluido el envío desde dominios verificados, correo entrante, plantillas alojadas, eventos de entrega y supresiones. Antes de migrar una integración, compare los cuerpos de solicitud, la autenticación, la idempotencia, los identificadores devueltos, las formas de los errores, los webhooks, las reglas de dominio y el comportamiento de supresión; luego valídelos con pruebas a nivel de campo. No suponga compatibilidad a partir de nombres de endpoint similares.

Preguntas frecuentes

Fuentes

• API de envío de correo de Resend — Resend
• Claves de API de Resend — Resend
• Dominios en Resend — Resend
• Claves de idempotencia de Resend — Resend
• Límites de uso de Resend — Resend
• Webhooks de Resend — Resend
• Verificar las solicitudes de webhook de Resend — Resend
• Tipos de eventos de webhook de Resend — Resend
• RFC 5321: protocolo simple de transferencia de correo (SMTP) — RFC Editor
• Contrato OpenAPI de SendHQ — SendHQ