Email Notifications

Email notifications allow CompleteFTP to automatically send emails in response to server events such as file uploads, downloads, user logins, and administrative alerts. This provides a lightweight alternative to process triggers when the desired action is simply to notify people — no scripting or external programs required.

Overview

Email notifications include:

• SMTP configuration - Configure the outgoing mail server used for all notifications
• Event-driven emails - Send messages when files are uploaded, downloaded, deleted, or other events occur
• Macro substitution - Include event details (file names, usernames, timestamps, etc.) in subject lines and message bodies
• Flexible filtering - Restrict notifications by file path, user, or site
• Multiple notifications - Define separate notifications for different events, recipients, and purposes

All notification operations use the completeftp notification command group, with SMTP server settings available via completeftp notification smtp.

Note: Email notifications share the same events and macros as process triggers. See Process Triggers for the full events and macros reference.

Configuring SMTP Settings

Before any notifications can be sent, you must configure the outgoing SMTP mail server. These settings apply globally to all notifications.

Viewing SMTP Settings

# Show all SMTP settings
completeftp notification smtp show

Setting SMTP Properties

# Configure the SMTP server host
completeftp notification smtp set host=mail.example.com

# Set the SMTP port (default: 25)
completeftp notification smtp set port=587

# Enable SSL/TLS for SMTP connections
completeftp notification smtp set enableSSL=true

# Set SMTP authentication credentials
completeftp notification smtp set userName=notifications@example.com
completeftp notification smtp set password=SmtpP@ssw0rd

# Set the default "from" address used when notifications do not specify one
completeftp notification smtp set defaultFromAddress=completeftp@example.com

# Configure multiple settings at once
completeftp notification smtp set host=mail.example.com port=587 enableSSL=true \
  userName=notifications@example.com password=SmtpP@ssw0rd \
  defaultFromAddress=completeftp@example.com

SMTP Property Reference

Note: Many SMTP servers require authentication and SSL/TLS. If notifications fail to send, verify that enableSSL, userName, and password are set correctly for your mail provider.

Viewing Notification Information

List Notifications

# List all notifications
completeftp notification list

# List with specific properties
completeftp notification list events to enabled

Show Notification Details

# Show all properties of a notification
completeftp notification show UploadAlert

# Show specific properties
completeftp notification show UploadAlert events to subject

Creating Notifications

Adding a Notification

# Basic syntax
completeftp notification add <name> <events> <to> <from> <subject> <message>

# Notify admin when a file is uploaded
completeftp notification add "UploadAlert" UploadFile \
  admin@example.com completeftp@example.com \
  "File Uploaded: %FileName%" \
  "User %LoginUserName% uploaded %FileName% to %FolderPath% at %DateAndTime% from %ClientIP%."

# Notify on file deletion
completeftp notification add "DeleteAlert" DeleteFile \
  admin@example.com completeftp@example.com \
  "File Deleted: %FileName%" \
  "User %LoginUserName% deleted %FileName% from %FolderPath% at %DateAndTime%."

# Notify on multiple events
completeftp notification add "TransferNotice" UploadFile,DownloadFile \
  transfers@example.com completeftp@example.com \
  "%Event%: %FileName%" \
  "%LoginUserName% performed %Event% on %FilePath% via %Protocol% at %DateAndTime%."

# Notify on user login
completeftp notification add "LoginAlert" LogIn \
  security@example.com completeftp@example.com \
  "User Login: %LoginUserName%" \
  "User %LoginUserName% logged in from %ClientIP% via %Protocol% at %DateAndTime%."

Notification for Server Events

# Notify when server starts or stops
completeftp notification add "ServerStatus" StartServer,StopServer \
  ops@example.com completeftp@example.com \
  "Server %Event%: %ServerName%" \
  "The CompleteFTP server %ServerName% triggered event %Event% at %DateAndTime%."

