Resend es una API de correo electrónico diseñada para desarrolladores: una solicitud POST, un cuerpo JSON y se envía un correo electrónico transaccional. Cada solicitud necesita una clave API, y la forma en que creas esa clave decide cuánto daño puede hacer una clave filtrada. Esta guía recorre todo el camino: regístrate, verifica un dominio de envío (o apóyate en la dirección de prueba incorporada), crea una clave con el ámbito de permisos adecuado y envía tu primer correo electrónico con curl, Node y Python. También almacenarás la clave en Apidog para poder probar el endpoint sin pegar secretos en tu shell.
Si quieres una visión más amplia de lo que hace la API más allá del envío, la guía para principiantes de la API de Resend cubre el resto. Todo lo que se menciona a continuación se ha comprobado con la documentación oficial de Resend, por lo que los números y las cadenas de error coinciden con lo que verás.
Lo que necesitas antes de empezar
- Una cuenta de Resend. El plan gratuito es suficiente para este tutorial.
- Un dominio que controles. Si no tienes uno a mano, la dirección de prueba cubre el primer envío.
- curl en tu máquina, además de Node.js o Python si quieres los ejemplos del SDK.
- Apidog instalado si planeas seguir la sección de pruebas.
Paso 1: crea una cuenta de Resend
Regístrate en resend.com y confirma tu correo electrónico. Anota la dirección con la que te registraste: hasta que verifiques un dominio, es la única bandeja de entrada a la que Resend entregará correos electrónicos de prueba, y olvidarlo provoca el 403 más confuso que verás el primer día.
Paso 2: verifica un dominio de envío, o usa la dirección de prueba
Dos rutas; empieza por la rápida.
Ruta A: la dirección de prueba de onboarding. Resend te permite enviar desde onboarding@resend.dev sin configuración. La pega es el destinatario: tiene que ser tu propio correo electrónico de cuenta. Envía a cualquier otra persona y la API devuelve un 403 con el mensaje "Solo puedes enviar correos electrónicos de prueba a tu propia dirección de correo electrónico".
Ruta B: tu propio dominio. Para cualquier cosa real, añade un dominio en el panel de control bajo Dominios. Resend recomienda un subdominio como notifications.example.com en lugar de tu dominio raíz, para que la reputación de envío de tu producto se mantenga separada de tu correo corporativo. Elige la región más cercana a tus destinatarios, luego copia los registros DNS que Resend genera en tu proveedor de DNS. La documentación los describe como "las configuraciones DKIM y SPF (registros TXT y MX o CNAME)". El subdominio Return-Path por defecto es send.example.com.
La verificación suele completarse en 15 minutos, aunque la propagación del DNS puede tardar hasta 72 horas. Si se estanca, comprueba dos culpables clásicos: registros colocados en la raíz en lugar del subdominio send, y el proxy de Cloudflare (el icono de la nube debe ser gris, no naranja). Corrige los registros y luego haz clic en "Reiniciar verificación". Añade un registro DMARC después; no es obligatorio para enviar, pero los proveedores de bandeja de entrada lo recompensan.
Paso 3: crea la clave API con el ámbito correcto
Abre la página de claves API en el panel de control y haz clic en Crear clave API. Tres campos importan; la documentación para crear una clave API cubre cada uno:
- Nombre. Hasta 50 caracteres. Nómbrala para la aplicación y el entorno, como
billing-service-prod, para que las claves sean fáciles de distinguir más tarde. - Permiso. "Acceso completo" puede crear, eliminar, obtener y actualizar cualquier recurso, incluidos dominios y otras claves API. "Acceso de envío" solo puede enviar correos electrónicos. Elige acceso de envío para cualquier cosa implementada. La clave de acceso completo pertenece a tu portátil, o a ningún sitio.
- Dominio. Con acceso de envío, puedes restringir la clave a un dominio verificado. Una clave con ámbito en
notifications.example.comno puede enviar desdebilling.example.com, lo que limita el radio de explosión de una fuga.
Resend muestra la clave exactamente una vez. Comienza con re_, y una vez que cierras el diálogo puedes renombrar la clave pero nunca volver a verla. Cópiala directamente en una variable de entorno:
export RESEND_API_KEY="re_xxxxxxxxx"
La propia guía de Resend: las claves nunca caducan, así que gíralas cada 90 días o antes; el panel de control marca cualquier clave no utilizada durante 30 días; y si una clave se filtra, elimínala inmediatamente en lugar de esperar la próxima rotación. Confirmar cadenas re_ en git es la ruta de fuga más común, así que ejecuta un escáner de secretos en tus repositorios antes del primer push.
También puedes acuñar claves con POST https://api.resend.com/api-keys, pasando name, permission (full_access o sending_access) y un domain_id opcional. Esa llamada necesita una clave de acceso completo, una razón más para mantener exactamente una de esas.
Paso 4: envía tu primer correo electrónico
El endpoint de envío es POST https://api.resend.com/emails. La autenticación es un token Bearer en el encabezado Authorization, el cuerpo es JSON y solo se acepta HTTPS. Se requieren tres campos: from, to y subject. Añade html, text o ambos; si envías solo html, Resend genera la parte de texto plano. to acepta una cadena o una matriz de hasta 50 direcciones. La lista completa de parámetros se encuentra en la referencia de envío de correo electrónico.
curl
curl -X POST 'https://api.resend.com/emails' \
-H "Authorization: Bearer $RESEND_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"from": "Acme <onboarding@resend.dev>",
"to": ["you@yourcompany.com"],
"subject": "First Resend email",
"html": "<p>Your Resend key works.</p>"
}'
Una llamada exitosa devuelve {"id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"}. Una peculiaridad: cada solicitud debe llevar un encabezado User-Agent, o la API responde con un 403 con el código 1010. curl y los SDKs configuran uno; un cliente hecho a mano en un entorno de ejecución edge podría no hacerlo.
Node.js
npm install resend
import { Resend } from 'resend';
const resend = new Resend(process.env.RESEND_API_KEY);
const { data, error } = await resend.emails.send({
from: 'Acme <notifications@example.com>',
to: ['you@yourcompany.com'],
subject: 'First Resend email',
html: '<p>Your Resend key works.</p>',
});
if (error) {
console.error(error);
} else {
console.log(data.id);
}
El SDK de Node nunca lanza errores de API. Devuelve { data, error }, así que comprueba error antes de tocar data.id.
Python
pip install resend
import os
import resend
from resend.exceptions import ResendError
resend.api_key = os.environ["RESEND_API_KEY"]
params: resend.Emails.SendParams = {
"from": "Acme <notifications@example.com>",
"to": ["you@yourcompany.com"],
"subject": "First Resend email",
"html": "<p>Your Resend key works.</p>",
}
try:
email = resend.Emails.send(params)
print(email["id"])
except ResendError as err:
print(err)
El SDK de Python hace lo contrario: lanza ResendError en caso de fallo, así que envuelve los envíos en un bloque try/except.
Paso 5: almacena y prueba la clave en Apidog
Curl prueba que la clave funciona una vez. Apidog convierte esa acción única en algo que tu equipo puede volver a ejecutar, y mantiene la clave fuera del historial de la shell y los registros de chat.
Almacena la clave como una variable secreta. Crea un entorno llamado Resend, añade RESEND_API_KEY como variable y márcala como secreta para que el valor esté enmascarado en la interfaz de usuario y no se incluya en las exportaciones. La guía de entornos y variables secretas cubre las divisiones de desarrollo, staging y producción si mantienes una clave de solo envío diferente por entorno, lo cual deberías hacer.
Envía la solicitud. Crea una solicitud POST a https://api.resend.com/emails, establece la autenticación en Bearer Token con {{RESEND_API_KEY}} y pega el cuerpo JSON del ejemplo de curl. Pulsa Enviar. El id aparece en el panel de respuesta junto a los encabezados de límite de tasa que se explican a continuación.
Guárdalo como una prueba. Añade dos aserciones: el estado es igual a 200 y $.id existe. Coloca la solicitud en un escenario de prueba y tendrás una prueba de humo que se ejecuta cada vez que alguien toca el código de correo electrónico. Apúntala a staging con una clave de envío restringida por dominio y es seguro ejecutarla desde CI.
Simula el endpoint para el trabajo de frontend. Tu frontend necesita la forma de la respuesta, no un envío real. Simula el endpoint en Apidog para que devuelva {"id": "mock-email-id"} en cada llamada. El equipo de UI puede construir el estado de "correo enviado" todo el día sin tocar la cuota gratuita de 100 por día o enviar spam a una bandeja de entrada real. Descarga Apidog para configurarlo; el plan gratuito cubre a cuatro usuarios.
Límites del nivel gratuito que alcanzarás primero
La página de precios de Resend enumera el plan gratuito en 3.000 correos electrónicos al mes, con un límite de 100 al día, con 3 dominios y retención de datos de 30 días. El plan Pro comienza en 20 $ al mes por 50.000 correos electrónicos, 10 dominios y sin límite diario, con un cargo por exceso de 0,90 $ por cada 1.000 correos electrónicos.
Los correos electrónicos de prueba a las direcciones resend.dev cuentan para esas cuotas, por lo que una prueba de carga dirigida a delivered@resend.dev sigue consumiendo tus 100 diarios. bounced@resend.dev, complained@resend.dev y suppressed@resend.dev simulan un rebote duro, una queja de spam y un destinatario suprimido sin direcciones realmente malas.
Aparte de la cuota, el límite de velocidad por defecto es de 10 solicitudes por segundo por equipo, compartido entre cada clave del equipo. Cada respuesta lleva los encabezados ratelimit-limit, ratelimit-remaining, ratelimit-reset y retry-after, por lo que un bucle de envío puede retroceder antes de alcanzar un 429. ¿Necesitas más? Resend te pide que contactes con soporte en lugar de crear equipos adicionales.
Errores comunes y cómo solucionarlos
Cada fallo se devuelve como JSON con un statusCode, un name y un message. Estos son los que te encontrarás el primer día, de la referencia de errores:
| Estado | Nombre | Lo que pasó | Solución |
|---|---|---|---|
| 401 | missing_api_key |
No hay encabezado Authorization |
Añade Authorization: Bearer re_... |
| 401 | restricted_api_key |
Clave de solo envío usada en un endpoint que no es de envío | Usa una clave de acceso completo para esa llamada |
| 403 | validation_error |
"El dominio no está verificado" | Finaliza la verificación DNS, o corrige la dirección from |
| 403 | validation_error |
Dirección de prueba enviada a alguien que no eres tú | Envía a tu correo electrónico de cuenta, o verifica un dominio |
| 403 | restricted_api_key |
"La clave API no está activa" | La clave fue eliminada; crea una nueva |
| 422 | missing_required_field |
Falta from, to, o subject |
Comprueba el cuerpo contra la referencia |
| 429 | rate_limit_exceeded |
Más de 10 solicitudes por segundo | Encola los envíos, respeta retry-after |
| 429 | daily_quota_exceeded |
Más de 100 correos electrónicos hoy en el plan gratuito | Espera el reinicio o actualiza |
Un 401 con una clave de la que estás seguro de que es correcta suele significar un salto de línea al final de la variable o un archivo .env que nunca se cargó. Ambos parecen una clave que falta desde el lado de la API.
Preguntas Frecuentes
¿Puedo ver mi clave API de Resend de nuevo después de crearla?
No. Resend muestra el valor una vez en el momento de la creación. Si la pierdes, crea una nueva clave con el mismo nombre y permiso, despliégala y luego elimina la antigua.
¿Debo elegir acceso completo o acceso de envío?
Acceso de envío, restringido a un dominio, para cada clave que sale de tu máquina. Mantén una clave de acceso completo para trabajos tipo panel de control, como añadir dominios o crear otras claves, y nunca la incluyas en una aplicación.
¿Puedo probar el envío sin verificar un dominio?
Sí. Usa onboarding@resend.dev como dirección from y tu propio correo electrónico de cuenta como destinatario. Cualquier otro destinatario devuelve un 403 hasta que se verifica un dominio.
¿Hay alguna forma de gestionar Resend desde la terminal en lugar del panel de control?
Sí. El tutorial de la CLI de Resend cubre cómo instalarla y ejecutar los comandos comunes de dominio y correo electrónico sin abrir un navegador.
¿Qué sucede cuando supero los 100 correos electrónicos al día en el plan gratuito?
La API devuelve un 429 con daily_quota_exceeded, y los envíos se reanudan después del reinicio diario. Si regularmente necesitas más, Pro elimina el límite, y el resumen de APIs de correo electrónico gratuitas muestra cómo se comparan los niveles gratuitos de otros proveedores.
Conclusión
Obtener una clave API de Resend tarda dos minutos; hacerlo bien tarda cinco. Verifica un subdominio, crea una clave de solo envío restringida a ese dominio, mantenla en una variable de entorno y envía un correo electrónico con curl para confirmar el ciclo completo. Luego, mueve la solicitud a Apidog, guarda las aserciones y simula el endpoint para que el resto de tu equipo pueda construir sobre él sin gastar tu cuota. Envía la clave menos potente que siga haciendo el trabajo.