Registry System Email (sys-email)


This registry entry identifies the address of your firm's e-mail server, and may be used to specify test settings such as cc’ing and redirects. It is required for implementation of Escalation Manager and Report Anywhere.

Testing Your Registry Entries
The system does not verify the validity of registry entries. Be sure to test your registry entries after completing them to verify that they are functioning correctly.

Setting Values are Uppercase-Lowercase Sensitive:
The Setting Value is case-sensitive: be sure that you enter the value exactly as specified in the documentation. If the documentation specifies a value of true, do NOT enter True or TRUE


SAMPro’s SMTP mechanism includes an Authentication mechanism for mail servers providing LOGIN authentication.

Enhanced MS Outlook support is also offered, and may be implemented with this registry entry. If this is implemented, all your SAMPro users must be running MS Outlook.

Note: Managing Emailed PDF’s
When e-mailing .PDF reports generated from SAM Pro, a copy of the report will be retained in the xmlToPdf_Sent folder located in the directory containing your SAM Pro executable (v.exe). You may wish to periodically clear or archive these files.

Important Fields:


The Id of the Registry Entry must conform to one of the following formats:

sys-email-branchid-userid (or sys-email--userid if branches are not implemented)

The first format enables you to specify e-mail parameters by branch id and/or user. A branch must be specified if a user belongs to a branch. If branches are not implement, two dashes (not separated by a space) must precede the user id.

The second format enables you to the e-mail server by security id.

The third format would apply to all users unless another registry entry was created for their security or branch/user id.

SMTP Server Configuration

Setting Key: serversmtp  Setting Value: address

where address is replaced by the address of your e-mail (smtp) server. Typically, this will be an internal IP address.

Setting Key: usernamesmtp  Setting Value: name
Setting Key: passwordsmtp  Setting Value: password

SAM Pro’s SMTP mechanism includes an Authentication mechanism for mail servers providing LOGIN authentication (Microsoft Exchange Server and MDaemon, for example).

Authentication and Sending PDF’s as E-mail:
If these SMTP options are specified, they must be configured properly for SAMPro to email PDF’s.

Alternate Ports

This release (used in conjunction with the xmlToPdf.jar file dated 11/8/2011) supports alternate email ports for emails with .pdf attachments (controlled by the xmlToPdf.jar file) as well as emails without pdf attachments (managed by SAM Pro). The following two additional options in sys-email are required to support this functionality:

Setting Key: portsmtp Setting Value:port# (controls emails without pdf’s)
Setting Key: smtpPort Setting Value:port# (controls emails with pdf’s)

Note that if the above options are omitted, port 25 will be the default.

Secure Servers

SAMPro supports secure (SSL) email servers. To implement, the following additional registries are required:

Setting Key: useSSL  Setting Value: true

Setting Key: MailerMethod Setting Value: Java (required to send non-pdf emails securely)

Example: Use Port 465, Secure Server

Setting Key: portsmtp Setting Value: 465

Setting Key: smtpPort Setting Value:465

Setting Key: useSSL  Setting Value: true

Setting Key: MailerMethod Setting Value: Java

Note: the applicable PasswordSMTP, UserNameSMTP, and serversmtp options must also be set.

Regarding SMTP Email Security

The built-in SAMPro emailer does not support Email Security. In order to utilize, you must use the Java Emailer (XMLtoPDF), enabled via MailerMethod=Java

There are 2 types of security, SSL and TLS. SSL is older/obsolete and has been replaced by TLS. It is best to use TLS when available.

By default, XMLtoPDF will attempt to use TLS initially, and will fall back to Plain (not secure) if not supported by the SMTP server and/or TCP/IP port.

If it is needed to utilize the older/obsolete SSL security method, the option UseSSL=true can be used.

Although TCP/IP ports for SMTP servers are not directly related to SSL/TLS, these typical SMTP port configurations will help for set up. Keep in mind your SMTP email provider may offer other configurations:

