JIRA applications have a very flexible built-in facility for sending out email notifications under a wide variety of conditions. This guide is meant to help troubleshoot when email notifications are not being received.
There is now a Notification Helper plugin - please check the notifications with this plugin prior to following these instructions.
No email notifications are being received by anyone
- Ensure you've properly configured an SMTP Server. Send a Test Mail inside the SMTP Server configuration setup screen. Make a note of any error that is returned from the test.
- Check your JIRA application log files and the application server log files for Out of Memory errors. Typically, the log file will show java.lang.OutOfMemoryError: Java heap space. This has been known to cause the service responsible for sending emails out to fail until JIRA applications are restarted. You should further troubleshoot your memory issues using this guide.
- Check and ensure the Mail Queue Service is installed. Click Admininstration > Services to inspect that the service exists, and is set at a reasonable interval. This interval controls how frequently the mail queue is processed. You can flush the mail queue to send out pending messages immediately to your mail server.
- Inspect your Mail Queue under Administration > Mail Queue. See if you are given the option to Bypass currently sending mail. A stuck email or trackback ping can hold up the queue.
- Check that your Base URL is set to a domain / IP which your SMTP server will accept. Example: Google apps accounts must have a matching base url to their Google Apps domain.
Enable additional logging in Administration > System > Troubleshooting and Support > Logging and Profiling by setting the following to
DEBUG to see more robust logging about services running at the background:
Email notifications are not being received by a specific group of people/person
- Check if the My Changes option in the user's profile is Notify Me. The default value for this property for all users can also be set under Administration > User Defaults
- Check the project permissions under the project's permission scheme. Users must have Browse Project permission for the project to which the issue belongs. If you're using Issue Security Levels, ensure they are members of any Issue security levels that have been applied to the issue.
- Inspect the Mail Queue under Administration > Mail Queue and see if notifications are being queued. You can adjust the Mail Queue Service interval to a longer period for troubleshooting purposes. Inspect the Error Queue tab for any errors.
Notifications aren't occurring after clicking through a transition/workflow step
- Notifications are triggered in a transition by their post-function.
- Inspect the post-function of the transition step you're investigating and ensure it's firing an event.
- Inspect your notification scheme and check that the event Work Started On Issue actually has people mapped there.
- Ensure the notification scheme you just checked is actually assigned to your project.
The content of the email notification is wrong
- If the content of the notification refers to an invalid or non-existent issue, then the notification may be coming from another source. This situation can happen when you restore a XML backup of your production JIRA application instance into a development/test server. The development/test JIRA server application then begins sending out notifications in addition with your production instance. Please see this guide on Disabling email sending/receiving for a Development/Test JIRA instance.
- If users are receiving messages in HTML or Text and they wish to change this preference, have them change this property in their user profile under Outgoing email format.
- If the URL links inside the content of the notification points to the wrong site, check your base URL property under Administration > General Configuration.
- If the FROM: header of the mail being received is not what you've configured under Administration > General Configuration > Email from, check to see if the Project's Mail Project setting is set. It will override the global setting.
Issues created from e-mail do not generate notifications
- Please check your mail handler configuration and ensure that notifyusers is set in the handler parameters.
- Ensure that the User Preference for "Notify users of their own changes?" is set to YES in Administration > Users > User Preferences.
Comments created from e-mail do not generate notifications
- When JIRA applications process mail to add comments, if an attachment is included in the email it will fire an Issue Updated event instead of an Issue Commented event.
- Check to see if the Issue Updated event is notifying the expected recipients. If it is not, add those recipients to the notification scheme.
Duplicate notification emails are being sent from JIRA applications
- (JIRA 4.4.4+ only): Enable the Outgoing Mail log and the Incoming Mail Log in Administration > System > Troubleshooting and Support > Logging and Profiling.
Please ensure that the Debugging mode is ON
Remember to disable these once the problem is resolved as they can increase the overhead on server hosting, potentially cause degradation to performance and also consuming HDD space.
- (Pre JIRA 4.4.4): Set-Dmail.debug=true and restart JIRA.
- Check the
atlassian-jira.log(pre 4.4.4) to see if any SMTP timeouts are occurring, as in our Read timed out error when sending outbound mail from JIRA applications KB article. JIRA applications may be successfully communicating with the mail server and sending the email and then timeouts while waiting for the response. As it does not receive the success response from the SMTP, it will attempt to resend mails until it receives it.
- If you have any third-party mail plugins, please disable them and retest the behaviour to see if the problem can be isolated further.
- Check whether you are watching the issue and one of the role of the issue at the same time. You might need to check whether autowatch is currently turned on.
- Check the notification scheme to see if it contains a mailing list - if it uses a mailing list and another notification item such as Assignee, and the assignee is also within the mailing list, JIRA applications are not able to identify the users of the mailing list and will end up sending duplicate notifications.
Large mails are getting stuck in the mail queue.
- By default JIRA applications have no limit on the size of text fields. This can mean enormous comments and descriptions can be constructed, causing performance problems and mail to fail to send.
- The jira.text.field.character.limit value can be set as per Configuring Advanced Settings, allowing the comment sizes to be limited. This can effectively workaround the problem.
General Troubleshooting Tips
- Reviewing your JIRA application logs will greatly help you narrow down the problem. Often, the problem exists in the mail server and a Google search of the error from the logs can help you identify the cause.
- The Mail Queue (under Administration > Mail Queue) can give you a general idea of how many emails are being generated.
- You can get more detailed logging under Administration -> System -> Logging & Profiling. Click Edit next to the com.atlassian package and change it from the WARN logging level to DEBUG. This change does not persist after a restart.
- For even more detailed logging (display the message headers, protocol details), see Logging email protocols.