Enable mail debugging mode in Confluence Data Center
Platform Notice: Data Center Only - This article only applies to Atlassian apps 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 Confluence.
Solution
This feature is only available on Confluence Data Center 7.20 or later.
You need System Administrator global permissions to do this.
Change the logging level of the com.atlassian.confluence.mail.session package
Go to Administration > General Configuration > Logging and Profiling.
If you run Confluence in a cluster, select a cluster node.
Locate the
com.atlassian.confluence.mail.sessionpackage, and select DEBUG value from the New Level menu.Save your changes.
Remember, your changes will not be written to the log4j.properties file and will be discarded when you next stop Confluence.
Persistent logging (survives restart): The UI method above resets when Confluence stops. If you need mail debug logging to persist across restarts, add the following line to <Confluence-install>/confluence/WEB-INF/classes/log4j.properties:
log4j.logger.com.atlassian.confluence.mail.session=DEBUG
Restart Confluence for the change to take effect. If running Data Center in a cluster, apply this change on every node. Remember to revert the change once troubleshooting is complete to avoid excessive log volume. See Configuring Logging | Confluence Data Center 10.2 | Atlassian Documentation for more details on permanent logging changes.
⚠️ Confluence upgrades can overwrite log4j.properties with the shipped default. After any upgrade, re-check this file and re-apply your custom configuration if it was reset.
To enable email logging at the protocol level (more verbose), add -Dmail.debug=true to the Confluence System Properties.
Verification: After enabling DEBUG logging, send a test email from Administration > General Configuration > Mail Servers and check for new entries:
For the UI method (
com.atlassian.confluence.mail.sessionat DEBUG): look inatlassian-confluence.logfor entries containingJmxSMTPMailServerordoSendWithMessageIdSupport.For the system property method (
-Dmail.debug=true): look in<install-directory>/logs/catalina.outfor entries starting withDEBUG SMTP:.
If no new entries appear, verify you saved the change on the correct cluster node (if running DC), and that the test email was triggered after the logging change was applied.
ℹ️ Keep in mind that the primary goal of debug logging is troubleshooting. It is good practice to disable the debug logging after the problem is solved to avoid potential performance impacts and logs with too many entries.
Was this helpful?