25 – Commonly Plain (unsecure), but can sometimes support SSL & TLS

465 – Commonly, but not limited to SSL

587 – Commonly, but not limited to TLS

Today’s standard is to use port 587 with TLS.

Example sys-email registries to use this:

Setting Key: MailerMethod   Setting Value: Java

Setting Key: PortSMTP  Setting Value: 587

Setting Key: SMTPport  Setting Value: 587

Default Email Sender Registry

If a From address cannot be determined, an Email cannot be sent. Especially in the case of emailing as a PDF, the XML will contain a blank emailFrom tag and the email will fail silently in the xmlToPdf_Failed folder. This release provides several enhancements to prevent Emails from attempting to send without a from address.

Setting Key: DefaultEmailSender  Setting Value: validemailaddress

If a 'From' email address cannot be determined from the User's Contact Record (for reports) or the Notification Category (for Scheduled Events), this email address will be used instead.


1. When clicking the email button on a report (if UseOutlook=false), the Sender field is now required on the SAMPro Email screen. If the Email address is not completed in the User's Contact record, the Sender field will default from the sys-mail registry's DefaultEmailSender option.

2. The Email From field in the Schedule Report screen is now required. If the Email address is not completed in the User's Contact record, the Email From field will default from the sys-mail registry's DefaultEmailSender option.

Scheduled Events: If the email-from is not set by the Scheduled Event Manager, the default email sender from  the sys-email registry will be used.

Enhanced MS Outlook Support

Setting Key: UseOutlook  Setting Value: true

If this entry is present, processing of the outgoing e-mail is passed on to Outlook with the to-address, subject, message and attachments defaulted when applicable. Older versions of Outlook may not be supported.

In Versions 9.0-9.1, UserOutlook is supported with Outlook 365/Outlook 2016. Other Outlook versions may or may not work. The appropriate XmlToPdf.jar file must also be in use. As of January 2019, the following versions (renamed as XmlToPdf.jar) are recommended:

XmlToPdf[2019-01-16] Java8-11].jar file which supports Java 8-11 but not Java 7

XmlToPdf[2017-12-27].jar to XmlToPdf.jar (Installations with Java 7 and Java 8 users)

NOTE:  this is intended to be used with supports versions of Outlook.  Outlook Express doesn't support the command-line attachments.  Other email clients may or may not work.

If UseOutlook is enabled, the CopyAll and AutoPopulateCCAddress should NOT be enabled.

Start AP Payment Approved: and Quotemaster Vendor Approval
If Outlook is enabled, the regular SAM Pro email form will appear when the Dispute / Vendor approval button is clicked.

When Outlook is implemented, the following will occur when you click the E-mail button on a SAMPro report:

The Outlook e-mail form (not SAMPro’s) will open.

The report that you generated will be attached in its default PDF format (or as set in the registry).

The From: line will be completed with the e-mail address from your Outlook profile.

The To: line will be completed with the default values if this is supported for the report.

The Subject line will be defaulted according to the report.

The report will be attached.

When the Outlook form is up, you may add additional recipients from your Outlook address box, enter a text message, and include additional attachments. When you click Send, a copy of the e-mail will remain in your Sent box if you have implemented this feature in Outlook, as well as in the xmlToPdf_Sent folder in directory containing your SAM Pro executable.

Important Note on dbreportfiles Registry Entry and Subfolders

If UseOutlook is enabled, the directory specified by the dbreportfiles registry entry is expected to contain subfolders xmlToPdf_Sent, xmlToPdf_Failed and xmlToPdf_Retry.  If they don't exist in this directory, they must currently be created manually. See Registry Entry for Report Anywhere File Path for details.

Java Mailer

Setting Key: MailerMethod Setting Value: Java

This registry option results in Java code sending all e-mail that initiates from within the system, not SAMPro. Note that Java is used when sending e-mail with PDF attachments. This option may be utilized if difficulties with e-mail are being experienced. Do not implement this registry entry until you have discussed it with your support representative.

