Sending emails

To send emails, define an email message destination and configure the emailMessageTransport plugin.

Defining the email message destination

To send email messages from PolicyCenter, define an email message destination to process them.

The base configuration defines an example email message destination. To view the destination in Studio, navigate to the following location and open the messaging-config.xml file.

This file is located at configuration > config > Messaging.

The example destination is assigned a unique ID value of 65, which references an external system defined in the Studio Messaging editor. The ID for the email message destination cannot be changed, but other parameters associated with the destination can be modified.

Configuring the email message transport plugin

To send email messages from PolicyCenter, configure the email message transport implemented in the emailMessageTransport plugin.

This plugin is located at configuration > config > Plugins > registry > emailMessageTransport.

In the base configuration of PolicyCenter, the email transport that is registered is the sample class EmailMessageTransport. This sample class is for demonstration purposes only and cannot be used in a production environment. Instead, you can use the JavaxEmailMessageTransport class in the gw.plugin.email.impl package. This plugin class implements the gw.plugin.messaging.MessageTransport interface, which is used to send an email. Alternatively, create your own email message transport class that implements the same interface.

JavaxEmailMessageTransport class

The JavaxEmailMessageTransport class can be used as the basis for an email messaging transport in a production environment. The class is located in the gw.plugin.email.impl package.

The JavaxEmailMessageTransport class supports the following parameters that can be specified in the registry.
CredentialsPlugin.Key

Optional. String key value stored in the Credentials plugin. If this parameter is specified and the Credentials plugin is enabled, the user name and password values to use in an SSL authenticated login are retrieved from the plugin. The plugin's properties can be encrypted, which enables secure user and password strings.

Default: EmailMessageTransport

Debug

Optional. Boolean value to enable debugging output from the email host.

Default: false

defaultSenderAddress

Default From email address to use for outbound email. For example, jdoe@mymail.com.

The defaultSenderAddress and defaultSenderName parameter values are used if both the Sender and Sender.EmailAddress properties are not specified in the Email object.

defaultSenderName

Default sender's name to use for outbound email. For example, John Doe.

mail.*

Optional. Specifies various mail.* properties.

Properties recognized in the base configuration are listed below. Additional mail.* properties can be recognized by writing configuration code.

  • mail.transport.protocol: Specifies the desired protocol. Default: "smtp"
  • mail.smtp.host: Specifies the SMTP email application that sends emails.
  • mail.smtp.port: Specifies the SMTP port number.

If any mail.* parameters are specified, the values specified in the smtpHost and smtpPort parameters are ignored.

If no mail.* parameters are specified and a password is specified, either in the Password parameter or retrieved from the Credentials plugin, the following properties and values are defined.

  • mail.smtp.ssl.enable: Set to true.
  • mail.smtp.auth: Set to true.
To support the TLS security standard, set the following mail.* parameters:
mail.smtp.auth
Set to true.
mail.smtp.starttls.enable
Set to true.
mail.smtp.host
The SMTP email application that sends emails
mail.smtp.port
The SMTP port number

Also set the Username, Password, defaultSenderName, and defaultSenderAddress to appropriate values for your TLS requirements.

Password

Optional. Login password.

The Password parameter is plain text and not secure. It is recommended to specify user name and password values in encrypted properties in the Credentials plugin. See the CredentialsPlugin.Key parameter.

Default: Not specified

smtpHost

Name of the SMTP email application that sends emails.

If any mail.* parameters are specified, the smtpHost parameter is ignored.

smtpPort

SMTP email port.

If any mail.* parameters are specified, the smtpPort parameter is ignored.

Default: 25 for non-authenticated logins; 465 for authenticated logins. See the Password parameter.

useDefaultAsSender
Optional. Boolean value indicating whether to use the defaultSenderName and defaultSenderAddress parameters to identify the email sender. If true, the parameter values are used even if the email explicitly specifies a sender and address.

Default: false

useMessageCreatorAsUser

Optional. Boolean value to specify on whose behalf to retrieve a document attached to the email. Possible personas are either the user who generated the email (true) or the system user (false).

Default: false

Username

Optional. Login user name.

The Username parameter is plain text and not secure. It is recommended to specify user name and password values in encrypted properties in the Credentials plugin. See the CredentialsPlugin.Key parameter.

Default: Not specified

In the base configuration, starting the plugin initializes the environment by performing the following tasks:
  • Reads the default values of the plugin parameters.
  • Sets the SMTP host name and port.
  • If a password is configured in the emailMessageTransport plugin, enables an SSL authenticated login.
The class implements the following important method:
send(message : entity.Message, transformedPayload : String)
The method accepts the following arguments.
message
Message entity instance to send
transformedPayload
The transformed payload of the message

The method does not return a value.

In the base configuration, the send method performs the following operations.
  • If either the email.Sender or email.EmailAddress properties are not set, uses the defaultSenderName and defaultSenderAddress values configured in the emailMessageTransport plugin.
  • Retrieves a Session object. If a Session does not already exist, one is created. If an authenticated login is performed, access to the Session object is restricted to the authenticated user. Also, if the emailMessageTransport plugin's debug parameter is true, debugging on the Session is enabled.
  • Creates and initializes a new HtmlEmail object.
  • If the SMTP host name is not an empty string, the email is sent.

If an error occurs that causes a MessagingException exception, the method catches that exception. If the exception is caused by an invalid email address, the invalid address is removed from the recipient list and an attempt is made to resend the email to any remaining recipients. The removal event is written to the log, but no further action is taken to recover from an invalid address. To modify this behavior, such as to create an activity or forward the removed email to a postmaster for additional processing, edit the handleMessageException method in the JavaxEmailMessageTransport class.

Other exceptions set the error description on the message and report the error.