Mail collector

Downloads e-mail from a mailbox over IMAP or POP3 and emits every message as a SmtpMessage. Trigger it periodically (for example from a timer) to process incoming mail, optionally deleting it from the server after processing.

Pins

Pin	Kind	Types	Description
Start	start	any	Starts one collection run. When unconnected, the system calls it once when the flow starts.
Output	output	Viaducta.Plugins.Smtp.Types.SmtpMessage	Called once per downloaded message.
Continue	continue	Viaducta.TypeSystem.Metadata.NoInputData	Called once after the collection run finished, also when no message was collected.

Configuration

Field	Type	Default	Description
Protocol	dropdown: 1 IMAP, 2 POP3	1	Mailbox protocol.
Host	string		Required. Host name or IP of the IMAP / POP3 server.
Port	integer	993	Server port. Typical: IMAP 993 (SSL) / 143, POP3 995 (SSL) / 110. Change it when you switch to POP3.
AuthType	dropdown	0	How to sign in, see Authentication.
UserName	string (max 256)		Mailbox user (mailbox address with OAuth2). With AuthType 0 and empty, no authentication is done.
Password	password (max 256)		Mailbox password or app password, AuthType 0 only. Use an expression setting (=Secrets.MailboxPassword).
Folder	string (max 256)	Inbox	IMAP folder to read. Only visible and used when Protocol is 1.
EnableSSL	boolean	true	true: TLS from the start of the connection (ports 993 / 995). false: plain connection, upgraded with STARTTLS when the server offers it (ports 143 / 110).
DeleteAfter	boolean	false	Delete each message from the server after it was emitted on Output.

Authentication

AuthType selects how the component signs in. Every option runs unattended: tokens are fetched, cached in memory and renewed by the engine, so nobody has to sign in while flows run. Store secrets as expression settings (=Secrets.X).

AuthType	Fields	Use for
0 Username and password (default)	UserName, Password	Classic servers; Gmail / Google accounts with an app password. No sign-in when UserName is empty.
1 OAuth2 client credentials	TokenEndpoint, ClientId, ClientSecret, Scope	Microsoft 365 / Exchange Online, app-only: endpoint https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token, scope https://outlook.office365.com/.default. The Entra app needs the IMAP / POP / SMTP .AccessAsApp permission and an Exchange service principal with mailbox access.
2 OAuth2 refresh token	TokenEndpoint (empty = Google), ClientId, ClientSecret, RefreshToken, optional Scope	Personal Gmail accounts. Get the refresh token once (for example with the Google OAuth Playground, scope https://mail.google.com/), using an OAuth client whose consent screen is published: in Testing status Google expires refresh tokens after 7 days.
3 Google service account	ServiceAccountKey (JSON key), optional Scope	Google Workspace. Needs domain-wide delegation of https://mail.google.com/; the service account acts as the mailbox in UserName.
4 OAuth2 access token	AccessToken	A token produced elsewhere, e.g. by an expression. Not renewed by the component.

• With OAuth2 (1-4) UserName is the mailbox address and is required; the sign-in uses SASL XOAUTH2.
• If the server rejects a cached token, the component fetches a new one and retries once.
• Refresh tokens rotated by the server are kept in memory for the life of the engine process; the configured RefreshToken is used again after a restart.

Behaviour

• Every call on Start connects, authenticates (if UserName is set), reads all messages in the folder (IMAP) or mailbox (POP3), and disconnects. Messages are processed from newest to oldest, one at a time; each Output call is awaited before the next message is downloaded.
• Each message is converted to SmtpMessage:
  • MailFrom: address of the first From mailbox; To, CC, Bcc: "Name" <address> entries joined with ; ; ReplyTo: Reply-To addresses joined with ;.
  • Subject, MessageId, InReplyTo, References, ReceiveDateTime (the message Date header).
  • Body: the HTML body when present (IsBodyHtml = true), otherwise the plain-text body.
  • Priority: 2 urgent, 1 non-urgent, 0 normal.
  • Attachments: every attachment part with FileName, ContentType and decoded Content bytes.
  • Headers: all headers except From, To, Subject, Date, Message-ID, MIME-Version and Delivered-To.
• DeleteAfter = true: IMAP messages are flagged deleted after their Output call and expunged at the end of the run; POP3 deletions are committed when the session ends normally.
• After the last message (and the IMAP expunge) the component disconnects and calls Continue once with a NoInputData record.
• Connection, authentication or folder errors throw an exception for the Start call; Continue is then not called.

Notes

• There is no "unread only" or "new since last run" filter: with DeleteAfter = false every run emits the whole mailbox again. Either enable DeleteAfter, or de-duplicate on MessageId downstream.
• If processing of a message throws, the run stops; already processed IMAP messages are flagged but not expunged, and POP3 deletions of that run are not committed.
• The IMAP folder is opened read-write, so the server may mark fetched messages as read.
• ReceiveDateTime is the date and time from the Date header in the sender's time zone (the offset is dropped).
• Very large mailboxes are read in one run; for an archive, use a dedicated folder and DeleteAfter.

Example

{ "Protocol": 1, "Host": "imap.example.com", "Port": 993, "EnableSSL": true, "UserName": "[email protected]", "Password": "=Secrets.MailboxPassword", "Folder": "Inbox", "DeleteAfter": true }

Timer → Mail collector → (map SmtpMessage fields, store attachments) → ...