Customizing email content (separate notifications)

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

When using separate notifications, every issue update is sent in a separate email. Templates that control how notifications look are in the Jira installation directory.

Customizations to Velocity templates or other Jira files are not included in the scope of Atlassian Support.

Good to know

  • Any changes to Velocity templates (as well as JSPs) will be overwritten following a Jira upgrade. In such a case, you will need to manually copy your modified files to the new Jira version. If the Velocity templates and/or JSPs have changed in the newer version, you will have to manually port your customizations into them (as opposed to copying these files directly over from your old Jira installation to your upgraded one).

  • Apart from modifying how your emails look, you can also add extra custom fields to describe the issues you're being notified about more precisely. For more info, see Adding custom fields to emails.

Email template locations

  1. Go to the following location in your Jira installation directory: 

    /atlassian-jira/WEB-INF/classes/templates/email/

    If you're using Jira sources files, go to jira/src/etc/java/templates/email/ instead.

  2. Under this directory, there are three subdirectories:

    • html - contains the templates used to create emails in html
    • text - contains the templates used to create plain text mail outs
    • subject - contains the templates used to generate the subject of the emails
  3. Bring the template up in your favorite text editor. Refer to the the Jira template documentation and Velocity Users Guide to make the customizations you want.
  4. Restart Jira.

Creating new email templates

  1. Create your new mytemplate.vm files in the htmltext and subject directories, based on the existing files in those directories
  2. Add the templates to atlassian-jira/WEB-INF/classes/email-template-id-mappings.xml to make them valid choices for when you are adding a new event.

Advanced customization

The Issue object is passed into the vm templates. Notice some of its implementation in /includes/summary-topleft.vm. As an example, calling $issue.getProject() would allow you to determine the project an issue comes from, and even create logic to show different information for emails from different projects.

Deploying Velocity templates without restarting Jira

In a development instance, you can play with picking up velocity file changes without a restart.
From <jira-install>/atlassian-jira/WEB-INF/classes/velocity.properties:

  1. Change class.resource.loader.cache from true to false
  2. Remove the comment sign (#) from #velocimacro.library.autoreload=true

Making this change in production will eventually lead to Jira not serving pages along with the 'ran out of parsers' error in the log file.

See also Adding Custom Fields to Email.

Last modified on Oct 8, 2020

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.