Mail client

Sends an e-mail over SMTP for every record it receives. The mail is either fully described by an incoming SmtpMessage, or built from the configuration (recipient, subject, body) with the body optionally taken from a TextRecord. Use it for notifications, reports and replies to collected mail.

Pins

Pin	Kind	Types	Description
Input	input	Viaducta.Plugins.Smtp.Types.SmtpMessage, Viaducta.Plugins.TextPlugin.Types.TextRecord, Viaducta.TypeSystem.Metadata.NoInputData	Triggers sending one mail per record.
Continue	continue	Viaducta.Plugins.Smtp.Types.SmtpMessage	Called after the mail was handed to the SMTP server, with the original input data and metadata.

Configuration

Field	Type	Default	Description
Host	string	viaducta.mail.service	Required. SMTP server host name or IP. The special value viaducta.mail.service sends through the platform's own SMTP settings (see Behaviour).
Port	integer	25	SMTP port, 1-65535. Typical values: 25, 587 (STARTTLS), 465.
AuthType	dropdown	0	How to sign in, see Authentication.
UserName	string (max 256)		SMTP user name (mailbox address with OAuth2). Leave empty for servers without authentication. Also used as the default sender address.
Password	password (max 256)		SMTP password or app password, AuthType 0 only. Use an expression setting (=Secrets.SmtpPassword) instead of a literal value.
EnableSSL	boolean	true	Use TLS for the SMTP connection.
To	string		Recipient(s) for TextRecord / NoInputData input. Separate several addresses with ,, ; or space.
Subject	string		Subject for TextRecord / NoInputData input; fallback subject for an SmtpMessage whose Subject is null.
Body	text (multi-line)		Body for NoInputData input; fallback body for an SmtpMessage with an empty Body.

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.

• The mail client sends OAuth2 mail through MailKit: EnableSSL with port 465 is TLS from the start, other ports require STARTTLS; without EnableSSL STARTTLS is used when offered. Password sign-in keeps using the .NET SMTP client.

• With Host = viaducta.mail.service the authentication settings are not used.

Behaviour

How the mail is filled, per input type:

Mail part	SmtpMessage input	TextRecord input	NoInputData input
From	MailFrom; if empty UserName; if still empty and Host is viaducta.mail.service, [email protected]; otherwise error	UserName (or [email protected] with the platform service)	same as TextRecord
To	To (required, config To is ignored)	config To	config To
CC / Bcc	CC, Bcc	none	none
Subject	Subject, else config Subject, else "No subject provided"	config Subject	config Subject
Body	Body, else config Body	TextRecord.Value	config Body
HTML	IsBodyHtml as given	auto: HTML if the body contains <body	auto: HTML if the body contains <body
Priority	Priority: 0 Normal, 1 Low, 2 High	Normal	Normal
Attachments, headers	Attachments (FileName, ContentType, Content bytes), Headers, MessageId (written as Message-ID), InReplyTo (In-Reply-To), References (References, space-separated)	none	none
Reply to	ReplyTo (split like To)	none	none

• Address lists (To, CC, Bcc) are split on ,, ; and space; each part must be a plain address.
• Body encoding is UTF-8.
• Host = viaducta.mail.service: host, port, SSL and credentials come from the platform SMTP configuration; Port, EnableSSL, UserName and Password of the component are not used for the connection.
• Any other host: a new SMTP connection is made with Host, Port, EnableSSL; credentials are sent only when UserName is set.
• On start the flow fails if Host is empty or Port is out of range. Send errors (authentication, rejected recipient, missing To/MailFrom, attachment without FileName or ContentType) throw an exception for the record.

Notes

• For TextRecord and NoInputData input the mail's Sender header is always the platform SMTP user name, also when a custom Host is configured. If the platform SMTP user name is not set, these inputs fail with an invalid address error; send an SmtpMessage (its sender is MailFrom) to avoid it.
• With SmtpMessage input only an empty or null Body falls back to the config Body, and only a null Subject (not an empty string) falls back to the config Subject.
• Message ids (MessageId, InReplyTo, References) can be given with or without angle brackets; the headers get them added when missing.
• Display-name addresses such as John Doe <[email protected]> are broken apart by the space separator; use plain addresses.
• The SmtpMessage.Priority field declares a default of 1, which means Low; set 0 explicitly for normal priority when you build the message in a mapper.
• Continue is declared as SmtpMessage, but it forwards whatever was received (also a TextRecord or NoInputData).
• Combine with Mail collector to answer incoming mail: copy the received MessageId into InReplyTo and swap MailFrom / To in a mapper.

Example

{ "Host": "smtp.example.com", "Port": 587, "EnableSSL": true, "UserName": "[email protected]", "Password": "=Secrets.SmtpPassword", "To": "[email protected]", "Subject": "Daily report" }

Timer → (component producing a TextRecord with the HTML or text body) → Mail client