Una lib simple para enviar emails usando la API de Gmail con autenticación de Service Account.
- ✅ Envío de emails usando Gmail API
- ✅ Soporte para Domain-Wide Delegation
- ✅ Manejo robusto de errores
- ✅ Validación de formatos de email
- ✅ Código modular y reutilizable
- ✅ Soporte para diferentes formatos de clave privada
Crea un archivo .env.local en la raíz del proyecto:
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nTU_CLAVE_PRIVADA_AQUI\n-----END PRIVATE KEY-----"
GOOGLE_CLIENT_EMAIL="[email protected]"- Crear un proyecto en Google Cloud Console
- Habilitar Gmail API
- Crear un Service Account
- Descargar las credenciales JSON
- Configurar Domain-Wide Delegation (si es necesario)
La clave privada debe estar en formato PEM. Si tienes problemas con el formato, puedes usar:
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQC+L5oU+TdRN46E\n...\n-----END PRIVATE KEY-----"POST /api/send-email
Content-Type: application/json
{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Asunto del email",
"body": "Contenido del email"
}{
"success": true,
"messageId": "18c1234567890abc",
"message": "Email enviado exitosamente"
}MISSING_FIELDS: Campos requeridos faltantesINVALID_EMAIL_FORMAT: Formato de email inválidoINVALID_CREDENTIALS: Credenciales inválidasACCESS_DENIED: Acceso denegadoUNAUTHORIZED_CLIENT: Cliente no autorizadoINVALID_PRIVATE_KEY: Error en formato de clave privadaUNSUPPORTED_KEY_FORMAT: Formato de clave no soportado
├── app/
│ └── api/
│ └── send-email/
│ └── route.ts # API endpoint
├── lib/
│ └── gmail-client.ts # Cliente de Gmail (todo en un archivo)
└── components/ # Componentes de UI
Función principal para enviar emails.
import { sendEmail } from "@/lib/gmail-client"
const result = await sendEmail({
from: "[email protected]",
to: "[email protected]",
subject: "Asunto",
body: "Contenido"
})Crea un cliente de Gmail autenticado.
Limpia y formatea la clave privada.
Parsea el campo "from" para extraer email y nombre.
Configura las credenciales de Gmail manualmente.
Verifica si la configuración está completa.
Causa: Formato incorrecto de la clave privada.
Solución:
- Verifica que la clave esté en formato PEM
- Asegúrate de que los
\nestén correctamente escapados - Regenera las credenciales si es necesario
Causa: Credenciales inválidas o Domain-Wide Delegation no configurado.
Solución:
- Verifica que el Service Account tenga los permisos correctos
- Configura Domain-Wide Delegation si es necesario
- Verifica que el email del remitente esté autorizado
Causa: El Service Account no tiene permisos para enviar emails.
Solución:
- Verifica que el Service Account tenga el scope
https://www.googleapis.com/auth/gmail.send - Configura Domain-Wide Delegation correctamente
- Verifica que el email del remitente esté en el dominio autorizado
# Instalar dependencias
npm install
# Ejecutar en desarrollo
npm run dev
# Construir para producción
npm run buildPara usar este módulo en otro proyecto, simplemente copia el archivo lib/gmail-client.ts y configúralo:
// .env
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nTU_CLAVE_AQUI\n-----END PRIVATE KEY-----"
GOOGLE_CLIENT_EMAIL="[email protected]"
// Uso
import { sendEmail } from "./gmail-client"import { sendEmail, configureGmail } from "./gmail-client"
// Configurar manualmente
configureGmail({
privateKey: "-----BEGIN PRIVATE KEY-----\nTU_CLAVE_AQUI\n-----END PRIVATE KEY-----",
clientEmail: "[email protected]"
})
// Usar
const result = await sendEmail({
from: "[email protected]",
to: "[email protected]",
subject: "Asunto",
body: "Contenido"
})next: Framework de Reactgoogleapis: Cliente oficial de Google APIs@types/node: Tipos de TypeScript para Node.js