Gmail — Connect

Gmail — Connect

Tipo: gmail-connect  ·  Paquete: Gmail v1.0.4  ·  Salida: ZoanGmailSession

Abre una sesión autenticada con Gmail. Es el punto de partida obligatorio del paquete: todas las demás actividades (enviar, buscar, responder, etiquetar…) trabajan sobre esta sesión, que representa el acceso a un buzón concreto.

Cómo funciona

Se autentica con una conexión OAuth de Google de Zoan Cloud (o una cuenta de servicio) y abre la sesión sobre el buzón. Tiene dos formas de uso:

• Con body: las actividades que coloques dentro heredan la sesión automáticamente y se ejecutan sobre ese buzón; al terminar el bloque (también si algo falla dentro), la sesión se cierra sola.
• Sin body: devuelve la sesión como salida; guárdala en una variable, pásala por el parámetro session a las demás actividades y ciérrala al final con Gmail — Close.

Al conectar, lee el perfil del buzón en Gmail para saber su dirección (es el remitente de los correos que envíes). Así, si la autorización no sirve, el error aparece aquí y no a mitad del proceso.

Modos de autenticación (authType)

Modo	Qué necesitas	Cuándo usarlo
oauth (por defecto)	Una conexión OAuth de Google en credential, autorizada con la cuenta del buzón.	La cuenta de una persona o de un buzón de equipo que alguien puede autorizar.
service-account	La llave JSON de una cuenta de servicio guardada como credencial en serviceAccount, y el buzón en impersonateUser.	Google Workspace, procesos desatendidos y varios buzones del dominio sin consentimiento de cada persona.

Con cuenta de servicio, el administrador de Google Workspace debe autorizar el ID de cliente de la cuenta de servicio en la delegación de todo el dominio con el alcance https://mail.google.com/, que es el que pide la actividad. No funciona con cuentas de Gmail personales (@gmail.com).

El token OAuth se toma al conectar

En modo oauth, la sesión usa el token que tenía la conexión en el momento de conectar; Zoan Cloud lo renueva para las conexiones siguientes, pero no dentro de una sesión ya abierta, y los tokens de Google duran alrededor de una hora. En procesos largos, trabaja por lotes y conecta en cada lote. En modo service-account el token se renueva solo.

Parámetros requeridos

Ninguno. En la práctica necesitas credential (modo oauth) o serviceAccount + impersonateUser (modo service-account).

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
authType	string	"oauth"	Modo de autenticación: oauth o service-account. El Designer muestra solo los campos del modo elegido.
credential	credential	—	Modo oauth: conexión OAuth de Google de Zoan Cloud. Elígela en el selector del Designer o escribe credential("nombre-clave").
serviceAccount	credential	—	Modo service-account: credencial de Zoan Cloud con el JSON completo de la llave de la cuenta de servicio.
impersonateUser	string	—	Modo service-account: correo del buzón de Workspace sobre el que operar (p. ej. facturacion@example.com). Obligatorio en ese modo.

Sub-flujos

body opcional

Actividades a ejecutar dentro de la sesión. Heredan la sesión automáticamente y, al terminar, esta se cierra.

Salida

Devuelve un ZoanGmailSession solo si no usas body; con body la actividad no devuelve nada (la sesión se hereda sola). La sesión expone:

Propiedad	Tipo	Contenido
EmailAddress	string	Dirección del buzón conectado (el usuario de la conexión o el impersonateUser).
UserId	string	Siempre me: el buzón autenticado.

Errores comunes

Mensaje	Causa y solución
'credential' no contiene un access_token válido. Revisa la conexión OAuth en Zoan Cloud.	La conexión no entregó token: está pendiente de autorizar o se revocó. Verifica en Zoan Cloud que esté Conectada.
'serviceAccount' debe hacer referencia a una credencial de Zoan Cloud que contenga la clave JSON de la cuenta de servicio.	La credencial de serviceAccount está vacía.
La credencial de la cuenta de servicio no es una clave JSON válida de cuenta de servicio de Google. …	El valor guardado no es la llave JSON completa. Descárgala de nuevo en Google Cloud y pega el archivo entero.
Gmail con una cuenta de servicio requiere 'impersonateUser' …	Falta impersonateUser en modo service-account.
unauthorized_client	La delegación de todo el dominio no está configurada para esa cuenta de servicio o no incluye el alcance https://mail.google.com/.
Request had insufficient authentication scopes.	La conexión OAuth no tiene los permisos de Gmail. Edita la conexión, marca los alcances de Gmail y vuelve a autorizarla.

Ejemplo

Gmail — Connect   credential = credential("gmail-soporte")
 └─ body:
      Gmail — Get emails   query = "is:unread in:inbox"   → output: nuevos
      For each   correo in nuevos
       └─ Gmail — Reply   id = correo["id"]   body = "Recibimos tu mensaje; te respondemos pronto."

Con cuenta de servicio, sin body:

Gmail — Connect   authType = service-account   serviceAccount = credential("google-sa")   impersonateUser = "facturacion@example.com"   → output: buzon
Gmail — Get emails   session = buzon   query = "has:attachment subject:factura"   → output: facturas
Gmail — Close   session = buzon

Búsqueda potente

Get emails usa la misma sintaxis que la caja de búsqueda de Gmail (is:unread, from:proveedor@example.com, has:attachment, after:2026/01/01).

Actividades relacionadas

• Gmail — Send — enviar un correo.
• Gmail — Get emails — buscar correos.
• Gmail — Close — cerrar la sesión (modo sin body).
• Todas las actividades de Gmail