Configuring Mail and Sending Emails →

Basic Notification and Alerting with the Mail Module

The mail module allows you to send emails from within Redwood Server. This module has basic alerting and notification features to alert operators about a process that has reached Error or about the publication of a new report, for example. You can have the mails forwarded to mobile phones via SMS, however, you need to use a third party service provider (additional fees may apply). The mail module allows you to easily send standard emails as well as customize the email before it is sent.

Two process definitions are shipped with the module:

note

The Mail Module requires the Module.Mail license key

note

The notification and alerting features of the Mail module require you to configure every chain definition that is to use these features. If you make extensive use of alerts and/or notifications, Redwood recommends the Active Monitoring module, as you can configure alerts and notifications centrally.

Configuring the Module

Before you can send an email, you need to configure the module to use your mail server and a default from: address. The module has a basic SMTP server detection mechanism which only requires the default From: email address to retrieve the address of the mail server. If the process was unable to detect your mail server, it will reach Error; in this case you will be asked for the From address as well as the mail server hostname or IP address.

note

The SMTP port is 25 by default. You can override this using the /configuration/jcs/mail/[<server>/]Port registry entry. The <server>/ part of the path is optional, if used, it must be set to the FQDN of the SMTP server.

The module has the following standard registry entries:

  • /configuration/jcs/mail/[<server>/]Server - FQDN of the SMTP server.
  • /configuration/jcs/mail/[<server>/]Port - Port to use, defaults to 25.
  • /configuration/jcs/mail/[<server>/]AuthenticationMethod - The authentication strategy used by your SMTP server.
  • /configuration/jcs/mail/[<server>/]From - The default From field for email.
  • /configuration/jcs/mail/[<server>/]Transport - The transport to use.
  • /configuration/jcs/mail/[<server>/]User - The user to use for the connection.
  • /configuration/jcs/mail/[<server>/]ConnectMethod - (internal) the overload to use for the connection.

Setting JavaMail SMTP Properties

You set properties such as mail.smtp.timeout, mail.smtp.connectiontimeout, and mail.smtp.port by creating a child key under the registry entry /configuration/jcs/mail/[<server>/]JavaMail. The name of the registry entry must match the name of the property, for example, /configuration/jcs/mail/[<server>/]JavaMail/mail.smtp.timeout. Special caution must be taken when you set other properties. Note that setting mail.smtp.host has no effect, as this setting is set in /configuration/jcs/mail/Server.

Alternatively, you set the port for the connection in the following locations; the first found is used:

  1. /configuration/jcs/mail/<server>/Port
  2. /configuration/jcs/mail/<server>/JavaMail/mail.smtp.port
  3. /configuration/jcs/mail/Port

STARTTLS and TLS

When a secure connection is established to an SMTPS server, the chain of trust for the public certificate presented by the secure server is verified by default.

The verification is performed by combining the presented server certificate with a chain of certificates that signed the server certificate, leading up to a Root Certificate Authority (Root CA). Trust of a certificate is established when the system trusts the Root CA. The Java SDK contains a Java KeyStore that contains a generally accepted list of trusted Root CAs, such as DigiCert, GoDaddy, Google and various country authorities. The Java system administrator can add extra certificates to this KeyStore. It is also possible to add Credentials of type X509_TrustedCertificate via the user interface. If your connections are to servers that are issued by one or more private Root CAs, you only need to create a Credential for each Root CA. If your connections are to servers that use self-signed certificates, you create a Credential for every self-signed certificate.

When TLS.VerifyServerCertificateTrust is set to the default and recommended value of Verify, the system will verify that certificates presented by SMTPS servers are trusted. On upgrades from earlier versions this value will be set to 'Warn', which will allow all certificates, but generate an operator message for every incorrect certificate. Check all operator messages and fix the hostnames or the certificates until no warnings are created. Once no operator messages are created the value can be set to Verify. It is possible to set this value to DontVerify to allow all certificates (not recommended).

Using STARTTLS

