Configure the Mail Transport Connector

The mail transport connector makes it possible to use IFS Applications using SMTP and POP3 or IMAP protocol. 
With an ordinary email client, a user can create an email message in any format and send it to the IFS Connect configured mailbox. 
The Mail Sender makes it possible to send mail in different formats using SMTP protocol.

Contents

• Common parameters
• Mail Sender specific parameters
• Mail Reader specific parameters
• How to create new instances of the Mail connector
   

Mail Sender specific parameters

• HOST
  Host name or IP address of machine hosting the SMTP server
• PORT
  Port number the SMTP server is listening on.
• TIMEOUT
  Time in seconds to wait for an answer from the server.
• PERFORM_AUTH
  Tick in if the SMTP server requires authentication.
• USER
  Username for the user connecting to the SMTP server if the server requires authentication.
• PASSWORD
  Password for the user connecting to the SMTP server.
• DEFAULT_MAIL_SENDER
  Default mail address shown in the From field if the sender mail address is not specified.
• OVERRIDE_MAIL_SENDER
  If enabled the mail address specified in DEFAULT_MAIL_SENDER will be used in the From field even if the sender is specified
• CONTENT_TYPE
  Choose the content type to use.
• SECURITY_PROTOCOL
  Choose SSL/TLS or SMTP+STARTTLS for SMTP over SSL.

Additional parameters are specified on Routing Address for Destination Type Mail.

Usage of DEFAULT_MAIL_SENDER and OVERRIDE_MAIL_SENDER parameters

The From field is normally on form "Name <local-part@domain>". How the two parts of the From field, i.e. the 'name' part and the 'mail address' part are combined depends on the following:

• If the flag OVERRIDE_MAIL_SENDER is not set and sender specification on the incoming message represents a valid mail address, i.e. contains the @ character, then it will be used as the From field.
• If the flag OVERRIDE_MAIL_SENDER is not set, sender specification is not a valid mail address (it is just a name) and DEFAULT_MAIL_SENDER is on form "local-part@domain", then the 'name' part of the From field will be taken from the sender specification and the 'mail address' part from DEFAULT_MAIL_SENDER
• If the flag OVERRIDE_MAIL_SENDER is not set, sender specification is not a valid mail address, but DEFAULT_MAIL_SENDER is on form "Name <local-part@domain>", then only DEFAULT_MAIL_SENDER will be used (sender specification will be ignored).
• If the flag OVERRIDE_MAIL_SENDER is set and DEFAULT_MAIL_SENDER is on form "Name <local-part@domain>" than it will be used.
• If the flag OVERRIDE_MAIL_SENDER is set and DEFAULT_MAIL_SENDER is on form "local-part@domain" than DEFAULT_MAIL_SENDER will be used as 'mail address' part and Mail Sender name (i.e. instance name) as the 'name' part.

Note: In a Mail Event Action flow the sender specification on the incoming message is set to the 'From User' if it is set . If not the logged in user will be set to the sender specification on the incoming message.

Mail Server and SSL

If the SMTP connection is secured by SSL / TLS, choose correct SECURITY_PROTOCOL and specify user name and password.
Certificates:
If any third party mail servers that requires SSL is being used you probably do not need to care about the certificate, but in case the certificate is not trusted, the mail reader will not be able to establish a connection to the mail server. To mark a certificate as trusted you need to get hold of the actual certificate and import it to the keystore using the keytool command.
Trust a certificate:
This guide assumes you already have obtained a copy of the certificate from a safe source. There are ways to obtain the certificate by other means but this is not recommended and beyond the scope of this guide.

1. To trust a certificate you need to use the keytool command supplied with the JDK. You will need to locate the JDK used during runtime by your application server.
   You can choose to create a new truststore or use the cacerts that comes with the java installation.
   Example:
   <java_home>/bin/keytool -import -alias <certificate-alias> -file <certificate.cer> -keystore <truststore> -storepass <thePassword>
   Where:
   -alias: Is the alias of the mail certificate (can be whatever you wish but use a descriptive name)
   -file: The certificate file
   -keystore: The keystore you want to put it in. If you choose to use a new truststore you do not need to give the -storepass argument. If you do, however, this will be the password for the new truststore. If you rather use cacerts storepass it is located in <java_home>/jre/lib/security.
   -storePass: Is the password to the truststore. (The default password for cacerts is 'changeit' or 'changeme' depending on the platform.)
2. The keytool command will print out the certificate information including the fingerprint and ask you to verify it. You should verify this fingerprint by comparing it with the original certificate before adding it to the truststore. You can check the fingerprint of a certificate using the -printcert command.
   Example:
   keytool -printcert -file <certificate>
   If the fingerprint is OK, add it and you should see a confirmation that the certificate has been added successfully.

Mail Reader specific parameters

WARNING: You should not use your own mail account for the mail reader. You will  get errors that result in a large number of replies to many people who may have sent you mail. It is recommended that you set up a separate mail account to be used only for the mail reader connector. 

Note: OAuth support for mail reader is added after UPD19 (165088) with Auth methods AuthorizationCode and ClientCredentials

• HOST
  Host name or IP address of machine hosting the Mail server
• PORT
  Port number the Mail server is listening on.
• AUTH_METHOD
  Choose correct authentication method, Basic/ClientCredentials/AuthorizationCode. If ClientCredentials or AuthorizationCode is used, relevant permissions to read mails should be granted and configured for the user connecting to the mail server.
• USER
  Username for the user connecting to the Mail server.
• PASSWORD
  Password for the user connecting to the Mail server.This is required if Basic auth method is used.
• CLIENT_ID
  OAuth Client Id of the application. This is required if ClientCredentials or AuthorizationCode auth method is used.
• CLIENT_SECRET
  OAuth Client Secret of the application. This is required if ClientCredentials or AuthorizationCode auth method is used.
• ACCESS_TOKEN
  Valid OAuth Access token which should be obtained with the permissions to read mails for the account which is configured according to the mail server setup for the user to authenticate the request. This is required if AuthorizationCode auth method is used.
• REFRESH_TOKEN
  Valid OAuth Refresh token obtained in the mail server setup which is used to get a new access token when the provided access token is expired. This is required if AuthorizationCode auth method is used.
• TOKEN_ENDPOINT
  Auth Token endpoint based on the mail server setup which is used to get the valid access token with permissions to read mails for the account which is configured. This is required if ClientCredentials or AuthorizationCode auth method is used.
• MAIL_PROTOCOL
  Choose correct protocol, POP3 or IMAP.
• SECURITY_PROTOCOL
  Choose SSL/TLS if the server is secured.
• PARSE_BODY
  Tick to enable the reader to read messages that are sent in the body. Normally a message is sent as an attachment.
• TIMEOUT
  Time in seconds to wait for an answer from the server.

Note: If AuthorizationCode and ClientCredentials auth methods are used, valid access and refresh tokens should be used to authenticate and read mails.For that you should configure the relevant permissions to read mails for the account in your third party email server which supports OAuth.

Note: OAuth for mail reader is not supported with POP3 mail protocol (due to an incompatibility issue with Middleware Server) and only IMAP protocol is supported.

How to create new instances of the Mail Connector

It's possible to create new instances of the Mail Reader Transport Connector provided that they should poll distinct mailboxes (Only one Mail Reader can poll a mailbox).

Instructions for how to create a new connector instance.