SMTP Integration Guide

Send emails directly from your pipelines using the SMTP connector. This guide covers connection setup, email function configuration, and pipeline integration.

Overview

The SMTP connector provides:

• Multiple recipients with To, CC, and BCC support
• HTML and plain text email bodies with templating
• File attachments using Base64‑encoded content
• Template parameters for dynamic email content
• TLS/SSL encryption with optional certificate configuration
• Popular provider presets for Gmail, Office365, SendGrid, Amazon SES, and more

Connection Configuration

Creating an SMTP Connection

From Connections → New Connection → SMTP, configure the fields below.

SMTP Connection Creation Fields

1. Profile Information

Field	Default	Description
Profile Name	-	A descriptive name for this connection profile (required, max 100 characters)
Description	-	Optional description for this SMTP connection

2. SMTP Server Configuration

Provider Preset

A quick‑fill dropdown to auto‑populate host and port for popular email providers:

Preset	Host	Default Port
Custom SMTP Server	(user specified)	587
Gmail	smtp.gmail.com	587
Microsoft 365 / Outlook	smtp.office365.com	587
Yahoo Mail	smtp.mail.yahoo.com	587
SendGrid	smtp.sendgrid.net	587
Mailgun	smtp.mailgun.org	587
Amazon SES (us-east-1)	email-smtp.us-east-1.amazonaws.com	587
Amazon SES (eu-west-1)	email-smtp.eu-west-1.amazonaws.com	587
MailHog (Local Testing)	localhost	1025

Server Fields

Field	Default	Description
Host	-	SMTP server hostname or IP address (e.g., smtp.example.com) – required
Port	587	SMTP port: 25 (Legacy), 465 (SMTPS/Implicit TLS), 587 (Submission – recommended), 1025 (Testing), 2525 (Alternative) – required
From Email	-	Sender email address (e.g., noreply@example.com) – required
From Name	-	Display name for the sender (e.g., MaestroHub Notifications). Max 100 characters

3. Authentication

Field	Default	Description
Username	-	SMTP authentication username. Often your email address. For SendGrid, use apikey – required
Password	-	SMTP password or App Password (for services with 2FA). Stored securely – required

Provider Authentication Notes

• Gmail/Office365/Yahoo: If 2‑Factor Authentication is enabled, use an App Password instead of your regular account password.
• SendGrid: Use apikey as the username and your SendGrid API key as the password.
• Amazon SES: Use IAM SMTP credentials (not AWS access keys).

4. TLS/SSL Settings

4a. TLS Configuration

Field	Default	Description
Enable TLS	true	Enable encrypted connection (STARTTLS or implicit TLS). Required when using port 465
Skip TLS Verification	false	Skip certificate verification. Only enable for self‑signed certificates or testing
Force Implicit TLS	false	Use implicit TLS on any port (advanced configuration)
TLS Server Name	-	Override hostname for certificate verification (advanced)

4b. Certificates (Optional)

Field	Default	Description
CA Certificate	-	Custom CA certificate for private/enterprise Certificate Authorities. PEM format
Client Certificate	-	Client certificate for mTLS (mutual TLS) authentication. PEM format
Client Private Key	-	Private key for the client certificate. PEM format. Both certificate and key must be provided for mTLS

5. Advanced Settings

Field	Default	Description
Dial Timeout (sec)	30	Connection establishment timeout (5–120 seconds)
Send Timeout (sec)	60	Email send operation timeout (10–300 seconds). Increase for large attachments
Keep-Alive Interval (sec)	30	Interval for keep‑alive pings to maintain persistent connections (10–300 seconds)

Timeout Recommendations

Increase the send timeout when sending emails with large attachments. Keep‑alive helps maintain persistent connections for high‑volume email sending.

6. Connection Labels

Field	Default	Description
Labels	-	Key‑value pairs to categorize and organize this SMTP connection (max 10 labels)

Example Labels

• environment: production
• service: notifications
• team: platform

Notes

• Required Fields: Profile Name, Host, Port, From Email, Username, and Password must be filled.
• Port 465: Requires TLS to be enabled (uses implicit TLS).
• Security: Credentials are stored encrypted and masked on edit. Leave fields empty to keep stored values.
• Provider Presets: Selecting a preset auto‑populates Host and Port with recommended values.

Function Builder

Creating SMTP Functions

After saving the connection:

1. Go to Functions → New Function
2. Choose Send Email as the function type
3. Select the SMTP connection profile
4. Configure recipients, content, and attachments

Design reusable email functions with dynamic content and attachments

Send Email

Purpose: Send emails with dynamic content, multiple recipients, and optional attachments from your pipelines.

Configuration Fields

Function Information

Field	Type	Required	Default	Description
Function Name	String	Yes	-	A descriptive name for this email function (e.g., Send Order Confirmation). Max 100 characters
Description	String	No	-	Optional description of what this email function does
Labels	Key-Value	No	-	Optional labels for categorizing the function

Recipients Configuration

Field	Type	Required	Default	Description
To	Array	Yes	-	Primary recipient email addresses. At least one recipient is required
CC	Array	No	[]	Carbon copy recipients
BCC	Array	No	[]	Blind carbon copy recipients

note

The To, CC, and BCC fields do not support templating. Email addresses must be explicitly provided.

Email Content

Field	Type	Required	Default	Description
Subject	String	Yes	-	Email subject line. Supports ((parameterName)) syntax for dynamic content
Body (Plain Text)	String	Conditional	-	Plain text version of the email body. At least one of Body Text or Body HTML is required
Body (HTML)	String	Conditional	-	HTML version of the email body. At least one of Body Text or Body HTML is required

tip

You can provide both plain text and HTML bodies. Email clients will display HTML if supported, otherwise fall back to plain text.

