Gmail (OAuth)

La integración con Gmail envía las plantillas de Frontmail desde tu propio buzón de Gmail o Google Workspace a través de la API de Gmail. Los mensajes enviados aparecen en tu carpeta Enviados, las respuestas llegan a tu bandeja de entrada y los destinatarios ven un correo normal tuyo.

Elige Gmail si tienes una web personal, un portfolio o un pequeño negocio y quieres que los envíos de formularios y las notificaciones salgan de la dirección que ya usas, sin configurar DNS si usas @gmail.com. No está pensado para grandes volúmenes: Google limita los envíos diarios (consulta Límites de envío) y no hay webhooks de entrega. Para volumen transaccional usa Mailgun, Postmark, Amazon SES o Resend. Consulta el resumen de los servicios.

OAuth en lugar de contraseñas de aplicación

También puedes conectar Gmail por SMTP con una contraseña de aplicación, pero OAuth es más seguro: Frontmail nunca ve tu contraseña, el permiso se limita a enviar y puedes revocarlo cuando quieras desde tu cuenta de Google.

Requisitos previos

• Una cuenta de Gmail (@gmail.com) o un usuario de Google Workspace con Gmail activado.
• En Workspace: el administrador debe permitir que las aplicaciones de terceros accedan a los datos de Google o marcar Frontmail como de confianza en Admin console → Security → Access and data control → API controls → App access control.
• Nada más: ni clave de API ni proyecto de Google Cloud.

Conectar en Frontmail

1. Abre Servicios de correo → Añadir servicio → Gmail.
2. Haz clic en Conectar Gmail. Se te redirige a Google.
3. Elige la cuenta y revisa la pantalla de consentimiento. Frontmail solicita:
   • https://www.googleapis.com/auth/gmail.send: enviar correo en tu nombre. Es un permiso solo de envío: Frontmail no puede leer, buscar, eliminar ni modificar ningún correo de tu buzón.
   • openid email: tu dirección de correo, para que el panel pueda mostrar qué cuenta está conectada y usarla como dirección From predeterminada.
4. Haz clic en Permitir. Google te redirige de vuelta y el servicio se guarda mostrando la dirección conectada.
5. Si quieres, configura Máx. de correos por segundo (por defecto 2/s) y haz clic en Probar conexión, que renueva el token de acceso y comprueba que se concedió el permiso gmail.send.

Qué se guarda: Frontmail guarda el refresh token de OAuth (y un token de acceso de corta duración), cifrado con cifrado de sobre de AWS KMS. El token de acceso caduca al cabo de una hora aproximadamente; Frontmail lo renueva en segundo plano antes de enviar. El flujo usa PKCE y siempre solicita acceso sin conexión, así que al volver a conectar se emite un refresh token nuevo.

Verificación de la aplicación

La aplicación OAuth de producción de Frontmail está verificada por Google para el permiso gmail.send, así que verás el nombre de Frontmail y ningún aviso de «aplicación no verificada».

Cuando el token deja de funcionar

Google invalida un refresh token cuando:

• revocas el acceso en Cuenta de Google → Seguridad → Aplicaciones y servicios de terceros → Frontmail,
• cambias la contraseña de la cuenta de Google (en los permisos de Gmail, Google revoca los tokens existentes),
• no usas el token durante 6 meses,
• o un administrador de Workspace retira el acceso a la aplicación.

El siguiente envío o la siguiente comprobación de estado fallan entonces con invalid_grant. Frontmail lo trata como un error de auth: el servicio se marca como unhealthy, recibes un correo y un aviso en el panel, y los mensajes quedan retenidos (o se envían por el servicio de respaldo) hasta que haces clic en Volver a conectar en la página del servicio. Al volver a conectar se crea un refresh token nuevo y los mensajes retenidos se liberan automáticamente.

Aplicaciones OAuth propias / en «Testing»

Si usas Frontmail con tu propio cliente OAuth de Google Cloud cuyo estado de publicación es Testing, Google hace caducar los refresh tokens a los 7 días: el servicio pasará a unhealthy cada semana. Publica la aplicación (y completa la verificación del permiso sensible gmail.send) para que los tokens duren. Esto no se aplica a la aplicación alojada de frontmail.dev.

DNS: SPF, DKIM y DMARC

• Direcciones @gmail.com: no tienes que hacer nada; Google firma y autentica el correo.
• Google Workspace con tu propio dominio: publica los registros de Google si aún no lo has hecho:

; SPF
example.com.                    TXT  "v=spf1 include:_spf.google.com ~all"

; DKIM: se genera en Admin console → Apps → Google Workspace → Gmail → Authenticate email
google._domainkey.example.com.  TXT  "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A…"

