SMTP Bridge microservice allows to connect to a remote email/news server and send emails/news articles.

SMTP is capable of handling:

Simple text e-mails/news articles
HTML e-mails/news articles
E-mails/news articles with attachments
Sign, encrypt mail and MDN

SMTP Bridge uses SMTP protocol for transmission of emails, NNTP protocol for transmission of news articles and AS1 protocol for signing, encrypting mail and MDN request. It uses the SMTP implementation from the JavaMail API and for NNTP, GNU a service provider for NNTP protocol to JavaMail API.

Icon

While sending attachments with the mail, if readFromFile attribute is enabled, then the content of the tag is treated as the filename and if it is disabled, then the content of the tag is treated as the content of the attachment with a dummy filename.

Configuration and Testing

Managed Connection Factory Panel

The properties that can be configured in the Managed Connection Factory panel of CPS are explained the sections below.

Figure 1: Managed Connection Factory panel in CPS

SMTP Server

Protocol

Specifies the protocol used to retrieve emails.

SMTP– Simple Mail Transfer Protocol is used to send emails.
NNTP– Network News Transfer Protocol is used to transfer news from one network to another.

Connection Configuration

Click the ellipses button to configure the properties.

Figure 2: Connection Configuration properties

MailServer IP/Name

The IP address or name of the SMTP mail server/ NNTP news server.

MailServer Port

The port on which the SMTP server is running on the host specified by the property MailServer IP/Name. Default port for NNTP is 119 and SMTP is 25

Use DefaultSession

The component uses a session (javax.mail.Session) to represent a mail session. A session collects together properties and defaults used by the mail APIs.

If this option is

enabled, the default session object (javax.mail.Session) is used to connect to the mail server. If a default is not setup, a new Session object is created and installed as default.
disabled, the the default session object is not used and a new session object is created for every connection attempt.

Additional Properties

Additional properties which can be used for creating connection can be specified here. For instance, to enable debug in Javamail, set a property 'mail.debug' to 'true'.

Example:

Icon

To send mails from gmail,

Provide the following property values:
1. MailServer IP/Name: smtp.gmail.com
2. MailServer Port: 465
Generate app password from https://accounts.google.com/IssuedAuthSubTokens?hide_authsub=1 for 'Mail'
Choose the desired device in App passwords section at Google Account > Security > Signing in to Google.
Use the generated password in the Authentication Configuration section.
Apart from the above, provide the following additional properties:
1. mail.smtp.starttls.enable=true
2. mail.smtp.auth=true
3. mail.smtp.ssl.enable=true
4. mail.smtp.ssl.protocols=TLSv1.2

Reference:

Icon

For the properties which are supported by

SMTP protocol: Properties section at https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html
NNTP protocol: http://www.gnu.org/s/classpathx/javamail/javadoc/gnu/mail/providers/nntp/package-summary.html

Authentication Details

Authentication Configuration

Authentication required

Specifies whether the connection has to be authenticated by the SMTP/NNTP server. The properties Login Name and Password for authentication are relevant only if Authentication is required. In case of NNTP, new server authenticates users against their preset account ids and passwords. You needs to provide authentication information in order to post news articles to the news server.

Login Name

The Login Name with which the connection to the SMTP/NNTP server is made. The login name specified must be valid with respect to the server whose URL is specified by the MailServer/NewsServer IP/Name property.

Password for authentication

Password for the user as specified by the Login Name property.

TimeOut Settings

Connection Timeout for mail server

Socket connection timeout value in milliseconds. This is the duration (in milliseconds) for which the component waits while trying to establish connection with the server. If the component fails to get a valid connection in the specified connection timeout interval, then the retry behavior depends on the configuration specified in Error Configuration Panel. Default value -1 indicates infinite timeout.

Timeout for sending MIME message

Socket I/O timeout value in milliseconds while sending MIME message. If sending a MIME message requires more time, the current connection will be lost. For example, if attaching a file takes more than the specified timeout period, then the connection will be timed out by the component. Default value -1 indicates infinite timeout.

AS1 Configuration

Enable AS1

Select this option to enable AS1 and provide signing, encryption and MDN configuration by clicking the AS1 SSL Configuration property ellipsis button.

Signature Configuration

Figure 3: Signature configuration details

Sign Mail

Enable this property to sign mail and provide algorithm and key store details to be used for signing.

Alias

Host private key alias should be configured.

Icon

Refer to the SSL Configuration – Client perspective section for configuring keystore and certificate alias details.

MDN configuration

Figure 4: MDN configuration details

Request Receipt

Choose whether MDN should be signed or unsigned.

Encryption Configuration

Figure 5: Encryption configuration details

Encrypt Mail

When this option is selected, mail will be encrypted with the provided algorithm and Keystore details.

Interaction Configurations Panel

Figure 6: Interaction Configurations

Sender Information

Display Name of the Sender

Name of the Sender to be displayed in the mail that is sent using the component.
If the input message has <From> element, its value overrides the display name specified by this property.