# Notify on certificate expiry
completeftp notification add "CertExpiry" CertificateExpiring,CertificateExpired \
  admin@example.com completeftp@example.com \
  "Certificate Alert: %Event%" \
  "Certificate event %Event% on site %SiteName% at %DateAndTime%. Please review and renew certificates."

# Notify on auto-ban events
completeftp notification add "AutoBanAlert" AutoBan \
  security@example.com completeftp@example.com \
  "IP Auto-Banned on %SiteName%" \
  "An IP address was auto-banned on %SiteName% at %DateAndTime%. Check server logs for details."

Modifying Notifications

Changing Notification Properties

# Enable or disable a notification
completeftp notification set UploadAlert enabled=false
completeftp notification set UploadAlert enabled=true

# Change the recipient address
completeftp notification set UploadAlert to=newadmin@example.com

# Change the sender address
completeftp notification set UploadAlert from=alerts@example.com

# Update the subject line
completeftp notification set UploadAlert "subject=Upload Notification: %FileName% by %LoginUserName%"

# Update the message body
completeftp notification set UploadAlert \
  "message=File %FileName% (%FileSize% bytes) was uploaded by %LoginUserName% to %FolderPath% at %DateAndTime% from IP %ClientIP% via %Protocol%."

# Change which events trigger the notification
completeftp notification set UploadAlert events=UploadFile,MoveFile

Notification Property Reference

Filters

Filters restrict when a notification fires based on the file path, user, or site involved in the event. These work the same way as process trigger filters (see Process Triggers - Filters).

Path Filter

The path filter matches against the virtual file path of the operation. It uses wildcard patterns by default.

# Only notify for .csv files uploaded to /Uploads
completeftp notification set UploadAlert pathFilter="/Uploads/*.csv"

# Notify for any PDF file in any directory
completeftp notification set UploadAlert pathFilter="*/*.pdf"

# Use regex for complex patterns
completeftp notification set UploadAlert 'pathFilter=regex:^/Home/.*\.xlsx$'

# Inverse filter - notify for all files EXCEPT .tmp files
completeftp notification set UploadAlert pathFilter="*.tmp" pathFilterInverse=true

User Filter

# Notify only for specific users
completeftp notification set UploadAlert users=alice,bob

# Inverse - notify for all users EXCEPT service accounts
completeftp notification set UploadAlert users=serviceaccount userFilterInverse=true

Site Filter

# Notify only for a specific site (Enterprise MFT only)
completeftp notification set UploadAlert sites="External Site"

# Inverse - notify for all sites except internal
completeftp notification set UploadAlert sites="Internal" siteFilterInverse=true

Macros

Macros are placeholders replaced with event-specific values at runtime. They can be used in the subject and message fields of a notification.

Important: The full list of available macros is shared with process triggers. See Process Triggers - Macros for the complete reference.

Commonly Used Macros in Notifications

Macro Examples in Notifications

# Detailed upload notification with macros
completeftp notification add "DetailedUpload" UploadFile \
  admin@example.com completeftp@example.com \
  "[%SiteName%] Upload: %FileName% by %LoginUserName%" \
  "Upload Details:
File: %FileName%
Path: %FilePath%
Size: %FileSize% bytes
User: %LoginUserName% (%LoginEmail%)
IP: %ClientIP%
Protocol: %Protocol%
Time: %Timestamp:yyyy-MM-dd HH:mm:ss%
Status: %TransferStatus%"

# Notification with custom timestamp format
completeftp notification add "TimestampExample" DownloadFile \
  reports@example.com completeftp@example.com \
  "Download on %Timestamp:yyyy-MM-dd%" \
  "File %FileName% was downloaded by %LoginUserName% at %Timestamp:HH:mm:ss% on %Timestamp:yyyy/MM/dd%."

Removing Notifications

# Remove a notification by name
completeftp notification remove UploadAlert

# Verify removal
completeftp notification list

Workflow Examples

Upload Notification for Compliance

Notify the compliance team whenever files are uploaded to a regulated folder:

# 1. Configure SMTP
completeftp notification smtp set host=smtp.example.com port=587 \
  enableSSL=true userName=ftpalerts@example.com password=Str0ngP@ss \
  defaultFromAddress=ftpalerts@example.com

# 2. Create the notification
completeftp notification add "ComplianceUpload" UploadFile \
  compliance@example.com ftpalerts@example.com \
  "Compliance Upload: %FileName% by %LoginUserName%" \
  "A file has been uploaded to a regulated folder.

File: %FileName%
Path: %FilePath%
Size: %FileSize% bytes
User: %LoginUserName%
IP Address: %ClientIP%
Protocol: %Protocol%
Date/Time: %Timestamp:yyyy-MM-dd HH:mm:ss%

Please review this upload for compliance requirements."

# 3. Restrict to the regulated folder
completeftp notification set ComplianceUpload pathFilter="/Regulated/*"

Security Alerts for Failed Logins

Notify the security team about login events from specific accounts:

# Create login notification for privileged accounts
completeftp notification add "PrivilegedLogin" LogIn \
  security@example.com completeftp@example.com \
  "Privileged Login: %LoginUserName% from %ClientIP%" \
  "A privileged account login was detected.

User: %LoginUserName%
IP: %ClientIP%
Protocol: %Protocol%
Time: %DateAndTime%
Site: %SiteName%"

# Restrict to privileged users only
completeftp notification set PrivilegedLogin users=admin,rootuser,ftpadmin

Certificate Expiry Monitoring

Keep track of certificate lifecycle events:

# Create a notification for certificate warnings
completeftp notification add "CertWarning" CertificateExpiring \
  admin@example.com completeftp@example.com \
  "WARNING: Certificate expiring on %SiteName%" \
  "A TLS certificate on site %SiteName% is expiring within 30 days.

Server: %ServerName%
Site: %SiteName%
Date: %DateAndTime%

Please renew the certificate before it expires to avoid service disruption."

# Create a separate notification for expired certificates
# Note: use a distribution list address to notify multiple recipients
completeftp notification add "CertExpired" CertificateExpired \
  ops-team@example.com completeftp@example.com \
  "CRITICAL: Certificate expired on %SiteName%" \
  "A TLS certificate on site %SiteName% has expired.

Server: %ServerName%
Site: %SiteName%
Date: %DateAndTime%

Immediate action required. Clients may be unable to connect securely."

Multi-Event File Activity Summary

Notify on all file operations for a high-value folder:

# Create a broad file activity notification
completeftp notification add "FileActivity" \
  UploadFile,DownloadFile,MoveFile,DeleteFile \
  audit@example.com completeftp@example.com \
  "[%SiteName%] %Event%: %FileName%" \
  "File activity detected on %SiteName%.

Event: %Event%
File: %FileName%
Path: %FilePath%
User: %LoginUserName% (%LoginFullName%)
IP: %ClientIP%
Protocol: %Protocol%
Status: %TransferStatus%
Time: %Timestamp:yyyy-MM-dd HH:mm:ss%"

# Restrict to the sensitive folder
completeftp notification set FileActivity pathFilter="/Sensitive/*"

Server Lifecycle Notifications

Notify operations staff about server start/stop events:

# Notify on server and site lifecycle events
completeftp notification add "ServerLifecycle" StartServer,StopServer,StartSite,StopSite \
  ops@example.com completeftp@example.com \
  "CompleteFTP %Event%: %ServerName%" \
  "Server lifecycle event on %ServerName%.

Event: %Event%
Server: %ServerName%
Site: %SiteName%
Time: %DateAndTime%"

Troubleshooting

Notifications Not Sending

# Verify SMTP settings are configured
completeftp notification smtp show

# Check that the notification is enabled
completeftp notification show UploadAlert enabled

# Verify the events are correct
completeftp notification show UploadAlert events

# Check if filters are excluding the operation
completeftp notification show UploadAlert pathFilter pathFilterInverse users userFilterInverse

# Enable debug logging for detailed notification logs
completeftp monitor set logging.level=Debug