Attachments

Field	Type	Required	Default	Description
Filename	String	Conditional	-	Attachment filename (e.g., report.pdf). Required if attachment data is provided
MIME Type	Dropdown	No	application/octet-stream	Content type of the attachment
Attachment Data (Base64)	String	No	-	Base64‑encoded file content. Supports templating

Available MIME Types

MIME Type	Description
application/pdf	PDF Document (.pdf)
application/zip	ZIP Archive (.zip)
application/json	JSON File (.json)
application/xml	XML File (.xml)
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	Excel Spreadsheet (.xlsx)
application/vnd.openxmlformats-officedocument.wordprocessingml.document	Word Document (.docx)
image/png	PNG Image (.png)
image/jpeg	JPEG Image (.jpg)
text/plain	Plain Text (.txt)
text/csv	CSV File (.csv)
text/html	HTML File (.html)
application/octet-stream	Binary Data (default)
Custom	Enter any custom MIME type

Advanced Options

Field	Type	Required	Default	Description
Timeout (seconds)	Number	No	60	Override the connection's send timeout for this specific function (1–300)

Use Cases: Send order confirmations, alert notifications, scheduled reports with attachments, welcome emails

Using Parameters

Use ((parameterName)) in supported fields to create dynamic, reusable email functions with content injected at runtime from your pipeline data.

Field	Supports Templating
To / CC / BCC	❌
Subject	✅
Body (Plain Text)	✅
Body (HTML)	✅
Attachment Filename	✅
Attachment Data	✅

Configuration	Description	Example
Type	Validate incoming values	string, number, boolean, datetime, json, buffer
Required	Enforce presence	Required / Optional
Default Value	Provide fallbacks	'Customer', '{}'
Description	Document intent	"Customer name for greeting", "Order ID for subject line"

Parameter validation, defaults, and helper text for dynamic email content

Pipeline Integration

Use the SMTP send email functions you configure here as nodes inside the Pipeline Designer to send notifications, alerts, and reports as part of your automation workflows. Drag in the send email node, bind parameters to upstream outputs or constants, and configure retry behavior for delivery guarantees.

For broader orchestration patterns that combine email notifications with SQL, REST, MQTT, or file operations, see the Connector Nodes page.

SMTP send email node with connection, function, and parameter bindings

Common Use Cases

Order Confirmation Emails

Send dynamic order confirmations with customer details and order information.

Subject with Templating:

Order Confirmation #((orderId))

Body HTML with Templating:

<html>
<body>
  <h1>Hello ((customerName))</h1>
  <p>Thank you for your order #<strong>((orderId))</strong>.</p>
  <p>We will notify you when your order ships.</p>
</body>
</html>

Pipeline Integration: Connect after order processing nodes to send confirmations automatically.

---

Alert Notifications

Send real-time alerts when pipeline conditions trigger thresholds.

Subject with Templating:

⚠️ Alert: ((alertType)) on ((machineName))

Body Text with Templating:

Machine: ((machineName))
Alert Type: ((alertType))
Value: ((currentValue))
Threshold: ((threshold))
Time: ((timestamp))

Please investigate immediately.

Pipeline Integration: Trigger from condition nodes that monitor sensor data or system metrics.

---

Scheduled Reports with Attachments

Distribute generated reports as email attachments on a schedule.

Configuration:

• Attachment Filename: report_((date)).pdf
• Attachment Data: ((reportBase64))
• MIME Type: application/pdf

Pipeline Integration: Schedule via cron triggers, generate report content upstream, then send via SMTP node.

---

Welcome Emails

Send personalized welcome messages when new users are created.

Subject:

Welcome to ((companyName)), ((firstName))!

Body HTML with Templating:

<html>
<body>
  <h1>Welcome, ((firstName)) ((lastName))!</h1>
  <p>Your account has been successfully created.</p>
  <p>Username: <strong>((email))</strong></p>
  <p>Get started by visiting our <a href="((portalUrl))">portal</a>.</p>
</body>
</html>

Pipeline Integration: Connect after user creation workflows or registration webhooks.

Provider-Specific Notes

Gmail

• Port: 587
• Requires App Password if 2FA is enabled
• Enable "Less secure app access" if not using App Password (not recommended)

Microsoft 365 / Outlook

• Port: 587
• Requires App Password if 2FA is enabled
• Modern authentication may require OAuth setup

SendGrid

• Port: 587
• Username: apikey
• Password: Your SendGrid API key

Amazon SES

• Use the region‑specific endpoint (e.g., email-smtp.us-east-1.amazonaws.com)
• Port: 587
• Use IAM SMTP credentials (not AWS access keys)
• Verify sender email/domain in SES console

Mailgun

• Port: 587
• Use your Mailgun SMTP credentials from the dashboard

MailHog (Local Testing)

• Port: 1025
• No authentication required
• Useful for local development and testing

Troubleshooting

Common Issues

Issue	Possible Cause	Solution
Connection timeout	Firewall blocking port	Check firewall rules, try port 587 or 2525
Authentication failed	Wrong credentials	Verify username/password, use App Password for 2FA accounts
TLS handshake failed	Certificate issues	Enable "Skip TLS Verification" for self‑signed certs (testing only)
Email not received	Spam filter	Check spam folder, verify sender domain SPF/DKIM records
Port 465 not working	TLS not enabled	Port 465 requires TLS to be enabled

Testing Your Connection

1. Configure all required fields
2. Click Test Connection to verify SMTP server connectivity
3. Create a Send Email function
4. Use Test Function to send a test email

Debugging Tips

• Start with MailHog for local testing before configuring production SMTP
• Use port 587 (Submission) for most providers
• Always use TLS for production environments
• Check your email provider's SMTP documentation for specific requirements