Troubleshooting the SMTP server

Edit online

This topic provides some troubleshooting tips for a successful connection to your SMTP server.

If the SMTP server is using TLSv1.2 protocol, you must upgrade to one of the following releases or iFix:
  • 6.0.5 iFix021
  • 6.0.6 iFix020
  • 6.0.6.1 iFix014
  • 7.0.0 iFix007
  • 7.0.1 iFix005
  • 7.0.2 and later iFixes/releases

The mail libraries shipped with the above versions support TLSv1.2.

The following JVM option is also required to enable TLSv1.2 for secure connection with the mail server: mail.smtp.ssl.protocols=TLSv1.2

For example, in WebSphere® Liberty server profile add the following in the server.startup.bat/sh.script and restart the server:
  • JAVA_OPTS="$JAVA_OPTS -Dmail.smtp.ssl.protocols=TLSv1.2"
  • set JAVA_OPTS=%JAVA_OPTS% -Dmail.smtp.ssl.protocols=TLSv1.2

Authorization enabled sample output

Open a command prompt and enter the following commands to verify if SMTP requires authentication.
telnet <smtp-serer> <port>
EHLO <server>
AUTH LOGIN
The following is a sample output when authorization is enabled:
C:\temp>telnet smtp.email.example.com 25

Line 1 220 smtp.email.example.com Microsoft ESMTP MAIL Service, Version: 8.5.9600.1
Line 2 6384 ready at  Fri, 10 Mar 2017 03:10:48 -0500
Line 3 EHLO smtp.email.example.com
Line 4 250-smtp.email.example.com Hello
Line 5 250-AUTH=LOGIN
Line 6 250-AUTH LOGIN
Line 7 250-TURN
Line 8 250-SIZE 2097152
Line 9 250-ETRN
Line 10 250-PIPELINING
Line 11 250-DSN
Line 12 250-ENHANCEDSTATUSCODES
Line 13 250-8bitmime
Line 14 250-BINARYMIME
Line 15 250-CHUNKING
Line 16 250-VRFY
Line 17 250 OK
Line 18 AUTH LOGIN
Line 19 334 VXNlcm5hbWU6

In the preceding sample output, line 1 and 2 are for the SMTP banner on receiver greetings. Line 3 is the EHLO extended SMTP command to initiate the communication. It displays a detailed response from the server. Line 5 and 6 indicate that the server is configured for authentication. The AUTH LOGIN command on line 18 gets a response back to enter user name with a question mark in base64 encoded text.

In order to use a user name and password in this telnet session, you must provide the user name and password in base64 encoding format.

Enter the following commands to get the base64 encoding for strings username and password:
$ perl -MMIME::Base64 -e 'print encode_base64("username");'
output:
dXNlcm5hbWU=
$ perl -MMIME::Base64 -e 'print encode_base64("password");'
output:
cGFzc3dvcmQ=
Then, you can use the user name and password as follows:
$ telnet smtp.email.example.com 25
Trying smtp.email.example.com...
Connected to smtp.email.example.com
Escape character is '^]'.
220 smtp.email.example.com Microsoft ESMTP MAIL Service, Version: 8.5.9600.16384 ready at  Sat, 11 Mar 2017 08:24:11 -0500
EHLO smtp.email.example.com
250-smtp.email.example.com Hello
250-AUTH=LOGIN
250-AUTH LOGIN
250-TURN
250-SIZE 2097152
250-ETRN
250-PIPELINING
250-DSN
250-ENHANCEDSTATUSCODES
250-8bitmime
250-BINARYMIME
250-CHUNKING
250-VRFY
250 OK
AUTH LOGIN
334 VXNlcm5hbWU6
dXNlcm5hbWU=
334 UGFzc3dvcmQ6
cGFzc3dvcmQ=
235 2.7.0 Authentication successful

After issuing the AUTH LOGIN command, lines starting with 334 are requests to enter the user name and password encoded in base64.

