SMTP Integration Guide

Overview

The SMTP integration allows your NINA workflows to send emails through any SMTP-compatible mail server. This includes services like Office 365, Gmail (via app passwords), AWS SES, self-hosted mail servers, and more. Unlike provider-specific integrations (e.g., Gmail, Outlook), this integration works with any server that speaks SMTP, giving you maximum flexibility.

Status

The integration currently supports:

• Email Sending: Send plain text or HTML emails with full recipient control (To, CC, BCC)
• Attachments: Attach files via base64-encoded content
• Encryption: STARTTLS, implicit TLS, or unencrypted connections
• Authentication: LOGIN and PLAIN SMTP authentication methods

Credential Configuration

Before using the SMTP integration in your workflows, you need to configure credentials for authentication.

Authentication Methods

SMTP Credentials (Basic Auth)

Field	Description	Required	Default	Example
Host	SMTP server hostname	Yes	—	smtp.office365.com
Port	SMTP server port	Yes	587	587, 465, 25
Encryption	Connection encryption method: starttls (port 587), tls (port 465), or none (port 25, not recommended)	No	starttls	starttls, tls, none
Username	SMTP username (usually your email)	Yes	—	[email protected]
Password	SMTP password or app password	Yes	—	—
Auth Method	SMTP authentication method	No	login	login, plain

Encryption Options

Value	Port	Description
starttls	587	Starts unencrypted, upgrades to TLS via STARTTLS command. Recommended for most providers.
tls	465	Implicit TLS from the start. Used by some older or enterprise servers.
none	25	No encryption. Not recommended — only use for internal/trusted networks.

Auth Method Options

Value	Description
login	LOGIN SASL mechanism. Works with most providers (Office 365, Gmail, AWS SES). This is the default.
plain	PLAIN SASL mechanism (RFC 4616). Some servers require this instead of LOGIN.

Provider-Specific Setup

Office 365

Field	Value
Host	smtp.office365.com
Port	587
Encryption	starttls
Username	Your Office 365 email address
Password	Your password or app password

Note: If your organization uses MFA, you must generate an app password in your Microsoft account security settings.

Gmail

Field	Value
Host	smtp.gmail.com
Port	587
Encryption	starttls
Username	Your Gmail address
Password	An app password (not your account password)

Note: You must enable 2-Step Verification and generate an app password at myaccount.google.com/apppasswords. Gmail does not allow direct password authentication for SMTP.

AWS SES

Field	Value
Host	email-smtp.<region>.amazonaws.com
Port	587
Encryption	starttls
Username	Your SES SMTP username (from IAM)
Password	Your SES SMTP password (from IAM)

Note: SES SMTP credentials are not the same as your IAM access keys. Generate them in the AWS SES console under "SMTP settings".

Creating an SMTP Credential

1. Navigate to the Credentials section in NINA
2. Click Add New Credential
3. Fill in the credential details:
   • Name: A descriptive name (e.g., "Office 365 Alerts")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "SMTP"
   • Fill in the authentication fields (Host, Port, Encryption, Username, Password)
4. Click Create to save and validate the credential

Supported Resources and Operations

Email

Operation	Description
Send	Sends an email message with optional attachments

Send Email Parameters

Parameter	Type	Required	Default	Description
to	array	Yes	—	Recipient email addresses
subject	string	Yes	—	Email subject line
body	string	Yes	—	Email body content
contentType	string	No	text	Body content type: text or html
from	string	No	Authenticated username	Sender email address
cc	array	No	—	CC recipient email addresses
bcc	array	No	—	BCC recipient email addresses
replyTo	string	No	—	Reply-to email address
importance	string	No	normal	Email importance: normal, high, or low
attachments	array	No	—	File attachments (see below)

Attachment Format

Each attachment in the attachments array must be an object with:

Field	Type	Required	Description
filename	string	Yes	The file name including extension (e.g., report.pdf)
content	string	Yes	The file content encoded as a base64 string

Parameter Merging

