Health Check: Mail Error Queue
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 use the health check for a mail error queue, upgrade the ATST plugin to at least version 1.53.2.
Solution
About the health check
This health check ensures the healthiness of email sending in Confluence Data Center. Emails that couldn't be delivered to a recipient will appear in a mail error queue. Email sending is unhealthy when a mail error queue has any emails.
In Confluence Data Center, if you get a notification about a failed health check for a mail error queue but see that the check passed on the System tools page, this might indicate failures on another node. In this situation, we highly recommend checking the mail error queue on each node separately. This is a known issue and we’re working on improving the behavior of this health check and your experience with Confluence.
Understanding the results
Confluence Server
Pass
Icon | Result | What this means |
|---|---|---|
✅ Pass | There are no emails in an error queue. | All emails have been delivered to recipients. |
⚠️ Warning | There is a number of emails in the error queue. | An exact number of emails couldn't be delivered to recipients, and Confluence won't retry sending. An administrator should troubleshoot the issue. |
Confluence Data Center
Icon | Result | What this means |
|---|---|---|
✅ Pass | There are no emails in the error queue on a particular node. If you get a notification about a failing health check for a mail error queue, verify the other nodes. | All emails have been delivered to recipients from this particular node. |
⚠️Warning | There is a number of emails in an error queue on a particular node. | An exact number couldn't be delivered to recipients from this particular node, and Confluence won't retry sending. An administrator should troubleshoot the issue. |
What happens if I ignore the warning?
Emails in a mail error queue won't be sent to recipients. This means that some users may never get a Confluence email notification intended for them.
Troubleshooting
As an immediate mitigation step, you might consider resending a mail error queue. To do this, go to Administration and selectGeneral configuration. Then, go to Mail queue and Error queue. Here, you can either resend or remove all emails in an error queue.
Take this step only as a temporary workaround since it won't resolve the underlying issue with sending emails.
In some situations, manually resending a mail error queue won't help, and emails might still pile up in the error queue. In these cases, don't try to resend the error queue several times. This action will generate more threads for Confluence to process, causing potential performance issues.
To resolve the issues when emails aren't sent from the Confluence, check Mail troubleshooting.
How to clear the mail error queue (step-by-step):
Log in to Confluence as a System Administrator.
Go to Administration (⚙️) > General Configuration > Mail Queue, then click the Error Queue tab.
Scroll down to the Mail Error Queue section. You will see a list of failed emails with timestamps and error messages.
Review the error messages. Common causes include:
Connection timeout: The mail server is not reachable. Verify SMTP host and port in Administration (⚙️) > General Configuration > Mail Servers.
Authentication failed: The username or password for the SMTP account is wrong. Re-enter credentials in Administration (⚙️) > General Configuration > Mail Servers.
Mailbox full: The sender's mailbox has reached quota. Contact your email administrator to increase the quota or delete old emails.
After fixing the underlying cause (SMTP config, credentials, or mailbox quota), Click Resend Error Queue to attempt redelivery, or Delete Error Queue to discard all failed items.
Verification: After clearing the error queue, return to Administration (⚙️) > General Configuration > Mail Queue > Error Queue tab and confirm the Mail Error Queue is now empty or shows a count of 0 items. Send a test notification (e.g., trigger a user mention in a space) and confirm that email reaches the recipient. If the error queue begins to fill again, the underlying SMTP issue is not resolved — go to "When this won't help" below.
When this won't help — Mail errors keep recurring after clearing the queue:
If the error queue continues to fill with mail errors even after you clear it and fix the SMTP configuration, the issue is usually one of the following:
SMTP configuration is still wrong: Double-check the SMTP host, port, username, and password in Administration (⚙️) > General Configuration > Mail Servers. Verify these credentials work by testing them directly with a mail client (e.g., Outlook, Thunderbird). If the credentials work in a mail client but not in Confluence, the SMTP server may have additional firewall or IP whitelist restrictions. Contact your email administrator.
Firewall or network restriction: Confluence may not have outbound connectivity to the SMTP server. Check with your network administrator to confirm port 25 (or your custom SMTP port) is open for outbound traffic from the Confluence server.
Mail server is down or unreachable: The SMTP server itself may be offline or unreachable. Ask your email administrator to verify the mail server is running and reachable from the Confluence server's IP address.
If none of the above apply, contact Atlassian Support with the error messages from the Mail Error Queue and your SMTP configuration details (host, port, and username only — do not share the password).
Providing data to Atlassian Support
If you still can't troubleshoot and fix the problem, create a support ticket at support.atlassian.com and attach the requested information. To get support:
Follow the guidelines in Enable mail debugging mode in Confluence Data Center and Server.
Wait for about 15 minutes so that we can collect enough logs.
Go to Administration>General configuration > Troubleshooting and support tools > Create support zip.
Select Customize zip, then select Thread dumps, and select Save.
SelectCreate zip and download the support zip. In case you have a Data Center cluster, repeat this step for each node.
Attach to the support ticket:
The support zips
Related articles
Was this helpful?