Home Back to Tutorial Online Help

Set up email notification in the Xlight FTP Server

System administrators can set up email notifications for some events that happen in the Xlight FTP Server, such as when a file is uploaded or hard disk space is low. The system administrator will receive a notification email when an event happens.

In this example, we will show you how to set up email notifications. Note: after the 30-day evaluation period, this function is only supported by the Professional edition of Xlight FTP Server.

1. To use email notifications, you have to enable this function in the virtual server as shown in the figure below.


2. Then you will need to set up an SMTP server for sending notification emails. We will use Gmail as an example. Because for sending email through Gmail SMTP server, TLS protocol must be used for encrypting connection. We select the SSL/TLS connection option and use port 465 for Gmail. However, for most corporate internal e-mail servers, standard SMTP port 25 is always supported and SSL/TLS port 465 may not be supported for sending email. It is not necessary or even possible to use SSL/TLS for corporate internal e-mail servers.

3. You must also select the email notification configuration file. This file is used to configure events triggering the FTP server to send email. An email notification configuration file is a text file that has the settings about events you want to receive email notifications. You can edit this file by using Notepad.


4. You will need to set up the SMTP User Authentication settings and Email Settings. To set up the SMTP User Authentication, you need to have a valid account in the email server, as shown in the figure below.


Events supported for the email notification

There are 7 email notification events supported by the Xlight FTP Server. The following table is the list of events supported by the Xlight FTP Server.

Event nameEvent Description
OnFileUploadThis event is triggered when a file being uploaded.
OnFileDownloadThis event is triggered when a file being downloaded.
OnFileDeleteThis event is triggered when a file being deleted.
OnDiskSpaceLowThis event is triggered when hard disk space is low.
OnLoginThis event is triggered when the user successfully logs in.
OnLogoutThis event is triggered when the user logs out.
OnWanIPChangeThis event is triggered when the WAN IP changes after the server starts.

5. If you want to receive an email notification, you have to put the event type in the email notification configuration file. You can also use parameters to further restrict the conditions that the email notification will be sent. The figure below is a sample email notification configuration file with 5 events.


After a file is uploaded, downloaded, or deleted or when disk space is periodically checked in the virtual server, all these actions will cause the FTP Server to check the email notification configuration file preloaded in the memory. FTP Server uses current action to check against events and conditions at every line of this configuration file. If a line can pass the check, an email will be sent. After finding a matched line, the Xlight FTP Server will not check lines below it anymore. The sequence of lines in the configuration file will have an impact on the email notification. You would better put lines with specific conditions at the top and lines with general conditions at the bottom.

Each line in the configuration file is checked from left to right. In the figure above, OnFileUpload is the event of the first line. The parameter $file sets the file types. $file has two values *.exe and *.bat. If a file with extension *.exe or *.bat is uploaded by a user, it can meet both the OnFileUpload event and file type conditions of the first line. The user upload action will then be checked against the $dir parameter. $dir parameter restricts the upload directories to be in the virtual path /public or its sub-directories.

If all conditions above are met, an email will be sent to notify that a file with extension *.exe or *.bat is uploaded in the virtual path /public or its sub-directories.

The parameter $email_file in the first line is not a condition. It is used to specify a file for customizing email messages. If you don't use $email_file parameter, Xlight FTP Server will generate a default email message. In the file specified in the $email_file, you can use your own TO, CC and BCC addresses for people to receive this email. It will replace the default TO address in the Email Settings.

Samples for email notification configuration.

Example 1. Receive the email notification when the free disk space of C is below 100 MB or the free disk space of D is below 200 MB.

OnDiskSpaceLow $disk_space=C(100),D(200)

Example 2. Receive the email notification when a file uploaded is larger than 2000 MB.

OnFileUpload $file_size>2000

Example 3. Receive the email notification when the user test uploaded a file with an extension gif, jpg, or png.

OnFileUpload $file=*.gif,*.jpg,*.png; $user=test

Example 4. Receive the email notification when someone uploaded a file with a name containing forbidden words, such as sex or porn.

OnFileUpload $file=*sex*,*porn*;

Example 5. Receive the email notification when a user logs out, and he had uploaded at least one file.

OnLogout $up_files>0;

Example 6. Receive the email notification when the user "tester" logs in.

OnLogin $user=tester;

Example 7. Receive the email notification when all users log in except the "anonymous" user.

OnLogin $user=*; $exclude_user=anonymous;

Below are the supported parameters for the email notification configuration file.

Parameters supported for the email notification configuration file