; DMARC
_dmarc.example.com.             TXT  "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

Después de publicar el registro DKIM, haz clic en Start authentication en la Admin console. Endurece DMARC a p=quarantine / p=reject cuando los informes estén limpios.

Nota

Los requisitos de 2024 de Google para remitentes masivos se aplican al correo enviado a usuarios de Gmail desde cualquier sitio, incluido Workspace. Un formulario de contacto no llegará al umbral de 5000 al día, pero aun así se recomienda SPF + DKIM + DMARC en tu dominio de Workspace.

Dirección From: Gmail envía como la cuenta conectada. Solo puedes usar otra dirección si está configurada como alias en Enviar como en los ajustes de Gmail; si no, Gmail sustituye el From por la dirección de la cuenta.

Regiones

No hay regiones: la API de Gmail es global.

Límites de envío

Google impone límites diarios por usuario. Si los superas, el envío se bloquea durante hasta 24 horas.

Cuenta	Límite aproximado
Gmail personal (@gmail.com)	~500 destinatarios al día
Google Workspace	~2000 mensajes al día (menos durante la prueba)
API de Gmail	250 unidades de cuota por usuario y segundo; un envío = 100 unidades

Por eso Frontmail envía como máximo 2 mensajes por segundo a través de Gmail. Cuando Google responde dailyLimitExceeded, Frontmail espera una hora entre reintentos; si el límite persiste, el mensaje termina como failed y se devuelve el crédito.

Seguimiento de la entrega (webhooks)

Gmail no tiene webhooks de entrega, así que no hay nada que configurar ni URL de webhook en la página del servicio. Frontmail solo sabe si Google aceptó el mensaje (sent) o lo rechazó (failed). Los rebotes llegan como correos normales de «Delivery Status Notification» a tu bandeja de entrada de Gmail y no se añaden automáticamente a la lista de supresión de Frontmail. Las aperturas y los clics no se registran.

Errores habituales

• auth: el servicio no funciona (token revocado o caducado, invalid_grant, 401/403, Gmail no activado para el usuario de Workspace). El servicio se marca como unhealthy; el propietario recibe un correo y un aviso en el panel. Si la plantilla tiene un servicio de respaldo, este toma el relevo; si no, se devuelve el crédito y el mensaje espera en la cola de correos retenidos como held_service_error y se envía automáticamente cuando vuelves a conectar (se vuelve a comprobar al guardar y en la comprobación de estado diaria).
• permanent: este mensaje no se puede enviar (destinatario no válido, mensaje demasiado grande, error de validación 400). Servicio de respaldo si está configurado; si no, failed y se devuelve el crédito.
• transient: 5xx, límites de velocidad o diarios, tiempos de espera agotados. Se reintenta con espera exponencial; tras el último intento, failed y se devuelve el crédito.

Respuesta de Google	Clase	Qué hacer
invalid_grant – Token has been expired or revoked	auth	Haz clic en Volver a conectar en la página del servicio y vuelve a conceder el acceso.
401 – Invalid Credentials	auth	Normalmente lo resuelve la renovación automática del token; si persiste, vuelve a conectar.
403 – Insufficient Permission / insufficient_scope	auth	Se desmarcó la casilla de gmail.send en la pantalla de consentimiento: vuelve a conectar y permite el envío.
403 – acceso bloqueado por el administrador de Workspace	auth	Pide a tu administrador que marque Frontmail como de confianza en API controls.
400 failedPrecondition – Mail service not enabled	auth	El usuario de Workspace no tiene licencia de Gmail; activa Gmail o conecta otra cuenta.
400 invalidArgument – Invalid To header	permanent	Consulta destinatario no válido.
413 / 400 – mensaje demasiado grande	permanent	Reduce el tamaño de los adjuntos (el límite de Gmail es de 25 MB).
429 / 403 rateLimitExceeded, userRateLimitExceeded, dailyLimitExceeded	transient	Reduce el ritmo o espera a que se renueve el límite diario; plantéate un proveedor transaccional.
500 / 503 backendError	transient	Caída de Google: Frontmail reintenta.

Lista de comprobación

• Conectado con Conectar Gmail; consentimiento concedido para enviar correo
• Workspace: Frontmail permitido en API controls (si está restringido)
• Workspace con dominio propio: SPF include:_spf.google.com, DKIM google._domainkey, DMARC
• From de la plantilla = la dirección conectada o un alias configurado en Enviar como
• Probar conexión funciona
• Volumen diario muy por debajo de los límites de Google
• Servicio de respaldo configurado en las plantillas importantes por si se revoca el token