Email SMTP

Follow

Simple Mail Transfer Protocol (SMTP) is an Internet standard for email transmission. You must configure SMTP to establish communication between the ILLiad client and your email service.

Emails in ILLiad are sent by the ILLiad System Manager. The System Manager uses the following SMTP keys for sending Email. The keys are found in the System | EMail section of the ILLiad Customization Manager. If you make changes to these keys in the customization manager it is recommended that you stop and restart the system manager to assure that the new settings are applied. Before using email in ILLiad, you will need to set the following keys.

EMailSMTPServer

SMTP server used for all system-generated e-mail. Note all e-mail is sent from the ILLiad web server using the System Manager.

EMailSMTPPort

Port used for sending emails from System Manager service on the server. Defaults to port 25.

EMailSecure Determines if SMTP server requires SSL.
SMTPUserID

Username used for SMTP authentication when sending system e-mails.

SMTPPassword

Password used for SMTP authentication when sending emails.

EMailFromAddress The from address used for all system-generated e-mail.
EMailFromName Name used for all system-generated e-mail.
EMailNoAccountAddress Email address for the system tto use when an outgoing email doesn’t have a TO: email address

To use Gmail with ILLiad, the EMailSecure key must be set to Yes.

SMTP.config Customization

The SMTP.config file (sample shown below) should be used only in specific situations where your SMTP server requires additional settings that cannot be set using the standard customization keys.

The SMTP.config file must be in the same location as the System Manager in order to function properly. When placed with the System Manager, the SMTP.config will complement the settings from the Customization Manager. Note that each setting is optional. Options that are not required by your SMTP server can be removed from the config file.

<?xml version="1.0"?>
<MailSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<AllowExtensions>true</AllowExtensions>
<FirewallHost>127.0.0.1</FirewallHost>
<FirewallPassword>firewall_password</FirewallPassword>
<FirewallPort>0</FirewallPort>
<FirewallType>fwNone</FirewallType>
<OtherHeaders></OtherHeaders>
<SslAcceptServerCert></SslAcceptServerCert>
<SslCertEncoded></SslCertEncoded>
<SslCertStore>MY</SslCertStore>
<SslCertStorePassword></SslCertStorePassword>
<SslCertStoreType>sstMachine</SslCertStoreType>
<SslCertSubject></SslCertSubject>
<SslStartMode>sslAutomatic</SslStartMode>
<Timeout>120</Timeout>
<FullyQualifiedDomainName>mydomain.com</FullyQualifiedDomainName>
</MailSettings>

Use this example if you need only to configure your fully qualified domain name:

<?xml version="1.0"?>
<MailSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<FullyQualifiedDomainName>mydomain.com</FullyQualifiedDomainName>
</MailSettings>

SMTP.config Sample Explanations

AllowExtensions

If AllowExtensions is true, the component will first send the EHLO greeting to the server; if that fails, the standard HELO command will be sent. True by default but may be disabled if it is known in advance that the MailServer doesn't support SMTP extensions.

FirewallHost

Name or IP address of firewall. If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.

FirewallPassword

The password property if authentication is to be used when connecting through the firewall. If FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

FirewallPort

The TCP port for the FirewallHost. See the description of the FirewallHost property for details. Note that the FirewallPort is set automatically when FirewallType is set to a valid value. See the description of the FirewallType property for details.

FirewallUser

The user name property if authentication is to be used when connecting through a firewall. If FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

FirewallType

Determines the type of firewall to connect through. The options are listed below.

  • fwNone (0) No firewall (default setting).
  • fwTunnel (1) Connect through a tunneling proxy. FirewallPort is set to 80.
  • fwSOCKS4 (2) Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.
  • fwSOCKS5 (3) Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.

The OtherHeaders Property

The OtherHeaders Property is an RFC 822 compliant string consisting of extra headers to be appended to the message headers created from other properties like SendTo, Subject, etc. The headers must of the format "header: value" as specified in RFC 822. Header lines should be separated by CRLF ("\r\ n"). The OtherHeaders property is useful for extending the functionality of the component. A good example is delivery of MIME encoded messages. SPECIAL CASE: If OtherHeaders starts with an empty line (CRLF), then the value of OtherHeaders is used instead of the normally computed message headers.

Use this property with caution. If OtherHeaders contains invalid headers, message delivery might not be successful.

SSLAcceptServerCert

Instructs the component to unconditionally accept the server certificate that matches the supplied certificate. If it finds any issues with the certificate presented by the server, the component will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property will create a security breach. Use it at your own risk.

SslCertEncoded

The SSL certificate (PEM/base64 encoded). This property is used to assign a specific certificate for SSL client authentication (SSL server authentication in the case of the IPDaemonS component). The SSLCertStore and SSLCertSubject properties may also be used to specify a certificate.

