/
Configuring SMTP endpoints

Configuring SMTP endpoints

Aug 31, 2021

Overview

The JavaMail framework is integrated into FIXEdge Java in the form of SMTP destination endpoints and gives the ability to send emails to external SMTP servers.

SMTP is a destination endpoint only.

Configuration properties

The list of main FEJ SMTP endpoint properties:

Property

Description

Required

Property

Description

Required

mail.clients

A comma-separated list of FEJ SMTP client IDs

Y

mail.<clientId>.host

The SMTP server to connect to

Y

mail.<clientId>.port

The SMTP server port to connect to

Y

mail.<clientId>.username

The SMTP user name to connect with

Y

mail.<clientId>.password

The SMTP user's password. Optional if SMTP supports user access without a password.

N

mail.<clientId>.protocol

Protocol for connection to the SMTP server. 'smtp' supported.

N

mail.<clientId>.subject

Default email's subject

Y

mail.<clientId>.to

Default email's 'To' comma-separated list

Y

mail.<clientId>.cc

Default email's 'Cc' comma-separated list

N

mail.<clientId>.bcc

Default email's 'Bcc' comma-separated list

N

mail.<clientId>.groups

FEJ groups for routing to this SMTP endpoint

N

mail.<clientId>.converterRef

An instance of the email converter interface, as a reference to the Spring bean name, to convert incoming MessageEvent to email fields.

N

mail.<clientId>.converterClass

Implementation class of the email converter interface to create a converter instance on endpoint initialization. 

By default, an implementation based on Apache Velocity templates is used.

N

The list of the main JavaMail properties, set with the mail.<clientId>'.properties prefix:

Property

Description

Property

Description

mail.smtp.from

Email address to use for the SMTP MAIL command. This sets the envelope return address.

mail.smtp.auth

If true, attempt to authenticate the user using the AUTH command.

mail.smtp.socketFactory.port

Specifies the port to connect to when using the specified socket factory.

mail.smtp.socketFactory.class

If set, specifies the name of a class that implements the javax.net.SocketFactory interface. This class will be used to create SMTP sockets.

mail.smtp.starttls.enable

If true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. If the server does not support STARTTLS, the connection continues without the use of TLS; see the mail.smtp.starttls.required property to fail if STARTTLS isn't supported.

mail.smtp.starttls.required

If true, requires the use of the STARTTLS command. If the server doesn't support the STARTTLS command, or the command fails, the connect method will fail.

template

Path to the Velocity template file for the default email converter interface. See more at Template converter properties.

The full list of properties could be found here.

NOTE: The FIX session can be started or stopped only if scheduling is applied. Otherwise, the session will be inactive. Refer to the Configuring Scheduler section where the session start procedure is specified.

SMTP properties example

SMTP endpoint for Gmail server

STMP properties example
# comma separated list of SMTP clients mail.clients=smtp1 # SMTP server connection details mail.smtp1.host=smtp.gmail.com mail.smtp1.port=587 mail.smtp1.username=smtp-user1 mail.smtp1.password=pass1 # default Subject/To/CC/BCC values mail.smtp1.subject=Test subject mail.smtp1.to=<John_Doe@outlook.com, Jane_Doe@outlook.com, etc.> mail.smtp1.cc=<cc list> mail.smtp1.bcc=<bcc list> mail.smtp1.protocol=smtp # FEJ routing groups mail.smtp1.groups=mail1-group # Optional. Converter class or Spring reference bean name #mail.smtp1.converterClass=com.epam.fej.smtp.TestEmailConverter #mail.smtp1.converterRef=testEmailConverter # additional SMTP properties mail.smtp1.properties.mail.smtp.auth=true mail.smtp1.properties.mail.smtp.starttls.enable=true # Velocity template for email content mail.smtp1.properties.template=mail_message_template.vm

SMTP endpoint for Gmail server with TLS

STMP properties to send emails from Gmail
mail.clients=smtp-gmail mail.smtp-gmail.host=smtp.gmail.com mail.smtp-gmail.port=587 mail.smtp-gmail.username=<user_name> mail.smtp-gmail.password=<pass> mail.smtp-gmail.subject=Test subject mail.smtp-gmail.to=<John_Doe@outlook.com> mail.smtp-gmail.cc=<cc> mail.smtp-gmail.bcc=<bcc> mail.smtp-gmail.protocol=smtp mail.smtp-gmail.groups=gmail-group #mail.smtp-gmail.converterClass=com.epam.fej.smtp.TestEmailConverter #mail.smtp-gmail.converterRef=testEmailConverter mail.smtp-gmail.properties.mail.smtp.auth=true mail.smtp-gmail.properties.mail.smtp.starttls.enable=true mail.smtp-gmail.properties.mail.smtp.host=smtp.gmail.com mail.smtp-gmail.properties.mail.smtp.port=587 mail.smtp-gmail.properties.mail.smtp.socketFactory.port=587 mail.smtp-gmail.properties.mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory #mail.smtp-gmail.properties.mail.debug=true # Velocity template for email content mail.smtp1.properties.template=mail_message_template.vm

Using templates for emails

If custom implementation for the email converter interface is not defined, the SMTP endpoint uses the default one, which is based on Apache Velocity. Velocity is a Java template engine with simple but powerful syntax.

The converter puts the received MessageEvent object and all its header fields to the template context as shown in the table below:

Variable name

Variable type

Description

Variable name

Variable type

Description

event

MessageEvent

Original MessageEvent for converting to email.

source

AppEvent

Predefined header field. The source AppEvent instance in case, if it was routed to SMTP endpoint.

email.template

String

Predefined header field. Custom template name. Can be set via the MessageEvent#setHeader() field. 

email.subject

String

Predefined header field. Custom email subject. Can be set via the MessageEvent#setHeader() field. 

The path to the template should be defined with the template property in the SMTP endpoint configuration. If the template is placed into the conf directory, the path can be relative:

default Velocity template definition
mail.smtp-adaptor.properties.template=mail_message_template.vm

Sample template for sending a notification about FIX message

default Velocity template definition
*** FIXEdge SMTP Notification System ***<br/> <br/> Notification Type: FIX<br/> <br/> FIX: <b>$event.getMessage().toPrintableString()</b><br/>

Sample template for sending a notification about FIX session state change

default Velocity template definition
*** FIXEdge SMTP Notification System ***<br/> <br/> FIX Session ID: $source.getSessionId()<br/> New State: $source.getSessionState()<br/>