IMAP Read

Tipo: imap-read · Paquete: SMTP / IMAP Email Activities v1.0.5 · Salida: List<ZoanMail>

Lee correos de un servidor IMAP y devuelve una lista de mensajes (ZoanMail). Es el punto de partida de los procesos que reaccionan al correo entrante, con filtros que se aplican en el propio servidor para traer solo lo que te interesa. Es la opción recomendada para leer correo (más completa que POP3).

Cómo funciona

Se conecta al servidor (por defecto puerto 993 con ssl), inicia sesión y abre la carpeta folder (por defecto INBOX) en solo lectura: leer no marca los correos como leídos ni los cambia.
Busca en el servidor los correos que cumplen todos los filtros indicados. Por defecto trae solo los no leídos (unreadOnly = true).
Si hasAttachments = true, se queda con los que tienen adjuntos.
Toma los limit más recientes (por defecto 10) y descarga cada mensaje completo; con includeAttachments = true también el contenido de los adjuntos.

Filtros de texto (subject, from): el servidor busca que el campo contenga el texto, normalmente sin distinguir mayúsculas. Filtros de fecha (since, before): se comparan por día (sin hora) con la fecha de llegada al servidor; since incluye ese día y before lo excluye.

Los nombres de carpeta son los del servidor, con su separador ("Procesados", "INBOX/Facturas" o "INBOX.Facturas" según el servidor). En Gmail las etiquetas son carpetas ("[Gmail]/Enviados", etc.).

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
`host`	`string`	—	Servidor IMAP (ej. `imap.gmail.com`).
`username`	`string`	—	Usuario (normalmente el correo completo).
`password`	`credential`	—	Contraseña o App Password. Usa `credential("nombre")["password"]`.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
`port`	`int`	`993`	Puerto IMAP.
`folder`	`string`	`"INBOX"`	Carpeta a leer, con el nombre que usa el servidor.
`unreadOnly`	`bool`	`true`	Solo correos no leídos. Pon `false` para leer todos.
`subject`	`string`	—	Filtro: el asunto contiene este texto.
`from`	`string`	—	Filtro: el remitente (nombre o dirección) contiene este texto.
`since`	`string`	—	Filtro: recibidos desde esta fecha, incluida. Formato `YYYY-MM-DD` (también acepta un `DateTime`). Una fecha que no se pueda interpretar se ignora.
`before`	`string`	—	Filtro: recibidos antes de esta fecha, excluida. Mismo formato que `since`.
`hasAttachments`	`bool`	`false`	Filtro: solo correos con adjuntos.
`includeAttachments`	`bool`	`false`	Descarga el contenido de los adjuntos en `.Attachments` (nombre, tipo MIME y bytes). Aumenta el tiempo y la memoria con adjuntos grandes.
`limit`	`int`	`10`	Máximo de correos a devolver (los más recientes que cumplen los filtros).
`security`	`string`	`"ssl"`	Cifrado: `auto`, `none`, `ssl` o `starttls`. Ver Cifrado y puertos.

Salida

Devuelve una List<ZoanMail> con hasta limit correos, del más antiguo al más reciente dentro de ese grupo. Cada correo trae:

Propiedad	Contenido
`.Id`	UID del mensaje en la carpeta (texto numérico). Úsalo como `mailId` en las demás actividades IMAP con la misma `folder`.
`.Subject`, `.From`, `.To`, `.Cc`	Asunto, dirección del remitente y direcciones de destinatarios.
`.Body` / `.IsHtml`	Texto plano del correo; si solo trae HTML, el HTML con `.IsHtml = true`.
`.SentAt`	Fecha del encabezado `Date` (fecha de envío).
`.IsRead`	Estado leído en el servidor.
`.Attachments`	Adjuntos con contenido si `includeAttachments = true`; si no, vacío.

Si ningún correo cumple los filtros, devuelve una lista vacía (no es un error) y lo indica en el log.

Errores comunes

Mensaje	Causa y solución
`'host' es obligatorio.` / `'username' es obligatorio.`	Falta el parámetro o la expresión dio `null`.
`Parameter 'password' is of type 'credential' but the value was null. Verify the credential exists in the configured store.`	La credencial no existe o no se pudo leer. Revisa el nombre y que el Agent esté conectado a Zoan Cloud.
Error de autenticación del servidor	Usuario o contraseña incorrectos, la cuenta exige App Password o el acceso IMAP está deshabilitado en el buzón.
Error de carpeta no encontrada	`folder` no existe en el servidor. Revisa el nombre exacto y el separador de subcarpetas.
Error de conexión o de TLS	Host o puerto equivocados, o `security` no corresponde al puerto (`993` + `ssl`, `143` + `starttls`).

Ejemplo

Leer los correos no leídos con “Pedido” en el asunto y adjuntos, guardar los adjuntos y marcar cada uno como leído:

IMAP Read
  host     = "imap.gmail.com"
  username = credential("correo-bot")["user"]
  password = credential("correo-bot")["password"]
  subject  = "Pedido"
  since    = today().AddDays(-7).ToString("yyyy-MM-dd")
  hasAttachments = true
  limit    = 25
  → output: correos

For Each   items = correos   itemVariable = correo
 └─ activities:
      IMAP Save Attachment   host = "imap.gmail.com"   username = credential("correo-bot")["user"]   password = credential("correo-bot")["password"]
                             mailId = correo.Id   outputPath = "C:/pedidos/" + correo.Id
      IMAP Mark Read   host = "imap.gmail.com"   username = credential("correo-bot")["user"]   password = credential("correo-bot")["password"]   mailId = correo.Id

Actividades relacionadas

IMAP Save Attachment — guardar adjuntos.
IMAP Mark Read / IMAP Move — gestionar los correos leídos.
Tipos de datos › ZoanMail — propiedades de cada correo.