Lifting the Hood on JavaMail Communications

Body

Introduction

In this short article we'll cover the mail.debug property which can help isolate e-mail related problems, specifically those that may occur during communication between the JavaMail API and your corporate (or test) e-mail server. The JavaMail API is part of the J2EE stack of libraries provided by your application server and the MXServer uses it for sending (SMTP) and receiving (POP3, IMAP) e-mail.

Note: If you give this a try, please do so on a non-critical test system because, as is typical of debug functions, the logging is chatty.
 
Add mail.debug Property

The mail.debug property does not exist out-of-the-box so it will need to be added via the System Properties application.  Note that this is a JavaMail property and not a Maximo property.

    O DEBUG: JavaMail version 1.4ea
      <snip>
    O DEBUG SMTP: useEhlo true, useAuth true
    O DEBUG SMTP: trying to connect to host "caesar.swg.usma.ibm.com", port 25, isSSL false
    O 220 CAESAR ESMTP
    O DEBUG SMTP: connected to host "caesar.swg.usma.ibm.com", port: 25
    O EHLO caesar
    O 250-CAESAR
    250-SIZE 20480000
    250 AUTH LOGIN
    O DEBUG SMTP: Found extension "SIZE", arg "20480000"
    O DEBUG SMTP: Found extension "AUTH", arg "LOGIN"
    O DEBUG SMTP: Attempt to authenticate
    O AUTH LOGIN
    O 334 VXNlcm5hbWU6
    O YWRtaW5AbWF4aW1vLmRldg==
    O 334 UGFzc3dvcmQ6
    O YWRtaW4=
    O 235 authenticated.
    O DEBUG SMTP: use8bit false
    O MAIL FROM:<admin@maximo.dev>
    O 250 OK
    O DEBUG SMTP: sendPartial set
    O RCPT TO:<pete@maximo.dev>
    O 250 OK
    O DEBUG SMTP: Verified Addresses
    O DEBUG SMTP:   pete@maximo.dev
    O DATA
    O 354 OK, send.
    O Date: Thu, 24 May 2012 09:30:34 -0400 (EDT)
    From: "admin@maximo.dev" <admin@maximo.dev>
    To: pete@maximo.dev
    Message-ID: <2042001846.11337866216353.JavaMail.Administrator@caesar>
    Subject: Test subject wonum = 5012
    MIME-Version: 1.0
    Content-Type: multipart/mixed;
        boundary="----=_Part_1_392435556.1337866216353"

    ------=_Part_1_392435556.1337866216353
    Content-Type: text/html
    Content-Transfer-Encoding: 7bit

    Test body wonum = 5012<br /><div></div><br /><br /><!-- RICH TEXT -->
    ------=_Part_1_392435556.1337866216353--

    .
    O 250 Queued (0.015 seconds)
    O QUIT
    O 221 goodbye
    

Failure Examples

1) Invalid credentials are passed to the e-mail server:

    O AUTH LOGIN
    O 334 VXNlcm5hbWU6
     O YWRtaW5AbWF4aW1vLmRldg==           
    O 334 UGFzc3dvcmQ6               <=== base 64 decoded: Password: prompt
    O QkFEUEFTU1dPUkQ=           <=== base 64 decoded: BADPASSWORD
    O 535 Authentication failed. Restarting authentication process.

2)  The e-mail server is configured to only accept email addresses from the local domain:

    O MAIL FROM:<admin@maximo.dev>
    O 250 OK
    O DEBUG SMTP: sendPartial set
    O RCPT TO:<pete@maximo.dev>
    O 250 OK
    O RCPT TO:<pete@external.dev>                        <===  An attempt to send to an external email address
    O 550 Delivery is not allowed to this address.  <===  ... and it's rejected by the email server
    O DEBUG SMTP: Verified Addresses
    O DEBUG SMTP:   pete@maximo.dev
    O DEBUG SMTP: Invalid Addresses
    O DEBUG SMTP:   pete@external.dev

 
Summary

Using the JavaMail mail.debug property is helpful when diagnosing e-mail communication issues that occur outside of Maximo.  The failure messages issued by the e-mail server are displayed in the debug trace, making determining the cause of communication problems unambiguous.

 
References:
JavaMail API Documentation