Report Attachment Defaults

Setting Key: EmailReportAsType Setting Value: pdf or text     (pick one option)

This entry applies to pushing the Email button on the side toolbar when displaying a report on screen. It sets the default attachment type of the report. The attachment type defaults to pdf if this option is not specified. The options of html and csv are deprecated for this global setting.

Comparison Against Database

This option enables you to prevent copies of your database (which may be running for training or testing purposes) from interfering with "live" operations. Implementing this option would help avoid inadvertently emailing and pages or overwriting your real invoices while running a copy of your data to train new personnel.

You may specify either or both:

Setting Key: eng  Setting Value: enginename

where enginename is replaced by the engine name that your live data runs under.

Setting Key: dbn  Setting Value: databasename

where databasename is replaced by the name of your live database. Do not include the .db extension in the databasename (mydata rather than mydata.db).

Copy All

Setting Key: CopyAll  Setting Value: emailaddress

This option enables you to send an extra copy of all e-mail generated out of SAM Pro to a specific address or addresses (separated by commas) where emailaddress is replaced by the address you wish to copy all emails to. This option would typically be implemented for testing purposes for a limited time frame.

Tip - Service Invoice Billing
Creating a user-specific sys-email registry allows billers to send themselves a copy of their auto-mailed Service Invoices. This registry would use the format sys-email-branchid-userid (or sys-email--userid if branches are not implemented).

CC Default for Manual Emails

Setting Key: AutoPopulateCCAddress Setting Value: true

If this registry option is implemented, the system will use the currently logged in user's email address (from the contact reference in the user record) to Auto-populate the CC email address when launching the SAMPro Email formatting form. This would apply anywhere that the USER initiates the open the MANUAL email form...i.e. dispatch board, previewed report, etc.

Note: Some Manual Email Forms (like on previewed reports) do not have a CC line. In these cases, the CC address will be added to the Send to address when the email is sent.

Redirect E-mail

Setting Key: RedirectAll Setting Value: emailaddress

This option enables you to redirect all e-mail generated out of SAM Pro to a specific address or addresses (separated by commas). This option would typically be implemented to avoid sending out spurious e-mails when you are running a test system.

Note - Problem Analysis if E-mails are Not Sending:

Click for troubleshooting details.

Log SMTP Conversations

A registry entry may be used to turn on the logging of SMTP ‘conversions’ to a log file. To turn on logging for support purposes, add the following entry:

Setting Key: smtplogpath Setting Value: C:\someDirectory\someFileName.log

Optional POP3 Server Configuration

Setting Key: pop3server Setting Value: address

where address is replaced by the address of your pop3 server (to retrieve e-mail). Typically, this will be an internal IP address.

Setting Key: pop3user Setting Value: pop3username

where pop3username is replaced by the user's pop3 user id (for retrieving e-mail).

Setting Key: pop3pw Setting Value: pop3password

where pop3password is replaced by the user's password on the pop3 server (for retrieving e-mail).

Setting Key: pop3timeout Setting Value: timems

where timems is replaced by the time (in milliseconds) between when a request is sent and an error message is returned if timeout or other problem occurs.

Setting Key: pop3secondswait Setting Value: checkagain

where checkagain is replaced by the time (in seconds) that elapses before the inbox is checked again.

Note: Alarm Server Entries

If you will be running Alarm Server on your system (to receive alarms into the SAM Pro system), you must include the following sys-email registry entry. Note that you must have a mailbox named dispatcher with the password dispatcher set up on your pop3 server to receive alarms: this is the mailbox that SAM Pro will check. Note that the terms registry entry must also be completed.

Id: sys-email

Setting Key: pop3server  Setting Value: address
Setting Key: pop3user  Setting Value: dispatcher
Setting Key: pop3pw  Setting Value: dispatcher
Setting Key: pop3secondswait  Setting Value: 60
Setting Key: pop3timeout  Setting Value: 5000