Configuring email notifications

Jira can send email notifications to users when significant events occur. For example, you can get notified when an issue is created or completed, or when any of the issue fields is updated.

Enabling notifications

To start the notifications flowing, you'll need to set up an SMTP mail server, and create a notification scheme in which you choose the notifications you'd like to get.

1. Configure Jira's SMTP mail server
2. Create a notification scheme

You can also customize your email content, and configure the email address from which notifications are sent.

How notifications work

Notifications for events that occur close together are grouped and sent in a summary email, just to avoid too many emails cluttering your mailbox. We're calling these notifications batched notifications, as opposed to separate notifications (where every notification is sent in a separate email) that were the default notifications in earlier Jira versions.

An email with batched notifications looks like the one below. As you can see, it groups all events from the last few minutes and presents them as a summary.

Issue updates

When it comes to notifications about issue updates, you will receive a separate email for every issue. The email contains events that occurred in an issue in the specified time frame (for example, the last hour), and includes the following updates:

• Details about the issue (if it was just created)
• Changes to any of the issue fields (including custom fields)
• Comments
• Work logs
• Attachments
• Mentions

You can change the frequency of batching these notifications. Depending on your choice, you’ll receive an email with events from the last few minutes or an hour. 

Mentions

When you're mentioned in an issue, it usually means that somebody needs your immediate attention. To avoid sending too many emails, a mention will be included in the email with other issue updates, but it will trigger this email to be sent as soon as possible (regardless of the frequency you've chosen). 

Customer notifications in Jira Service Management

Jira Service Management has an additional set of notifications, which we call customer notifications. These notifications are designed to keep the customers informed about progress on particular tickets without disclosing information about internal processes, and usually include responses to customers, customer-visible changes, approvals, or requests being shared with individuals or organizations. You can read more about them in Managing Jira Service Management notifications.

These notifications are not batched, and you can’t choose the frequency of sending them — every notification is sent in a separate email after an event occurs.

Advanced: Adding more custom fields

Updates to custom fields in your issues are included in the notifications, just like regular fields. However, if you’re an advanced Jira user, you can display additional custom fields in your emails. Such custom fields can be added to email’s subject, header, or any other location. Some of our users do this to describe their notifications more precisely, for example by adding security levels. For more info, see Adding custom fields to emails.

Changing the notification frequency

Every team works in a different way, so we’re giving you a way to tailor the notifications to your needs. If you like to always stay on top of things, you can receive batched notifications every few minutes (2 minutes being the minimum), and if you’d rather just read a summary every now and then, you can choose to receive a summary of what happened in the last hour.

To change the frequency:

1. Go to Administration () > System > Batching email notifications (you can also search for it by pressing 'gg').
2. Choose the frequency that works for you, and click Save. These settings will be applied to all users.

Disabling batched notifications

If you absolutely love to know what’s going on in your projects, you can also disable batched notifications and get notified about every event (for example, change of status or any of the fields) in a separate email. You can choose to do this if you simply got used to separate notifications that were the default notifications before Jira 8.4.

To disable batched notifications:

1. Go to Administration () > System > Batching email notifications (you can also search for it by pressing 'gg').
2. Select Disabled, and click Save. These settings will be applied to all users.

Customizing email content

Email notifications are based on Apache’s Velocity templates. Whether it’s adding some info to the header or footer, or shuffling around the contents of your emails, you can make a number of customizations to the templates and tailor the emails to your needs.

For more info, see Customizing email content.

Configuring a project's email address 

You can configure an email address for your project, which will work as the address that notifications are sent from - the ‘sender address’. This email address will also serve as the reply address for responses.

To configure a project’s email address:

1. Choose Administration () > Projects, and select a project.
2. Locate the Notifications section, and click the pen icon next to the email address.
   
   
   
   
3. Enter a valid email address, and click Update.

Notifications about issues from this project will now be sent from the new email address. If you ever wanted to change it back to the default address from your SMTP server, complete the same steps but leave the email address blank.

Email recipients

For each notification, Jira will only send the first encountered email intended for a recipient. Hence, in the case where a user is included in two or more recipient lists (e.g. the Project Lead and current reporter) for one event notification, the user will only receive the first encountered email notification. Jira will log the fact that this user was on multiple recipient lists.

Jira can send email notifications to users when significant events occur, (e.g. creation of an issue; completion of an issue).

Note: For all of the following procedures, you must be logged in as a user with the Jira Administrators  global permission.

Email format: HTML or text

Each Jira user can specify in their profile preferences, whether to send outgoing emails in either text or HTML format. Jira Administrators can specify a default email format by going to Administration () > User Management > User Preferences.

The HTML email format can accommodate internationalized words in the 'Issue Details' section. However, due to Internet Security Settings, which prevent images from being automatically downloaded, the HTML email messages may not be correctly formatted. For example, the summary column on the left may appear too wide. You can correct the formatting by accepting to download these images (this option should be available in the email). 

Troubleshooting notifications

Using the Jira admin helper

The Jira admin helper can help you diagnose why a user isn't receiving email notifications when they should be, or why a user is receiving email notifications when they shouldn't be. This tool is only available to Jira administrators.

To diagnose why a user is or is not receiving notifications for an issue:

1. View the issue in Jira.
2. Click Admin > Notification Helper.
3. Enter the username of the user.
4. Click Submit.