Gmail Activities

Versión: 1.0.4 · ID: zoan-packages-gmail · Autor: Zoan Software

El paquete Gmail envía, busca, lee y organiza correos de un buzón de Gmail o Google Workspace mediante conexiones OAuth2 de Zoan Cloud. Automatiza el correo sin tener un cliente instalado: funciona igual en robots atendidos y desatendidos.

Concepto 1: la autenticación

Connect admite dos modos:

Modo	Qué necesitas
OAuth (por defecto)	Una conexión OAuth de Google de Zoan Cloud autorizada con la cuenta del buzón: `credential = credential("gmail-soporte")`.
Cuenta de servicio	La llave JSON guardada como credencial, el buzón en `impersonateUser` y la delegación de todo el dominio autorizada en Google Workspace con el alcance `https://mail.google.com/`. Ideal para procesos desatendidos sobre buzones del dominio.

Alcances de Gmail que necesita la conexión OAuth:

Alcance	Cubre
`https://www.googleapis.com/auth/gmail.modify`	Todo el paquete excepto el borrado permanente: buscar, leer, enviar, responder, reenviar, etiquetar, archivar, enviar a la papelera.
`https://mail.google.com/`	Todo, incluido Delete con `permanent = true`.

Concepto 2: la sesión

Connect abre una sesión (ZoanGmailSession) sobre un buzón:

Con body: las actividades de dentro la heredan y se cierra sola al terminar.
Sin body: guárdala en una variable, pásala por session y ciérrala con Close.

En modo OAuth la sesión usa el token vigente al conectar, que dura alrededor de una hora: en procesos largos, trabaja por lotes y conecta en cada lote.

Concepto 3: el correo como diccionario

Get emails y Get email by ID devuelven cada correo como un Dictionary<string,object> con las claves id, threadId, from, to, cc, subject, date, snippet, labels, unread y, con el cuerpo, body, bodyHtml y attachments (el detalle está en Get emails). Lee cada dato por su clave: correo["subject"]. Las cabeceras (from, to, date) vienen tal cual las escribió el remitente, con nombre y dirección.

El id de un correo no cambia al etiquetarlo, archivarlo o marcarlo: puedes encadenar varias actividades sobre el mismo id.

Concepto 4: etiquetas en lugar de carpetas

En Gmail un correo no está «en» una carpeta: tiene etiquetas. La bandeja de entrada es la etiqueta INBOX, los no leídos llevan UNREAD. Por eso Archive quita INBOX, Mark read/unread pone o quita UNREAD, y Apply label / Remove label clasifican. Consulta nombres e IDs con Get labels.

Actividades

Actividad	Tipo	Salida	Descripción
Gmail — Connect	`gmail-connect`	`ZoanGmailSession`	Abre una sesión autenticada con Gmail (OAuth o cuenta de servicio)
Gmail — Send	`gmail-send`	`string`	Envía un correo desde la cuenta de la sesión
Gmail — Reply	`gmail-reply`	`string`	Responde a un correo existente manteniendo el hilo
Gmail — Forward	`gmail-forward`	`string`	Reenvía un correo existente a nuevos destinatarios, con sus adjuntos
Gmail — Get emails	`gmail-get-emails`	`List<Dictionary<string,object>>`	Busca correos con la sintaxis de Gmail y devuelve una lista
Gmail — Get email by ID	`gmail-get-email`	`Dictionary<string,object>`	Trae un correo completo por su ID (cuerpo, cabeceras y adjuntos)
Gmail — Download attachments	`gmail-download-attachments`	`List<string>`	Descarga los adjuntos de un correo a una carpeta
Gmail — Mark read/unread	`gmail-mark-read`	—	Marca un correo como leído o no leído
Gmail — Apply label	`gmail-apply-label`	—	Aplica una o varias etiquetas a un correo (por nombre o ID)
Gmail — Remove label	`gmail-remove-label`	—	Quita una o varias etiquetas de un correo (por nombre o ID)
Gmail — Archive	`gmail-archive`	—	Archiva un correo (lo saca de la bandeja de entrada) o lo devuelve
Gmail — Get labels	`gmail-get-labels`	`List<Dictionary<string,object>>`	Lista las etiquetas del buzón
Gmail — Delete	`gmail-delete`	—	Mueve un correo a la papelera (o lo elimina permanentemente)
Gmail — Close	`gmail-close`	—	Cierra una sesión de Gmail

Ejemplo de proceso completo

Gmail — Connect   credential = credential("gmail-facturas")
 └─ body:
      Gmail — Get emails   query = "in:inbox is:unread has:attachment subject:factura"   → output: pendientes
      For each   correo in pendientes
       └─ Gmail — Download attachments   id = correo["id"]   folder = "C:\facturas\entrada"
          Gmail — Reply         id = correo["id"]   body = "Recibimos tu factura; la registraremos en los próximos días."
          Gmail — Apply label   id = correo["id"]   labels = "Procesado"
          Gmail — Archive       id = correo["id"]