IMAP Read

IMAP Read

Type: imap-read  ·  Package: SMTP / IMAP Email Activities v1.0.5  ·  Output: List<ZoanMail>

Reads emails from an IMAP server and returns a list of messages (ZoanMail). It is the starting point of processes that react to incoming mail, with filters applied on the server itself to bring only what you need. It is the recommended option for reading mail (more complete than POP3).

How it works

1. Connects to the server (port 993 with ssl by default), signs in and opens folder (default INBOX) in read-only mode: reading does not mark emails as read or change them.
2. Searches the server for emails that match all the filters given. By default it brings only unread emails (unreadOnly = true).
3. If hasAttachments = true, it keeps those with attachments.
4. Takes the limit most recent (default 10) and downloads each full message; with includeAttachments = true also the attachment content.

Text filters (subject, from): the server checks that the field contains the text, usually case-insensitively. Date filters (since, before): compared by day (no time) against the date the message reached the server; since includes that day and before excludes it.

Folder names are the server’s, with its separator ("Processed", "INBOX/Invoices" or "INBOX.Invoices" depending on the server). In Gmail, labels are folders ("[Gmail]/Sent Mail", etc.).

Required parameters

Parameter	Type	Default	Description
host	string	—	IMAP server (e.g. imap.gmail.com).
username	string	—	Username (usually the full address).
password	credential	—	Password or App Password. Use credential("name")["password"].

Optional parameters

Parameter	Type	Default	Description
port	int	993	IMAP port.
folder	string	"INBOX"	Folder to read, with the name the server uses.
unreadOnly	bool	true	Only unread emails. Set false to read all.
subject	string	—	Filter: subject contains this text.
from	string	—	Filter: sender (name or address) contains this text.
since	string	—	Filter: received on or after this date. Format YYYY-MM-DD (a DateTime is also accepted). A date that cannot be parsed is ignored.
before	string	—	Filter: received before this date (exclusive). Same format as since.
hasAttachments	bool	false	Filter: only emails with attachments.
includeAttachments	bool	false	Downloads attachment content into .Attachments (name, MIME type and bytes). Increases time and memory with large attachments.
limit	int	10	Maximum number of emails to return (the most recent matching ones).
security	string	"ssl"	Encryption: auto, none, ssl or starttls. See Encryption and ports.

Output

Returns a List<ZoanMail> with up to limit emails, from oldest to newest within that group. Each email has:

Property	Content
.Id	Message UID in the folder (numeric text). Use it as mailId in the other IMAP activities with the same folder.
.Subject, .From, .To, .Cc	Subject, sender address and recipient addresses.
.Body / .IsHtml	Plain text of the email; if it only has HTML, the HTML with .IsHtml = true.
.SentAt	Date from the Date header (sent date).
.IsRead	Read state on the server.
.Attachments	Attachments with content if includeAttachments = true; otherwise empty.

If no email matches the filters, it returns an empty list (not an error) and says so in the log.

Common errors

Message	Cause and fix
'host' is required. / 'username' is required.	The parameter is missing or the expression returned null.
Parameter 'password' is of type 'credential' but the value was null. Verify the credential exists in the configured store.	The credential does not exist or could not be read. Check the name and that the Agent is connected to Zoan Cloud.
Server authentication error	Wrong username or password, the account requires an App Password, or IMAP access is disabled for the mailbox.
Folder not found error	folder does not exist on the server. Check the exact name and the subfolder separator.
Connection or TLS error	Wrong host or port, or security does not match the port (993 + ssl, 143 + starttls).

Example

Read unread emails with “Order” in the subject and attachments, save the attachments and mark each one as read:

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

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

unreadOnly is on by default

By default IMAP Read brings only unread emails, and reading does not mark them. Combine it with IMAP Mark Read at the end of processing so the same email is not picked up in the next run. To read all, set unreadOnly = false.

Related activities

• IMAP Save Attachment — save attachments.
• IMAP Mark Read / IMAP Move — handle the emails you read.
• Data types › ZoanMail — properties of each email.