SMTP Email Notifications

Overview

Faction provides comprehensive email notification capabilities through SMTP integration. The system sends automated emails for user registration, assessment updates, finding assignments, peer reviews, and verification requests.

Configuration

SMTP Server Settings

Configure SMTP in Faction’s system settings:

server: smtp.example.com
port: 587
type: smtp
fromAddress: [email protected]
uname: smtp-username
password: encrypted-password
emailAuth: true
tls: true
emailSSL: false

Configuration Parameters

Parameter	Description	Example
`server`	SMTP server hostname	`smtp.gmail.com`, `smtp.office365.com`
`port`	SMTP server port	`587` (TLS), `465` (SSL), `25` (Plain)
`type`	Mail protocol type	`smtp`
`fromAddress`	Sender email address	`[email protected]`
`uname`	SMTP authentication username	Usually your email address
`password`	SMTP authentication password	Encrypted automatically
`emailAuth`	Enable SMTP authentication	`true` or `false`
`tls`	Enable STARTTLS	`true` or `false`
`emailSSL`	Enable SSL/TLS	`true` or `false`

Environment Variables

Faction can auto-configure SMTP settings from environment variables:

FACTION_SMTP_SERVER=smtp.example.com
FACTION_SMTP_PORT=587
FACTION_SMTP_USER=[email protected]
FACTION_SMTP_FROM_ADDRESS=[email protected]
FACTION_SMTP_PASSWORD=your-smtp-password

If no SMTP configuration exists in the database, Faction automatically initializes settings from these environment variables with the following defaults:

TLS: Enabled
SSL: Disabled
Authentication: Enabled
Type: smtp

Relevant source code: src/com/fuse/dao/SystemSettings.java:112-124

Provider-Specific Configuration

Gmail / Google Workspace

server: smtp.gmail.com
port: 587
fromAddress: [email protected]
uname: [email protected]
password: app-specific-password
emailAuth: true
tls: true
emailSSL: false

Gmail requires an App Password instead of your regular password when 2FA is enabled.

Microsoft 365 / Outlook

server: smtp.office365.com
port: 587
fromAddress: [email protected]
uname: [email protected]
password: your-password
emailAuth: true
tls: true
emailSSL: false

Amazon SES

server: email-smtp.us-east-1.amazonaws.com
port: 587
fromAddress: [email protected]
uname: AWS-SMTP-USERNAME
password: AWS-SMTP-PASSWORD
emailAuth: true
tls: true
emailSSL: false

Amazon SES requires verifying your sender email address or domain before sending emails.

SendGrid

server: smtp.sendgrid.net
port: 587
fromAddress: [email protected]
uname: apikey
password: your-sendgrid-api-key
emailAuth: true
tls: true
emailSSL: false

SendGrid uses “apikey” as the username and your SendGrid API key as the password.

Custom SMTP Server

server: mail.company.com
port: 25
fromAddress: [email protected]
uname: ""
password: ""
emailAuth: false
tls: false
emailSSL: false

Email Customization

Email Prefix and Signature

Customize email subject prefixes and signatures:

prefix: "[Faction Security]"
signature: "Thanks,\nThe Faction Security Team\nhttps://faction.company.com"

Prefix: Prepended to all email subjects (e.g., “[Faction Security] New Finding Assigned”)
Signature: Appended to all email bodies (HTML format supported)

Default values:

Prefix: "Faction: "
Signature: "Thanks,<br>FACTION"

Notification Types

Faction sends email notifications for the following events:

Assessment Notifications

New Assessment Created

Sent to assigned assessors and remediation contacts when a new assessment is created.Recipients:

All assigned assessors
Remediation contact
Distribution list members

Assessment Updated

Sent when assessment details or status changes.Recipients:

Assigned assessors
Remediation contact
Distribution list members

Finding Assigned

Sent when a new finding is created or assigned.Recipients:

Assigned assessors
Remediation contact

Verification Notifications

Verification Requested

Sent when a finding is marked for verification.Recipients:

Original assessor
Assigned remediation contact
Assessment distribution list

Verification Completed

Sent when verification is completed (passed or failed).Recipients:

Original assessor
Remediation contact

Peer Review Notifications

Peer Review Requested

Sent when an assessment is submitted for peer review.Recipients:

All assessors assigned to the parent assessment

Peer Review Completed

Sent when peer review is completed.Recipients:

Original assessors

User Registration

Welcome Email

Sent to new users when their account is created.Contents:

Welcome message
Login instructions
Platform URL

Password Reset

Sent when a user requests a password reset.Contents:

Password reset link
Expiration time

Distribution Lists

Each assessment can have a distribution list for additional email recipients:

[email protected];[email protected];[email protected]

Separate multiple emails with semicolons (;)
Distribution list recipients receive all assessment-related notifications
Configured per-assessment in assessment settings

Calendar Invites

Faction can send calendar invites (.ics files) for assessment-related meetings:

public void sendCalendarInviteInline(String toEmail, String subject, String icsContent)

Calendar invites are sent as multipart MIME messages with:

Plain text alternative
HTML body
iCalendar attachment
Outlook-specific headers for compatibility

Relevant source code: src/com/fuse/utils/SendEmail.java:229-310

Email Templates

HTML Email Support

Faction sends HTML-formatted emails with support for:

Rich text formatting
Inline images (base64 encoded)
Custom signatures
Email prefixes

Image Embedding

Inline images in email content are automatically:

Extracted from HTML content
Decoded from base64
Attached as MIME parts
Referenced in the email body

Relevant source code: src/com/fuse/utils/SendEmail.java:177-210

