Gmail — Get emails

Gmail — Get emails

Tipo: gmail-get-emails  ·  Paquete: Gmail v1.0.4  ·  Salida: List<Dictionary<string,object>>

Busca correos en el buzón usando la sintaxis de búsqueda de Gmail y devuelve la lista de mensajes que coinciden. Es la actividad con la que normalmente arranca un proceso: localiza los correos a procesar y luego iteras sobre ellos.

Cómo funciona

Opera sobre la sesión creada con Gmail — Connect. Pásala en el parámetro session, o coloca esta actividad dentro del body de Gmail — Connect para heredarla automáticamente.

• query acepta la misma sintaxis que la caja de búsqueda de Gmail: is:unread, from:, to:, subject:, has:attachment, filename:pdf, label:, in:inbox, after:2026/10/01, before:, newer_than:7d, older_than:1y… Vacío = todo el correo.
• labelIds restringe a correos que tengan todas las etiquetas indicadas, por ID (INBOX, UNREAD, STARRED, Label_123…). Para usar nombres de etiqueta, ponlos en la búsqueda (label:Proveedores) o consulta los IDs con Get labels.
• Como en Gmail, la papelera y el spam no se incluyen salvo que los pidas en la búsqueda (in:trash, in:spam, in:anywhere).
• Los resultados vienen en el orden de Gmail: los más recientes primero.

La actividad hace una sola consulta y Gmail entrega como mucho 500 correos por consulta; no pide páginas siguientes. Para volúmenes grandes, procesa por lotes: etiqueta, archiva o marca como leído lo procesado y vuelve a consultar. Cada correo se descarga con una petición propia, así que un maxResults alto y includeBody hacen la actividad más lenta.

Parámetros requeridos

Ninguno.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
session	ZoanGmailSession	—	Sesión de Gmail — Connect (se hereda dentro del body).
query	string	—	Búsqueda de Gmail (misma sintaxis que la caja del buzón). Vacío = todo el correo. Ej.: is:unread from:proveedor@example.com.
maxResults	int	25	Número máximo de correos a devolver (Gmail acepta hasta 500). Un valor vacío, no numérico o menor que 1 usa 25.
includeBody	bool	false	Si es true, incluye el cuerpo y la información de adjuntos de cada correo (claves body, bodyHtml, attachments).
labelIds	string | List	—	ID(s) de etiqueta que deben tener los correos (p. ej. INBOX, UNREAD). Texto separado por comas o punto y coma, o una lista.

Salida

Devuelve un List<Dictionary<string,object>>: una lista en la que cada elemento es un correo con estas claves.

Clave	Tipo	Contenido
id	string	ID del mensaje. Es la entrada de las demás actividades y no cambia al etiquetar o archivar.
threadId	string	ID de la conversación a la que pertenece.
from	string	Cabecera From tal cual, con nombre y dirección: Ana Pérez <ana@example.com>. La dirección sola es lo que va entre < y >.
to	string	Cabecera To tal cual (varias direcciones separadas por comas).
cc	string	Cabecera Cc tal cual, o null si no hay.
subject	string	Asunto.
date	string	Cabecera Date tal cual, en formato de correo (Wed, 15 Oct 2026 09:03:22 -0500).
snippet	string	Fragmento del inicio del mensaje, en texto plano.
labels	List<string>	IDs de las etiquetas del correo (INBOX, UNREAD, IMPORTANT, Label_…).
unread	bool	true si el correo está sin leer.
body	string	Solo con includeBody. Cuerpo en texto plano; si el correo solo trae HTML, ese HTML sin etiquetas; "" si no hay cuerpo.
bodyHtml	string	Solo con includeBody. Cuerpo HTML, o null si el correo no lo trae.
attachments	List<Dictionary>	Solo con includeBody. Un elemento por adjunto con filename, mimeType, size (bytes) y attachmentId.

Sin includeBody, las claves body, bodyHtml y attachments no existen en el diccionario. Si nada coincide, devuelve una lista vacía (no falla).

Errores comunes

Mensaje	Causa y solución
No hay una sesión de Gmail disponible. …	No pasaste session y la actividad no está dentro del body de Connect.
Error 400 de Gmail, o lista vacía cuando esperabas correos	labelIds lleva nombres de etiqueta en lugar de IDs. Usa los IDs de Get labels, o label:Nombre en query.
Request had insufficient authentication scopes.	La conexión no tiene permiso de lectura de Gmail. Revisa sus alcances en Zoan Cloud.

Ejemplo

Gmail — Connect   credential = credential("gmail-soporte")
 └─ body:
      Gmail — Get emails   query = "is:unread has:attachment subject:factura"   maxResults = 50   → output: pendientes
      For each   correo in pendientes
       └─ Gmail — Download attachments   id = correo["id"]   folder = "C:\facturas\entrada"   → output: archivos
          Log   message = str(correo["subject"]) + ": " + count(archivos) + " adjunto(s)"
          Gmail — Mark read/unread   id = correo["id"]

Actividades relacionadas

• Gmail — Connect — abrir la sesión.
• Gmail — Get email by ID — traer un correo completo.
• Gmail — Download attachments — guardar los adjuntos de un correo.
• Todas las actividades de Gmail