Customizing email content

This page is for Jira Data Center

If you’re using Jira Server, you’ll need to retrieve your templates in a different way than described here. Learn how to customize email content in Jira Server

Jira offers a range of default templates that you can use for different interactions. 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 and tailor the emails to your needs. Learn more about different types of notifications

How email templates are set up in Jira

Jira generates emails in response to events using a templating engine called Apache’s Velocity. This is a templating language that can pull apart Java objects in a number of ways.

Read more about Velocity templates in the Jira developer documentation

Customizations to Velocity templates or other Jira files aren’t included in the scope of Atlassian Support. Check out Atlassian Support Offerings 

Viewing your email templates

For all of the following procedures, you must be logged in as a user with the Jira system administrator global permissions.

To view and customize Jira email templates:

  1. In the upper-right corner of the screen, select Administration  > System

  2. Under Mail, select Email templates.

  1. Download .zip: Download a ZIP archive with all available templates and edit them locally.
  2. Upload: Once you’re done editing, upload the archive back to Jira. It needs to have the same .zipe file structure as the original archive. Check out the required file structure
  3. Revert to default: If there are problems with your uploaded templates, revert them to default ones. Jira will copy the default templates from its resources to your Jira shared home directory.

Editing your email templates

Editing email templates allows you to change the look and feel of your email notifications. This comes in handy if you’re looking to add your company branding or reorganize the content.

When editing the template, you’ll be using the Velocity templating language, and some knowledge of it will be essential.

Use these guides to learn about different email templates in Jira and their customization:

Uploading the templates

You’ll need to archive the templates into a ZIP archive and upload it back to Jira. 

Required file structure

When editing the templates, you shouldn’t change their filenames or location within the folder, as Jira will validate the file structure. You can add extra files to the archive, like graphics, and link them from your templates.

Jira only checks if the required templates exist. The syntax or any errors in your templates won't be validated.

The following file structure will be accepted. Alternatively, you can omit the templates folder:

- templates
    - email
    - email-batch

Applying the changes

After uploading the templates, they won’t be applied right away. Jira will first validate the file structure, and then ask you to apply the changes if everything looks right. Once you do it, the new templates will be moved to <Jira-shared-home>/data/templates, overwriting whatever exists there.

Reverting templates to default

If something isn't right with your modified templates, you can bring the default ones by clicking Revert to default. Here's what happens when you do it:

  1. Jira copies the default templates from its resources to the Jira shared home directory.

  2. The default templates overwrite any existing templates in <Jira-shared-home>/data/templates.

  3. Jira clears the template cache so the default templates are applied right away.

Good to know

Here is some other information that you might find useful.

Templates: Default vs. current

Current templates

Current templates are templates that Jira is using for email notifications. They are stored in your Jira shared home directory and are updated every time you upload a new ZIP archive and apply the changes.

  • Separate issue notifications and other events: <Jira-shared-home>/data/templates/email

  • Batched issue notifications: <Jira-shared-home>/data/templates/email-batch

Default templates

tip/resting Created with Sketch.

Because of how default templates work, we recommend against modifying them so Jira always has something to revert or fall back to.

Default templates are backup templates that are stored in the Jira resources, either in the installation directory (separate issue notifications and other events) or in one of the apps (batched issue notifications).

These templates work as backups and will only be used in these cases:

  • Missing files: One of the templates is missing in your Jira shared home directory. For this template, Jira will fall back to the default one.

  • Revert to default: You chose to revert your templates to default. Default templates will be copied to your shared home directory, overwriting the current templates.

Changes retained on upgrade

Since email templates are stored in your Jira shared home directory, any changes you make will be retained on upgrade. Also, you don’t have to restart Jira after editing the templates.

Caching email templates

All templates in the Jira shared home directory are cached. Thanks to that, Jira can use these templates even if the shared directory isn’t accessible.

We don’t cache information about missing files — if one of the templates is missing from the shared directory, Jira will try to read it every time and will fall back to the default template.

Last modified on Oct 12, 2023

Was this helpful?

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