Testing Email Configuration

Connection Test

Navigate to Settings > Email Configuration
Enter your SMTP settings
Click Test Connection to verify:
- SMTP server connectivity
- Authentication credentials
- TLS/SSL configuration
A test email will be sent to your configured fromAddress

Send Test Email

To verify end-to-end email delivery:

In email settings, use the Send Test Email feature
Enter a recipient email address
Click Send Test
Check the recipient inbox for the test message

Implementation Details

JavaMail Configuration

Faction uses JavaMail with the following properties:

mailServerProperties.put("mail.smtp.port", port);
mailServerProperties.put("mail.smtp.host", server);
mailServerProperties.put("mail.smtp.auth", emailAuth);
mailServerProperties.put("mail.smtp.starttls.enable", tls);
mailServerProperties.setProperty("mail.smtp.ssl.protocols", "TLSv1.2");

SSL/TLS Configuration

For SSL (port 465):

mailServerProperties.put("mail.smtp.socketFactory.class", "javax.net.ssl.SSLSocketFactory");
mailServerProperties.put("mail.smtp.ssl.socketFactory.port", port);
mailServerProperties.put("mail.smtp.socketFactory.fallback", "false");

For STARTTLS (port 587):

mailServerProperties.put("mail.smtp.starttls.enable", "true");
mailServerProperties.setProperty("mail.smtp.ssl.protocols", "TLSv1.2");

Relevant source code: src/com/fuse/utils/SendEmail.java:140-166

Password Encryption

SMTP passwords are encrypted before storage using Faction’s encryption utilities:

String encryptedPassword = FSUtils.encryptPassword(plainPassword);
String decryptedPassword = FSUtils.decryptPassword(encryptedPassword);

Dependencies

Faction includes the JavaMail dependency in pom.xml:

<dependency>
    <groupId>com.sun.mail</groupId>
    <artifactId>javax.mail</artifactId>
    <version>1.5.5</version>
</dependency>

Troubleshooting

Authentication Failed

Verify username and password are correct
Check if your email provider requires an app-specific password
Ensure “less secure app access” is enabled (for Gmail legacy accounts)
Verify the account isn’t locked or suspended

Connection Timeout

Verify the SMTP server hostname and port
Check firewall rules allow outbound SMTP traffic
Test connectivity: telnet smtp.example.com 587
Ensure the SMTP server is running and accessible

TLS/SSL Errors

For port 587, use TLS (STARTTLS)
For port 465, use SSL
Ensure emailSSL and tls settings match your port
Check that TLSv1.2 is supported by your SMTP server

Emails Not Received

Check recipient spam/junk folders
Verify the sender email is not blacklisted
Check email server logs for delivery errors
Ensure SPF/DKIM records are configured for your domain
Verify the fromAddress is allowed to send from your SMTP server

HTML Formatting Issues

Check email content for malformed HTML
Test with plain text first, then add HTML formatting
Verify images are properly base64 encoded
Some email clients may strip certain HTML elements

Best Practices

Use Dedicated SMTP Account

Create a dedicated email account for Faction notifications to improve deliverability and tracking.

Configure SPF and DKIM

Set up SPF and DKIM records for your domain to prevent emails from being marked as spam.

Use TLS Encryption

Always use TLS or SSL for SMTP connections to protect credentials and email content.

Monitor Email Delivery

Regularly check email delivery success rates and investigate failures promptly.

Customize Email Templates

Update email prefix and signature to match your organization’s branding.

Test Before Production

Always test email configuration with test addresses before deploying to production.

Security Considerations

SMTP passwords are encrypted at rest using Faction’s encryption utilities
Always use authenticated SMTP to prevent relay abuse
Use TLS/SSL to encrypt email transmission
Restrict SMTP credentials to Faction’s application account
Regularly rotate SMTP passwords
Monitor email logs for suspicious activity

Getting Started

Core Features

User Guides

Integrations

Extensions

​Overview

​Configuration

​SMTP Server Settings

​Configuration Parameters

​Environment Variables

​Provider-Specific Configuration

​Gmail / Google Workspace

​Microsoft 365 / Outlook

​Amazon SES

​SendGrid

​Custom SMTP Server

​Email Customization

​Email Prefix and Signature

​Notification Types

​Assessment Notifications

​Verification Notifications

​Peer Review Notifications

​User Registration

​Distribution Lists

​Calendar Invites

​Email Templates

​HTML Email Support

​Image Embedding

​Testing Email Configuration

​Connection Test

​Send Test Email

​Implementation Details

​JavaMail Configuration

​SSL/TLS Configuration

​Password Encryption

​Dependencies

​Troubleshooting

​Best Practices

Use Dedicated SMTP Account

Configure SPF and DKIM

Use TLS Encryption

Monitor Email Delivery

Customize Email Templates

Test Before Production

​Security Considerations

Build docs developers (and LLMs) love

Overview

Configuration

SMTP Server Settings

Configuration Parameters

Environment Variables

Provider-Specific Configuration

Gmail / Google Workspace

Microsoft 365 / Outlook

Amazon SES

SendGrid

Custom SMTP Server

Email Customization

Email Prefix and Signature

Notification Types

Assessment Notifications

Verification Notifications

Peer Review Notifications

User Registration

Distribution Lists

Calendar Invites

Email Templates

HTML Email Support

Image Embedding

Testing Email Configuration

Connection Test

Send Test Email

Implementation Details

JavaMail Configuration

SSL/TLS Configuration

Password Encryption

Dependencies

Troubleshooting

Best Practices

Security Considerations