Logging & Debugging Simple Java Mail

Logging emails instead of sending
Override envelope-level receivers
Enable javax.mail debug logging
Inspect a mailer or an email
Catching exceptions
Logging output
Example with log4j12
Example with log4j2
Example with logback

Logging emails instead of sending

You can configure the Mailer to log emails instead of sending them.

Note: normally emails are always logged on Level.DEBUG level, but in logging mode emails are logged in Level.INFO.

Mailer mailer = MailerBuilder
    .withTransportModeLoggingOnly()
    .(...)
    .buildMailer();

mailer.sendMail(email); // <-- this email will be logged but not sent

or:

simplejavamail.transport.mode.logging.only=true

Override envelope-level receivers

For testing purposes, you can change where the email is sent to, without touching the actual email being sent, by overriding the envelope-level receivers. It's super easy.

// send the email to your testers
currentEmailBuilder.withOverrideReceivers(tester1Recipient, testGroupInboxRecipient...);

Enable javax.mail debug logging

By default javax.mail's debug logging is turned off, but you can turn it on for more diagnostic info. All this does is enabling debug mode on the internal Session instance.

mailer.withDebugLogging(true);

// or
mailer.getSession().setDebug(true);

// or
yourSession.setDebug(true);
MailerBuilder.usingSession(yourSession);

or:

simplejavamail.javaxmail.debug=true

Inspect a mailer or an email

After building a Mailer or an Email instance, you can read everything back from it and see if it is what you expected.

You can verify default values this way as well.

email.getAnythingYouCanSetWithABuilder();

mailer.getSession();
mailer.getTransportStrategy();
mailer.getServerConfig();
mailer.getProxyConfig();
mailer.getOperationalConfig();
// default S/MIME signing, validation criteria etc.
mailer.getEmailGovernance();

Catching exceptions

Simple Java Mail throws a MailException if something goes wrong and logs these by default using SLF4J. This includes checked exceptions thrown by underlying frameworks.


try {
   mailer.sendMail(email);
} catch (MailException e) {
   // handle the exception
}

Logging output

Simple Java Mail uses SLF4J to log, which means you can use any logging framework you like that supports it. Also read this excellent summary of how to configure slf4j with log4j2.

Aside from the native Jakarta Mail logging, the following parts of Simple Java Mail may produce additional logging:

"org.simplejavamail"
"org.simplejavamail.internal.clisupport"
"org.simplejavamail.internal.dkimsupport"
"org.simplejavamail.internal.smimesupport"
"org.simplejavamail.internal.authenticatedsockssupport"
"socks5bridge"

The latter two are for the proxy bridge that is used for authenticated proxy connections.

If you wish to know where and how the properties are loaded, you can increase logging for "org.simplejavamail.config.ConfigLoader". This will tell you which properties are loaded by API and which from config file and which properties are without value.

When using maven, Simple Java Mail provides some default XML configuration for log4j2, but you can easily switch to something else. Below are some examples.

You can also checkout the log4j2 configuration used in our own tests.

Example with log4j12

Here's an example configuration for log4j12, make sure you have the slf4j-to-log4j impl included on the classpath as well as log4j12 itself and the log4j.xml with the config.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" debug="false">

    <appender name="console" class="org.apache.log4j.ConsoleAppender">
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%d [%t] %-5p %c{1} - %m%n"/>
        </layout>
    </appender>
    <appender name="simpleConsole" class="org.apache.log4j.ConsoleAppender">
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%d Simple Java Mail SOCKS5 bridge - %p %m%n"/>
        </layout>
    </appender>

    <logger name="org.simplejavamail">
        <level value="trace"/>
        <appender-ref ref="console"/>
    </logger>
    <!-- in case you're using authenticated proxy -->
    <logger name="socks5bridge" additivity="false">
        <level value="info"/>
        <appender-ref ref="simpleConsole"/>
    </logger>
    <logger name="org.simplejavamail.internal.authenticatedsockssupport">
        <level value="warn"/>
    </logger>

</log4j:configuration>

Example with log4j2

Here's an example configuration for log4j2, make sure you have the log4j-slf4j-impl impl included on the classpath as well as log4j2 itself and the log4j2.xml with the config.

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="OFF">
    <appenders>
        <Console name="console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss} [%t] %-5level %c{1} - %msg%n" />
        </Console>
        <Console name="simpleConsole" target="SYSTEM_OUT">
            <PatternLayout pattern="%d Simple Java Mail SOCKS5 bridge - %level %m%n" />
        </Console>
    </appenders>
    <Loggers>
        <Logger name="org.simplejavamail" level="trace"/>
        <!-- in case you're using authenticated proxy -->
        <Logger name="socks5bridge" level="info" additivity="false">
            <AppenderRef ref="simpleConsole" />
        </Logger>
        <Logger name="org.simplejavamail.internal.authenticatedsockssupport" level="warn"/>

        <Root level="warn">
            <AppenderRef ref="console" />
        </Root>
    </Loggers>
</configuration>

Example with logback

Here's an example configuration for logback, make sure you have the logback-classic included on the classpath as well as logback-core and the logback.xml with the config.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %c{1} - %msg%n</pattern>
        </encoder>
    </appender>
    <appender name="simpleConsole" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d Simple Java Mail SOCKS5 bridge - %level %m%n</pattern>
        </encoder>
    </appender>

    <logger name="org.simplejavamail" level="TRACE"/>
    <!-- in case you're using authenticated proxy -->
    <logger name="socks5bridge" level="INFO" additivity="false">
        <appender-ref ref="simpleConsole" />
    </logger>
    <logger name="org.simplejavamail.internal.authenticatedsockssupport" level="WARN"/>

    <root level="WARN">
        <appender-ref ref="console" />
    </root>
</configuration>