Customizing email content

Jira generates emails in reaction to events using a templating engine—Apache’s Velocity. This is a relatively easy to use templating language that can pull apart java objects in useful ways. 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.

Accessing your email templates

To access your email templates:

• Go to Administration > System > Email templates. You need to be a Jira System Administrator to complete any actions on this page.

1. Download: 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. The archive needs to have the same file structure as the original. See Required file structure below.

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. To see the list of all templates and their description, check:

• List of available email templates

Uploading the templates

You’ll need to archive the templates into a ZIP archive and upload it back to Jira. Here’s some things you’ll need:

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

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 plugins (batched issue notifications). It's what you would edit to customize your emails before Jira 8.14. 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.