The SMTP integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the SMTP Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When an SMTP Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• The combined parameters are used to execute the send operation

Example: Sending a Plain Text Email

Node Configuration:

{
  "resource": "email",
  "operation": "send",
  "parameters": {
    "to": ["[email protected]"],
    "subject": "Security Alert: Suspicious Login Detected",
    "body": "A suspicious login attempt was detected on your account from IP 203.0.113.42. Please review your recent activity."
  }
}

Example: Sending an HTML Email

Node Configuration:

{
  "resource": "email",
  "operation": "send",
  "parameters": {
    "to": ["[email protected]"],
    "subject": "Weekly Threat Intelligence Report",
    "body": "<h1>Threat Intelligence Report</h1><p>Week of March 10, 2025</p><ul><li><strong>Critical:</strong> 3 new CVEs affecting infrastructure</li><li><strong>High:</strong> Phishing campaign targeting employees</li></ul><p>See the full report in the SOC dashboard.</p>",
    "contentType": "html",
    "cc": ["[email protected]"],
    "importance": "high"
  }
}

Example: Sending an Email with Attachments

Node Configuration:

{
  "resource": "email",
  "operation": "send",
  "parameters": {
    "to": ["[email protected]"],
    "subject": "Monthly Audit Report",
    "body": "Please find the audit report attached.",
    "attachments": [
      {
        "filename": "audit-report-march-2025.csv",
        "content": "aWQsdGltZXN0YW1wLGV2ZW50LHNldmVyaXR5CjEsMjAyNS0wMy0wMVQxMDowMDowMFosImxvZ2luX2ZhaWx1cmUiLCJoaWdoIg=="
      }
    ]
  }
}

Note: The content field must be a valid base64-encoded string. Most upstream nodes that produce file output will already provide base64-encoded content.

Example: Notification with Multiple Recipients

Node Configuration:

{
  "resource": "email",
  "operation": "send",
  "parameters": {
    "to": ["[email protected]", "[email protected]"],
    "cc": ["[email protected]"],
    "bcc": ["[email protected]"],
    "subject": "CRITICAL: Active Incident - Ransomware Detected",
    "body": "<h2>Incident Notification</h2><p>Ransomware activity has been detected on host <code>WS-FIN-042</code>. The host has been isolated. Immediate review required.</p>",
    "contentType": "html",
    "importance": "high",
    "replyTo": "[email protected]"
  }
}

Troubleshooting

Common Issues

1. Connection Timeout:

   • Verify the host and port are correct
   • Check that your network/firewall allows outbound connections on the SMTP port
   • Ensure the encryption setting matches what the server expects (e.g., port 587 usually requires starttls, port 465 requires tls)

2. Authentication Failed:

   • Double-check your username and password
   • If using Office 365 or Gmail with MFA, you must use an app password
   • Try switching the auth method between login and plain — some servers only support one
   • For AWS SES, ensure you're using SMTP credentials (not IAM access keys)

3. Sender Address Rejected:

   • Many SMTP servers only allow sending from the authenticated email address
   • If specifying a custom from address, ensure your server permits it (e.g., "Send As" permissions in Office 365)

4. Emails Going to Spam:

   • Ensure your domain has proper SPF, DKIM, and DMARC records configured
   • Avoid using none encryption in production
   • Use a consistent from address that matches your domain

5. Attachment Errors:

   • Verify the content field is valid base64
   • Check that the filename is present for every attachment
   • Be mindful of SMTP server size limits (commonly 10-25 MB per message)

Best Practices

1. Security:

   • Always use starttls or tls encryption in production
   • Use app passwords instead of account passwords where possible
   • Rotate SMTP credentials periodically

2. Reliability:

   • Keep email body size reasonable — large HTML bodies may be truncated by recipients
   • Test with a single recipient before sending to distribution lists
   • Use the importance field sparingly — overuse reduces its effectiveness

3. Attachments:

   • Keep total message size under your server's limit
   • Use descriptive filenames with proper extensions
   • For large files, consider sending a link instead of an attachment

Updated: 2026-04-16