Customizing email content
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:
In the upper-right corner of the screen, select Administration
> System. Under Mail, select Email templates.
- Download .zip: Download a ZIP archive with all available templates and edit them locally.
- 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
- 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-batchApplying 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:
Jira copies the default templates from its resources to the Jira shared home directory.
The default templates overwrite any existing templates in
<Jira-shared-home>/data/templates.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/emailBatched issue notifications:
<Jira-shared-home>/data/templates/email-batch
Default templates
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.