SMTP Connection Failures

# Verify all SMTP settings (host, port, SSL, credentials)
completeftp notification smtp show

# Test connectivity to the SMTP server from the command line
nc -zv mail.example.com 587

Emails Going to Spam

• Ensure the from address matches a valid domain with proper SPF and DKIM records
• Use a defaultFromAddress on a domain you control
• Avoid generic subject lines that spam filters may flag
• Verify your SMTP server is not on any blocklists

Macros Not Expanding

• Confirm macros are spelled correctly with percent signs: %FileName% not FileName
• Some macros are only available for certain events. For example, %FileName% is not available for StartServer or StopServer events
• See Process Triggers - Events for which macros are available per event

Duplicate Notifications

• Check for overlapping notifications with similar event and filter configurations
• Use completeftp notification list events to pathFilter to compare active notifications
• Disable or remove redundant notifications

Best Practices

SMTP Configuration

1. Use SSL/TLS - Always enable enableSSL=true when your SMTP server supports it
2. Use a dedicated sender address - Set defaultFromAddress to a recognizable address like completeftp@example.com
3. Use application passwords - If your SMTP provider supports them, use app-specific passwords rather than primary account credentials
4. Test early - Configure and test SMTP settings before creating production notifications

Notification Design

1. Descriptive names - Name notifications to describe their purpose (e.g., ComplianceUpload, CertExpiry)
2. Informative subjects - Include key details in the subject line using macros so recipients can triage without opening
3. Structured messages - Use a consistent format in message bodies for easy scanning
4. Targeted recipients - Send notifications only to people who need to act on them

Filtering

1. Use path filters - Restrict file-related notifications to relevant folders to avoid noise
2. Use user filters - Exclude service accounts or batch users that generate high volumes of events
3. Combine with triggers - Use notifications for alerting and process triggers for automation; avoid duplicating logic between them

Maintenance

1. Review periodically - Disable notifications that are no longer needed to reduce email noise
2. Monitor delivery - Check server logs if recipients report missing notifications
3. Update recipients - Keep to addresses current as team members change
4. Document purpose - Use descriptive names and maintain records of what each notification does

Quick Reference

SMTP Commands

# Show SMTP settings
completeftp notification smtp show

# Configure SMTP
completeftp notification smtp set property=value [property=value ...]

Notification Management Commands

# List notifications
completeftp notification list [properties]

# Show notification details
completeftp notification show [<name>] [properties]

# Add notification
completeftp notification add <name> <events> <to> <from> <subject> <message>

# Modify notification
completeftp notification set <name> property=value [property=value ...]

# Remove notification
completeftp notification remove <name>

SMTP Properties

host               = SMTP server hostname
port               = SMTP server port (default: 25)
userName           = SMTP authentication username
password           = SMTP authentication password
enableSSL          = Enable SSL/TLS (default: false)
defaultFromAddress = Default sender email address

Notification Properties

name               = Notification name
events             = Comma-separated event list
to                 = Recipient email address
from               = Sender email address
subject            = Email subject (supports macros)
message            = Email body (supports macros)
enabled            = true or false

Common Macros

%FileName%        = File name
%FilePath%        = Virtual file path
%FolderPath%      = Virtual folder path
%FileSize%        = File size in bytes
%LoginUserName%   = Logged-in user
%LoginEmail%      = User email address
%ClientIP%        = Client IP address
%SiteName%        = Site name
%Protocol%        = Protocol used
%Event%           = Event type
%TransferStatus%  = success or failure
%DateAndTime%     = Date and time of event
%Timestamp:fmt%   = Custom formatted timestamp

Event Names

UploadFile, DownloadFile, MoveFile, DeleteFile
CreateFolder, MoveFolder, DeleteFolder
LogIn, LogOut, ChangeDirectory
Timer, StartServer, StopServer, StartSite, StopSite
AutoBan, CertificateExpiring, CertificateExpired, ClusterSyncFailed