Email ID of the Sender

The sender's e-mail ID. This ID must be valid with respect to the server details provided in the Managed Connection Factory Panel.

Icon

If the input message has <From> element, its value overrides the e-mail ID specified by this property.

Input

SMTP component takes the input in XML format as shown below when SMTP protocol is selected.

Sample input in XML format when SMTP protocol is selected

SMTP component takes the input in XML format as shown below when NNTP protocol is selected.

Sample input in XML format when NNTP protocol is selected

Descriptions of the elements involved are as below:

To: Applicable only for SMTP protocol, E-mail ID of the primary recipient(s). For multiple recipients, the e-mail IDs should be separated by comma.
Newsgroup: Applicable only for NNTP protocol Newsgroup ID/Name of the primary recipient(s). For multiple recipients, the Newsgroup IDs should be separated by comma.
From: E-mail ID of the sender. The E-mail ID provided here will override the value provided for property Email ID of the Sender in the CPS. This element is optional.
CC: Applicable only for SMTP protocol, E-mail ID of the CC (carbon copy) recipient(s) to be copied in the e-mail. For multiple recipients, the e-mail IDs should be separated by comma. This element is optional.
BCC: Applicable only for SMTP protocol, E-mail ID of the BCC (blind carbon copy) recipient(s) to be copied in the mail. For multiple recipients, the e-mail IDs should be separated by comma. This element is optional.
ReplyTo: Applicable only for SMTP protocol, ReplyTo header field. Comma separated e-mail IDs can be used here.
The ReplyTo field is used by some e-mail programs when the Reply address is different than the From address.
While replying to an e-mail using Reply function, if ReplyTo header was set on the message, then the e-mail client shows the Reply-To field instead of the From field in the To address. This element is optional.
DispositionNotificationTo: E-mail ID to which a receipt/acknowledgement mail is to be sent back to (from recipients of this mail).
ReturnReceipt: Boolean indicating whether the mail is a normal one or a receipt/acknowledgement mail. If set to 'true', a multi-part report will be generated and sent as acknowledgement mail.

Icon

DispositionNotificationTo and ReturnReceipt are mutually exclusive elements. If it is an acknowledgement mail, DispositionNotificationTo should not be present.
Subject: Subject of the e-mail. This element is optional.
Headers: The headers provided (name value pairs) are added as Headers in the message. This element is optional.

Icon

This cannot be used to replace the default e-mail headers.
Attachments: This option is used to send attachments in the e-mail. This element is optional.
The attachment name is the value of the name attribute in the Attachment element.
Icon
- The value of ContentId given to a particular attachment can be used to refer the attachment in 'HtmlBody' tag under 'Body' tag.
  Entities "<" and ">" should be used at the start and end of the ContentId to represent special characters '<' and '>' respectively. A ContentId with value 'sampleId' is demonstrated in the example below.
  Example
- If the value of readFromFile attribute is set to No, then a new attachment file is created with the data provided against this tag as the file contents, and added as an attachment to the email.
  Example
- If the value of readFromFile attribute is set to Yes, then the path of the file which has to be added as an attachment should be provided with this tag.
  Example
- The attribute base64encoded attribute specifies whether the attachment is base64 encoded. This property is used only when readFromFile attribute is set to "no".
- If base64encoded value is set to "yes", then the value is base64 decoded before sending as an attachment.
Body: Used to specify the e-mail message body. This element is optional.
- TextBody: Sets the given string as the body content with a MIME type of text/plain.
- HTMLBody: Sets the given value as the body content with MIME type text/html.

Output

If the e-mail is sent successfully, then the component sends an XML output with a single element Result.

Figure 7: Sample response

Functional Demonstration

Scenario 1

Sending HTML emails with attachment.

Icon

Choose scenario(s) that can be superset in terms of number of features it can demonstrate.

Configure the SMTP Bridge as described in Configuration and Testing section and use Feeder and Display component to send sample input and check the response respectively.

Figure 8: Sample flow for Scenario 1

Sample Input

Output

Figure 9: Mail sent by SMTP Bridge in the Inbox

Use Case Scenario

In an order entry scenario e-mails can be sent to the concerned party when a PO is accepted or rejected.

Figure 10: Event Process demonstrating

The Event Process demonstrating this scenario is bundled with the installer.

Documentation of the scenario and instructions to run the flow can be found in the Help tab of the Event Process in Fiorano Studio.

Useful Tips

SMTP component can be used as ESB Alerter when configured with ExceptionListener component to listen for exceptions from all flows.
If the component is used to connect to a mail server that is SSL enabled, set the value of property 'mail.smtp.ssl.enable' to 'true' in Additional Properties in Connection Configuration.
If the component is used to connect to a mail server that is SSL enabled and the component is running in-memory, enable SSL in component configuration and provide the truststore location and password. In general, this truststore is %JAVA_HOME%\jre\lib\security\cacerts.

Icon

To understand the service better, refer the Sending and Receiving emails example which demonstrates SMTP service features.