Using electronic mail services that support STARTTLS requires you to at least set the following registry entries (the port defaults to 587):

/configuration/jcs/mail/[<server>/]JavaMail/mail.smtp.starttls.required
/configuration/jcs/mail/[<server>/]JavaMail/mail.smtp.starttls.enabled

Both these must be set to true, the <server>/ part of the path is optional, if used, it must be set to the FQDN of the SMTP server.

If authentication is required, you set /configuration/jcs/mail/[<server>/]AuthenticationMethod to one of the following values depending on the configuration of the SMTP server:

  • <no value> - use the standard session constructor
  • sessionNull - pass an extra null to the session constructor
  • sessionAuth - pass the authenticator to the session constructor
  • transport - pass the authenticator to the session but only for the specified transport

Using TLS

Straight TLS is also supported although it is not RFC compliant. Default port is 465.

You are required to set the /configuration/jcs/mail/[<server>/]JavaMail/mail.smtps.ssl.enable registry entry to true to enable TLS on the connection.

The /configuration/jcs/mail/[<server>/]JavaMail/mail.smtps.ssl.trust registry entry might be required depending on the configuration of the SMTP server; it should be set to the trusted third-party, usually the FQDN of the SMTP server.

Example

Gmail Service

The following table lists the registry entries that are needed to connect to the Gmail service:

||Registry Key||Value |/configuration/jcs/mail/smtp.gmail.com/JavaMail/mail.smtp.starttls.required|true |/configuration/jcs/mail/smtp.gmail.com/JavaMail/mail.smtp.starttls.enabled|true |/configuration/jcs/mail/smtp.gmail.com/AuthenticationMethod|sessionAuth |/configuration/jcs/mail/smtp.gmail.com/Server|smtp.gmail.com

In addition to the registry entries, you must create an application password in the account profile of the account used to connect and create a credential with the following properties:

FieldValue
Protocolsmtp
Real UserThe username to use for the connection; without the @gmail.com part.
PasswordThe application password generated in the Gmail account profile.
Endpointsmtp.gmail.com
Virtual Userdefault

Office 365 Service

Office 365 has a direct send service which uses encryption without authentication that is used to send emails, limited to recipients in your organisation.

Locate the FQDN of the mail server for your domain (example.com in this example) as follows using nslookup on the command line:

nslookup
> set type=MX
> example.com
Server:         127.0.0.53
Address:        127.0.0.53#53

Non-authoritative answer:
example.com     mail exchanger = 10 example-com.mail.protection.outlook.com

In this case, the SMTP server to use is example-com.mail.protection.outlook.com.

Since this is the only SMTP server used at Example Inc, we specify the registry entries directly under /configuration/jcs/mail:

Registry KeyValue
/configuration/jcs/mail/JavaMail/mail.smtp.starttls.requiredtrue
/configuration/jcs/mail/JavaMail/mail.smtp.starttls.enabledtrue
/configuration/jcs/mail/JavaMail/mail.smtp.port25
/configuration/jcs/mail/Serverexample-com.mail.protection.outlook.com

Attaching Files

The mail module allows you to attach output files to emails. The feature is used in chains; you create a step with chain process running System_Mail_Send and use the parameters Relative Process and File to specify which file to attach to the email. The Relative Process parameter takes a value in the form of <step_name>, <job_number>, or [Job] <job_ID> and the parameter File takes the short name of the output file.

Example

Using default step names and chain process orders

Relative Chain Process - Step 1, Job 1
File - stderr.log

Using custom step names

Relative Chain Process - Dataload, Job 2
File - datarun.txt

Using the ID of the chain process or process

Relative Chain Process - 1234
File - datarun.txt

Using the ID of the chain process or process

Relative chain process - Job 1234
File - datarun.txt

Advanced Email Customisation

The mail module ships with the Mail Definition Type which allows you to customize the email before it is sent. See the Customising Email section of the documentation.

See Also

Configuring Mail and Sending Emails →