When SSLCertEncoded is set, a search is initiated in the current SSLCertStore for the private key of the certificate. If the key is found, SSLCertSubject is updated to reflect the full subject of the selected certificate, otherwise SSLCertSubject is set to empty string.

SslCertStore

The name of the certificate store for the client certificate. The SSLCertStoreType property specifies the type of the certificate store specified by SSLCertStore. If the store is password protected, specify the password in SSLCertStorePassword. SSLCertStore is used in conjunction with the SSLCertSubject property in order to specify client certificates. If SSLCertStore has a value, and SSLCertSubject or SSLCertEncoded is set, a search for a certificate is initiated. Please refer to the SSLCertSubject property for details. Designations of certificate stores are platform-dependent.

The following are designations of the most common User and Machine certificate stores in Windows:

  • MY A certificate store holding personal certificates with their associated private keys.
  • CA Certifying authority certificates.
  • ROOT Root certificates.
  • SPC Software publisher certificates. When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS12 certificate store).  If the provider is OpenSSL, the certificate store is a file containing a certificate and a private key. This property must be set to the name of the file.

SSLCertStorePassword

The password for the certificate store (if any). If the certificate store is of a type that requires a password, the value of this property is used to open the certificate store.

SSLCertStoreType

The type of certificate store for the client certificate. Options are listed below:

  • 0 (sstUser - default) For Windows, this specifies that the certificate store is a certificate store owned by the current user. For Java, this specifies that the certificate store is the name of a JKS (Java Key Store) file. If the provider is OpenSSL, this specifies that the certificate store is a file that contains PEM encoded certificate and private key.
  • 1 (sstMachine) The certificate store is a machine store (not available in Java and when provider is OpenSSL).
  • 2 (sstPFXFile) The certificate store is the name of a PFX (PKCS12) file containing certificates. If the provider is OpenSSL, the file may contain only one certificate and private key.
  • 3 (sstPFXBlob) The certificate store is a string (binary or base64 encoded) representing a certificate store in PFX (PKCS12) format. This setting is currently not supported when the provider is OpenSSL.
  • 4 (sstPEMKey) The certificate store is a string or filename that contains a PEM encoded certificate and private key. This store type is currently not supported in Java.

SSLCertSubject

The subject of the certificate used for client authentication. When this property is set, a search is performed in the current certificate store certificate with matching subject. If an exact match is not found, the store is searched for subjects containing the value of the property. When setting the property to a partial subject, CN= should be omitted. If a match is not found, the property is set to an empty string, and no certificate is selected. The special value "*" picks a random certificate in the certificate store. If a matching certificate is found, the SSLCertSubject property is set to the full subject of the matching certificate.

SSLStartMode

Determines how the component starts the SSL negotiation.

Options for SSLStartMode:

  • 0 (sslAutomatic - default) If the remote port is set to the standard plaintext port of the protocol (where applicable), the component will behave the same as if SSLStartMode is set to sslExplicit. In all other cases, SSL negotiation will be implicit (sslImplicit).
  • 1 (sslImplicit) The SSL negotiation will start immediately after the connection is established.
  • 2 (sslExplicit) The component will first connect in plaintext, and then explicitly start SSL negotiation through a protocol command such as STARTTLS.
  • 3 (sslNone) No SSL negotiation, no SSL security. All communication will be in plaintext mode.

Custom Key Needed for SSLStartMode:

SSLStartMode requires that a custom key be added to the Customization Manager. Add the following values to the key, EmailSecure, when creating it in the Customization table:

CustKey: EmailSecure
Value: Yes
NVTGC: ILL
Description: SMTP.config control
AdminCat: System
AdminKey: EMail
Admin Type: YesNo

Timeout

A timeout for the SMTP connection in seconds. If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or until an error condition is encountered.

If Timeout is set to a positive value, the component will wait for the operation to complete before timing out. Please note that by default, all timeouts are inactivity timeouts, i.e., the timeout period is extended by Timeout seconds when data is successfully sent or received. The default value for the Timeout is 60 (seconds).

FullyQualifiedDomainName

A domain name that is used when sending the initial HELLO message to an SMTP server.

Shared Server SMTP Configuration

For shared server systems, configuration files for the System Manager are used individually by each site to override the settings in the Configuration Manager. Each site has the choice to use the existing Customization Manager settings or to create individual configuration files. To use an individual configuration file it should be named using the NVTGC site code. (i.e., instead of SMTP.config it would be named NVTGC.config) and located in the same folder as the System Manager. When an individual configuration file is not found for a specific NVTGC, if the SMTP.config file exists, those settings will be used.

Questions?

If this article didn’t resolve your issue, please take a moment and answer a few questions to help improve our documentation:

Feedback