Enable mail debugging mode in Jira Data Center

Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.

Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Summary

To detail clearly how to enable debug mode for both the incoming and outgoing emails in Jira.

Solution

  • Go to Administration (Gear next to profile) > System > Logging and Profiling page

    • This can also be accessed by pressing 'g+g' and typing Logging and Profiling in the pop-up.

  • For Outgoing Mail,

    • Scroll down the page to the Outgoing Mail Section

    • Ensure that you have an Outgoing Mail configured and that Outgoing Mail log is enabled as without it, debugging cannot be enabled through the UI.

      ℹ️ If you are only using Jira Service Management email, you need to add the package com.atlassian.mail as DEBUG

    • Click the blue Enable link that appears in this section to enable outgoing mail debugging.

    • To persist the debug logging enabled, even after you restart Jira:

      • Edit the <jira-installation>/atlassian-jira/WEB-INF/classes/log4j.properties file.

      • Locate the section:

        1 log4j.logger.com.atlassian.mail = INFO, outgoingmaillog

        and change INFO to DEBUG.

      • For Jira 9.5 and above the configuration file that will need to be updated is named log4j2.xml and the syntax for adding the debug logging has changed.

      • Edit the <jira-installation>/atlassian-jira/WEB-INF/classes/log4j2.xml file

      • Add the content below just before the closing "<Loggers>" tag.

        1 2 3 <Logger name="com.atlassian.mail.outgoing" level="DEBUG" additivity="false"> <AppenderRef ref="outgoingmaillog"/> </Logger>
    • For batch notifications specifically, set the packagecom.atlassian.jira.plugins.inform.batching to DEBUG

  • For Incoming Mail,

    • Scroll down the page to the Incoming Mail Section

    • Ensure that you have an Incoming Mail configured and that Incoming Mail log is enabled as without it, debugging cannot be enabled through the UI.

      ℹ️ If you are only using Jira Service Management email, you need to add the package com.atlassian.mail.incoming as DEBUG

    • Click the blue Enablelink that appears in this section to enable Incoming mail debugging.

    • To persist the debug logging enabled, even after you restart Jira:

      • Edit the <jira-installation>/atlassian-jira/WEB-INF/classes/log4j.properties file.

      • Locate the section:

        1 log4j.logger.com.atlassian.mail.incoming = INFO, incomingmaillog

        and change INFO to DEBUG.

      • For Jira 9.5 and above the configuration file that will need to be updated is named log4j2.xml and the syntax for adding the debug logging has changed.

      • Edit the <jira-installation>/atlassian-jira/WEB-INF/classes/log4j2.xml file

      • Add the content below just before the closing "<Loggers>" tag.

        1 2 3 <Logger name="com.atlassian.mail.incoming" level="DEBUG" additivity="false"> <AppenderRef ref="incomingmaillog"/> </Logger>
  • To enable email logging for incoming and outgoing at the protocol level (more verbose), add -Dmail.debug=true to the Jira startup parameters.

For more information on the subject, please refer to Logging and Profiling.

ℹ️ Keep in mind that the primary goal of debug logging is troubleshooting. A good practice to avoid potential performance impact and logs with too many entries in the future is to disable the debug logging after the problem is solved.

Updated on April 15, 2025

Still need help?

The Atlassian Community is here for you.