Authorization disabled sample output

The following sample output is for when the authorization is disabled:
C:\temp>telnet smtp.email.example.com 25

Line 1 220 ESMTP IMSVA 9.0
Line 2 EHLO smtp.email.example.com
Line 3 250-smtp.email.example.com
Line 4 250-PIPELINING
Line 5 250-SIZE 26214400
Line 6 250-ETRN
Line 7 250-STARTTLS
Line 8 250-ENHANCEDSTATUSCODES
Line 9 250-8BITMIME
Line 10 250 DSN
Line 11 AUTH LOGIN
Line 12 503 5.5.1 Error: authentication not enabled

In the preceding sample output, line 1 is for the SMTP banner on receiver greetings. Line 2 is the EHLO extended SMTP command to initiate the communication. It displays a detailed response from the server. Line 11 is to issue the AUTH LOGIN command and line 12 is the error prompt that indicates the authentication isn’t enabled on the SMTP server. If SMTP server has authorization disabled as shown in preceding sample output, then user name and password field should not be configured in Jazz® Team Server email settings section or in the teamserver.properties file of Jazz Team Server.

Other issues you might encounter

C:\temp>telnet smtp.email.example.com 25

Line 1 220 ***************
Line 2 EHLO
Line 3 502 5.5.2 Error: command not recognized
Line 4 AUTH LOGIN
Line 5 502 5.5.2 Error: command not recognized
Line 6 quit
Line 7 502 5.5.2 Error: command not recognized

In the preceding sample output, line 1 indicates that after connecting to the SMTP server, the SMTP banner seems corrupt by displaying (***************). The banner characters are replaced by asterisks. The reason for this is that a firewall or third party application in your environment is interfering or performing an inspection on the SMTP/ESMTP traffic. It may filter out or replace the SMTP traffic or the SMTP commands. This might be a firewall of router/proxy between the Engineering Lifecycle Management server and the SMTP server, or even some email security software. To resolve this issue, you can change the attribute of port 25 in the firewall to not monitor SMTP/ESMTP traffic, or modify the router/proxy firewall to disable any SMTP/ESMTP inspection. Alternatively, you can use a different port number for the SMTP Server, such as 587.

After you get a good banner response from the SMTP server, then you can use the SMTP for Engineering Lifecycle Management servers.

STARTTLS option

You can only use STARTTLS option with Jazz Team Server mail settings if your SMTP server is configured with TLS encryption using Signer certificate.

If your SMTP server is configured with TLS encryption, then you can import the Signer certificate from SMTP server into your IBM® WebSphere Liberty or IBM WebSphere Application Server trust keystore and then enable the STARTTLS option to true in Jazz Team Server. A server restart might be required after importing the certificate. For details, see Installing a security certificate

Sample DEBUG output by using the DEBUG MAIL API

220 smtp.example.com Microsoft ESMTP MAIL Service
EHLO HOST
250-smtp.example.com Hello
250-AUTH=LOGIN
250-AUTH LOGIN
250-TURN
250-SIZE 2097152
250-ETRN
250-PIPELINING
250-DSN
250-ENHANCEDSTATUSCODES
250-8bitmime
250-BINARYMIME
250-CHUNKING
250-VRFY
250-TLS
250-STARTTLS
250 OK
STARTTLS
220 2.0.0 SMTP server ready
EHLO HOST
250-smtp.example.com Hello
250-AUTH=LOGIN
250-AUTH LOGIN
250-TURN
250-SIZE 2097152
250-ETRN
250-PIPELINING
250-DSN
250-ENHANCEDSTATUSCODES
250-8bitmime
250-BINARYMIME
250-CHUNKING
250-VRFY
250 OK
AUTH LOGIN
334 VXNlcm5hbWU6
<base64 encoded user name>
334 UGFzc3dvcmQ6
<base64 encoded password>
235 2.7.0 Authentication successful