SMTP / IMAP / POP3 Email Activities

Version: 1.0.5  ·  ID: zoan-packages-smtp  ·  Author: Zoan Software

This package works with email by connecting directly to a server, without depending on an installed client. It works with any standard server that accepts a username and password: Gmail, your company’s mail server or your hosting provider’s.

SMTP/IMAP or the Outlook package?

• This package (SMTP/IMAP/POP3): connects to the server with a username and password. It does not need Outlook installed and works perfectly in unattended execution (a server with no screen). It is the recommended option for production robots.
• The Outlook package: drives the Outlook desktop client already configured on the machine. Useful if you already use Outlook with configured accounts and an interactive session.
• For Microsoft 365 mailboxes with organization sign-in, the Outlook 365 package works directly with the Microsoft account.

Three protocols, three uses

Protocol	What for	Activities
SMTP	Send email	SMTP Send
IMAP	Read and manage email (folders, read/unread, move, delete) — recommended	IMAP Read, IMAP Save Attachment, IMAP Mark Read, IMAP Move, IMAP Delete
POP3	Basic reading (no folders or state) — only if there is no IMAP	POP3 Read, POP3 Delete

IMAP vs POP3

Use IMAP whenever you can: it supports folders, filters, mark as read, move and delete, and each email has a stable identifier. POP3 is an old, limited protocol (it downloads emails without state or folders); use it only if your server does not offer IMAP.

Connecting to the server

These activities do not keep a session: each one connects, signs in, does its work and disconnects. That is why each receives the server connection data. It is the same in all of them:

Parameter	Type	Description
host	string	Server (e.g. smtp.gmail.com, imap.gmail.com, pop.gmail.com).
port	int	Port. Defaults: SMTP 587, IMAP 993, POP3 995.
username	string	Username (usually the full email address).
password	credential	Password or app password. In POP3 it is a string. See credentials.
security	string	Connection encryption: auto, none, ssl or starttls. Defaults: SMTP auto, IMAP and POP3 ssl.

Encryption (security) and ports

Value	What it does	Usual ports
ssl	TLS from the first byte (implicitly encrypted connection).	SMTP 465, IMAP 993, POP3 995
starttls	Connects in clear text and upgrades to TLS with STARTTLS; fails if the server does not offer it.	SMTP 587, IMAP 143, POP3 110
auto	Chooses by port: direct TLS on the well-known SSL ports and STARTTLS on the others if the server offers it; if it does not, it continues unencrypted.	—
none	No encryption. Only for internal test servers.	SMTP 25, IMAP 143, POP3 110

The value is case-insensitive; an unrecognized value is treated as the protocol default. The port does not change by itself when you change security: if you use ssl with SMTP, also set port = 465.

All activities sign in with username and password; SMTP servers that only accept unauthenticated sending are not supported.

Common servers

Provider	SMTP (send)	IMAP (read)	POP3
Gmail	smtp.gmail.com : 587	imap.gmail.com : 993	pop.gmail.com : 995
Corporate server	Your IT team provides the server, port and encryption

Gmail: use an “App Password”, not your normal password

If the account has 2-step verification (common nowadays), the normal password does not work: generate an app password in the account’s security settings and use it. In corporate Microsoft 365 mailboxes, IMAP/POP3/SMTP access with a password depends on what the administrator allows; if it is disabled, use Outlook 365.

Security: store the password in a credential

Never write the password in plain text: store it in a Zoan Cloud credential. With a multi-field credential (for example user and password), the form that works in every activity of the package is:

username = credential("mail-bot")["user"]
password = credential("mail-bot")["password"]

In SMTP and IMAP the password field is of type credential, so it also accepts credential("mail-bot") directly (it takes the password field). In POP3 the field is plain text: always use the indexer: credential("mail-bot")["password"] (or ["value"] if the credential holds a single value). The value is not exposed in the playbook and is masked in the logs.

The read flow: mailId

As in Outlook, IMAP Read (and POP3 Read) return a list of emails (ZoanMail). Each email has an identifier, its .Id, which you pass as mailId to the other activities to say which email to act on (save attachments, mark, move, delete):

• In IMAP it is the message UID in its folder: stable across connections as long as the email stays in that folder.
• In POP3 it is the message index in the mailbox (from 0): it changes when messages are deleted.

IMAP Read   host = "imap.gmail.com"   username = credential("mail-bot")["user"]   password = credential("mail-bot")["password"]
            unreadOnly = true   → output: emails

For Each   items = emails   itemVariable = email
 └─ activities:
      IMAP Save Attachment   ...   mailId = email.Id   outputPath = "C:/attachments"
      IMAP Mark Read         ...   mailId = email.Id

What each email contains (ZoanMail)

Property	Type	Value in IMAP / POP3
.Id	string	UID (IMAP) or index (POP3), as text.
.Subject	string	Subject ("" if empty).
.From	string	Address of the first sender, without the display name.
.To / .Cc	string[]	Recipient addresses.
.Bcc	string[]	Always empty.
.Body	string	Plain-text part; if the email only has HTML, the HTML.
.IsHtml	bool	true only when the email has no text part and .Body is HTML.
.SentAt	DateTime	Date from the message Date header (sent date).
.IsRead	bool	Read state in IMAP; always false in POP3.
.Attachments	ZoanAttachment[]	With includeAttachments = true: name, MIME type and content of each attachment. Otherwise empty.

The full type is in Data types › ZoanMail.

Activities

Send (SMTP)

Activity	Type	Output	What it does
SMTP Send	smtp-send	—	Sends an email

Read and manage (IMAP)

Activity	Type	Output	What it does
IMAP Read	imap-read	List<ZoanMail>	Reads emails with filters
IMAP Save Attachment	imap-save-attachment	—	Saves the attachments of an email
IMAP Mark Read	imap-mark-read	—	Marks an email as read
IMAP Move	imap-move	—	Moves an email to another folder
IMAP Delete	imap-delete	—	Deletes an email

Basic reading (POP3)

Activity	Type	Output	What it does
POP3 Read	pop3-read	List<ZoanMail>	Reads emails (no folders or filters)
POP3 Delete	pop3-delete	—	Deletes an email

Next steps

• SMTP Send — send emails.
• IMAP Read — read the mailbox with filters.
• Using credentials — store the password securely.