DBMail User Manual
Overview
DBMail is a Windows .NET program that generates email messages from xeml files dropped in an input folder and sends them out to specified recipients.
DBMail checks its input folder at regular intervals (5 seconds [internal]) to see if there are any xeml files to be processed.
DBMail has no user interface. It's started by double clicking and stopped by dropping a file named "stop.txt" in the folder that it runs in. In most cases you'll want to run it as a Windows scheduled task.
All activity is logged in emailLogs folder.
DBMail supports:
- html formatted messages accompanied with images and css files
- attachment compression (zip format)
- CSV to Excel conversion of attachments
- HTML to PDF conversion of attachments
Note: [internal] refers to a non-configurable parameter.
Installation
There is no installation program for DBMail. The operating system must have .NET Framework 4.5 installed.
The program is located in your DesignBais web component /admin/dbMail folder. You just copy that folder to another location and run it there.
Configuration
DBMail is configured using the xml file dbmail.config located in its start folder (i.e. /admin/dbMail)
The structure of the dbmail.config file is as follows:
Allowed values for these parameters and a brief description are given below:
| Parameter | Allowed Values | Description |
| adminEmail | Email address | System generated notifications are sent to this address. This can be your email address. |
| smtpHost | IP address | Emails are sent via this email server |
| smtpPort | a TCP/IP port number | TCP/IP port of the email server. Leave blank initially (defaults to 25) |
| smtpLogin | A user login name | User login name in connecting to the mail server (if needed by your mail server). Leave blank initially. |
| smtpPassword | A password | password for smtpLogin (if needed by your mail server). Leave blank initially. |
| smtpEnableSsl | true or false | specifies whether SSL is used to access the specified SMTP mail server. Default is false. |
| inputFolder | Input folder path | The full path of the input folder where xeml files are dropped |
| archiveFolder | Archive folder path | The full path of the archive folder where xeml files and attachments are archived |
| enableABCPDF | true or false | This parameter is optional. If provided and set to true then it enables the ABCPDF mode for PDF document generation. If set to false or if the node is missing then HIQPDF mode is used. We recommend that this node be excluded from the config unless there is a particular reason to enable the ABCPDF mode. |
| HIQImageCompressionLevel | 0-100 | This parameter is optional. If provided, images are compressed according to this value during an HTML to PDF conversion. Lower values result in lower quality images but smaller size attachments. No compression is applied if this parameter is not provided or set to 0. |
| login | A Windows user login name | This is required for PDF conversions where the HTML input file has image URLs pointing to a DBNET with Basic authentication. |
| pass | Password for the above login | This is required for PDF conversions where the HTML input file has image URLs pointing to a DBNET with Basic authentication. |
Configuration parameters can be changed while DBMail is running. There is no need to stop and restart after a configuration change.
Passwords are automatically encrypted by dbMail in dbmail.config
Set up and start up
- Enter the required parameters in file dbmail.config
- Double click to start DBMail.exe
That's all. Please refer to your DesignBais manual to see what you need to do in DesignBais to send emails via dbMail.
You can set a Windows scheduled task to start DBMail everytime the host is restarted.
Check the logs in emailLogs folder for any errors after starting dbMail.
Check the Windows task manager to see if DBMail.exe process is running.
Note that DBMail allows only one instance running on a computer.
Stopping
To stop dbMail, drop a file named "stop.txt" in the same folder. Remember to delete stop.txt (if it's there) before starting dbMail.
Operation
DBMail polls the input folder at 5 seconds [internal] intervals and picks up the xeml files dropped in that folder. It processes an xeml file 15 seconds [internal] after it's created. In most cases this is enough time for its attachments to be ready. If the attachments are still not ready at the end of that period then DBMail retries the process in 2 minutes [internal] and again in 3 hours [internal].
xeml files older than 6 hours are not processed. Those files remain in the input folder.
xeml file and its attachments are moved from the input folder to the process folder where they are processed and sent out as email messages.
xeml files and their attachments are filed in the archive folder.
Folder Structure
When started for the first time, DBmail creates three subfolders; process, emailLogs and zips. These folders are used internally by dbMail.
In addition, DBMail uses the input and archive folders specified in db.config.
Errors
An email notification is sent to the system administrator for errors. Email notifications are put on hold for one minute [internal] after a notification is sent.
Fatal Errors
DBMail logs the error and stops when one of these conditions are encountered:
- Malformed xml or invalid parameters in db.config file
- Permission errors in creating the process, emailLogs and zips folders
- Input or archive folders missing
Critical Errors
DBMail logs the error, pause for one minute [internal] when one of these conditions are encountered:
- Permission problems on the process folder (e.g. cannot move a file)
- Errors in reading files from the input folder (e.g. insufficient folder permissions)
- Too many quaranteened xeml files due to to many critical errors
DBMail and resumes operation after the one minute [internal] wait.
Non-critical errors
- Errors in copying an xeml file from the input folder to the process folder
- Missing or incomplete attachments or errors in moving attachments from input folder to process folder
DBMail retries sending these messages in two minutes [internal] and again in three hours [internal]. If the error conditions is still there (e.g. an attachment is missing) the xeml file is archived.
Other Errors
- Errors in parsing the xeml file
DBMail archives the xeml file. If the provided attachment and resource file names are same without the extension, then the resource file remain but the attachment file is deleted. Otherwise, the attachments of the message remain in the input folder.
Any SMTP send errors are logged, the xeml file and its attachments are archived.
XEML File
An XEML file specifies an email message together with its attachments and file conversions. XEML files are generated by DesignBais.
Attachments
General
Any file type can be attached to a message. All the attachments are archived in the archive folder location but not the resource files.
Attachments are moved from their given location to an archive folder. Do not use attachment paths that are significant elsewhere in your deployment. Attachment paths pointing to a web site's files may not be a good idea.
DBMail can convert HTML files to PDF format. Conversion parameters are supplied by DesignBais in the xeml file.
Excel
DBMail can convert CSV files to Excel format. Conversion parameters are supplied by DesignBais in the xeml file.
Zip
DBMail can compress (zip) any attachment indivdually. Compression parameters are supplied by DesignBais in the xeml file.
Housekeeping
You need to monitor your input and archive files to make sure that there are not too many files in them as that would impact the performance of DBMail.