Parameter nameAllow multiple valuesUNIX shell-style wildcardsValue Description
$fileYesYesThe name of the file.
$dirYesYesThe directory where events happened in. The directory can be either an FTP virtual path such as "/public" or a DOS path such as "C:\test". Use wildcards to include sub-directories. For example, to include all sub-directories of "C:\test", you can write it as "C:\test\*".
$userYesYesThe name of the user.
$groupYesYesThe user group.
$exclude_fileYesYesThe name of the file excluded from triggering event.
$exclude_dirYesYesThe directory excluded from triggering event.
$exclude_userYesYesThe name of the user excluded from triggering event.
$exclude_groupYesYesThe user group excluded from triggering event.
$file_sizeNoNoThe file size in MB. For example, if you want the OnFileUpload event to be triggered when the uploaded file is above 1000M, you can write it as $file_size>=1000. File size can be float value (with version 3.8.6.1 and above). This parameter doesn't support multiple values.
$down_filesNoNoThe number of files the user downloaded. For example, if you want the OnLogout event to be triggered when the user has at least downloaded 10 files, you can write it as $down_files>=10. This parameter doesn't support multiple values.
$up_filesNoNoThe number of files the user uploaded. For example, if you want the OnLogout event to be triggered when a user has at least uploaded 1 file, you can write it as $up_files>=1. This parameter doesn't support multiple values.
$disk_spaceYesNoThe condition for triggering disk space low warning. This entry starts with the hard drive letter and brackets with free disk space in MB. For example, if we want to receive a warning when free disk space in hard drive E is lower than 500M, we can write it as E(500). After setting this parameter, the Xlight FTP Server will check disk space for configured drives every 30 minutes. So if your current disk space is above the threshold, but for some reason you received an unexpected low disk space warning email. Please check if you have any scheduled job (such as backup) that will temporarily reduce the disk space usage in the configured drive.
$email_fileNoNoCustomize email message to be sent when an event is triggered. You can put many TO, CC and BCC addresses in the content of this file. They will override the default TO address in the Email Settings. There are no limits on the number of TO, CC and BCC addresses in this file. However, SMTP servers may have limitations. Also, the size of the email message file is limited to 16K. Another useful tip is that this file is read by the Xlight FTP Server just before sending an email. It can be useful if you want to change the email content dynamically. For example, if you have a nightly code build job generating a log. After the build is finished, before uploading the log file to the FTP Server, you can use a script to write a customized email file, which includes the build result and recipient email addresses. Upload this email file to the FTP server before uploading the log file. So people in the morning will receive an email with the result of the nightly build job and the location of the log file.

Some parameters allow multiple values. Multiple values are separated by the comma ",". For parameters with multiple values, the relationship between values is OR. For example $user = a*, c* means the user's login name must start with the character a or b. If a line with multiple parameters, all conditions must be met to trigger the event for this line. For parameters not shown in the line, their conditions are met automatically.

The content of the email message file is set in the $email_file parameter

The figure below is the content of a sample email message file specified in the parameter $email_file. Strings start with character % are variables, which will be replaced with actual values before an email message is sent.

Note: there must be no blank lines in the email header. The email header and email content are separated by one blank line. You can have as many blank lines as you want in the email content, as shown in the figure below.


6. Below are supported variables for the content of the email message file. Please note the difference: Variables in the email message file start with the character %, but parameters in the email notification configuration file start with the character $.

Variables supported for the email message file

Variable nameValue Description
%filenameIt will be replaced with the name of the file being uploaded, downloaded or deleted.
%down_filelistThe name list of the last 100 files being downloaded. Filenames are separated by a comma.
%up_filelistThe name list of the last 100 files being uploaded. Filenames are separated by a comma.
%file_sizeIt will be replaced with the size of the file (in bytes) being uploaded, downloaded or deleted.
%file_size_mbIt will be replaced with the size of the file (in MBytes) being uploaded, downloaded or deleted.
%downfilesIt will be replaced with the number of the files the user downloaded.
%upfilesIt will be replaced with the number of the files the user uploaded.
%totaldownIt will be replaced with the total amount the user downloaded.
%totalupIt will be replaced with the total amount the user uploaded.
%usernameIt will be replaced with the name of the user who uploads, downloads or deletes the file.
%passwordIt will be replaced with the password of the user who uploads, downloads or deletes the file.
%groupnameIt will be replaced with the name of the user group who uploads, downloads or deletes the file.
%virtual_pathIt will be replaced with the name of the virtual path where the file is uploaded, downloaded or deleted.
%real_pathIt will be replaced with the name of the DOS path where the file is uploaded, downloaded or deleted.
%client_ipIt will be replaced with the IP address of the user who uploads, downloads or deletes the file.
%server_ipIt will be replaced with the IP address of the virtual server where the file is uploaded, downloaded or deleted.
%server_portIt will be replaced with the port of the virtual server where the file is uploaded, downloaded or deleted.
%weekdayIt will be replaced with the weekday.
%dateIt will be replaced with the date.
%timeIt will be replaced with the time.
%rfc822_dateIt will be replaced with the RFC 822 date format. It is used if you want to set the DATE header for the email message.
%diskfree<>It will be replaced with the free disk space. For example, %diskfree<C> will show free disk space of C:\ drive. It can work only when the OnDiskSpaceLow event is triggered.
%wan_ipIt will be replaced with the WAN IP address. This variable must be used with the OnWanIPChange event.