Customizing Email Content

JIRA generates emails in reaction to events using a templating engine. The templating engine is Apache's Velocity. This is a relatively easy to use templating language that can pull apart java objects in useful ways. The mails are generated inside JIRA by invoking Velocity with a set of objects of relevance to the event.

(info) Please Note:

  • To change the columns in your filter subscriptions, you don't need to customize the mail templates. See Customizing your Issue Navigator.
  • There's a feature request to improve this at JRA-7266, which you can vote on to improve its chances of being implemented.
  • Bear in mind that the next time you upgrade JIRA – or need a new installation for any reason – you will have to manually copy any changes you have made to Velocity templates (as well as JSPs) into the new installation of JIRA. 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).

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

Email template locations

To customize email content, please follow this procedure.

  1. Open up your JIRA distribution, and navigate to the following paths:
    • The WEB-INF/classes/templates/email/ of the <jira-application-dir> in your JIRA Installation Directory.
    • The jira/src/etc/java/templates/email/ in your extracted JIRA source directory.
  2. Under this directory there are three directories: html, text and subject. The html subdirectory contains the templates used to create emails in html, while the text directory the plain text mail outs. The subject directory contains the templates used to generate the subject of the emails. The templates are named after the event that will trigger the email.
  3. Bring the template up in your favorite text editor. Referring to the JIRA template documentation (particularly Velocity Context for Email Templates) and Velocity Users Guide, make the customizations you want.
  4. Restart JIRA.

For new email templates:

  1. Create your new mytemplate.vm files in the html, text 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.

Note that since JIRA 4.1 each new template has to have a corresponding file in the subject directory.

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.

Was this helpful?

Thanks for your feedback!

41 Archived comments

  1. User avatar

    Nancy Belser

    It appears that the "event" is no longer included in the subject line for any emails. It looks like it is now in the "from" line.  Now every email for a particular issue has the same subject, which defeats the purpose of the subject line.  I really DO NOT want to go and edit every single subject velocity template to add this back in.  My users set up outlook email rules to look for particular subjects and that will no longer work and you can't search the "From" for anything besides user name.  I do not understand why this change was made.

    18 Aug 2011
  2. User avatar

    Anonymous

    I agree with you, it was more handy in the previous version...

    27 Aug 2011
  3. User avatar

    Anonymous

    Me too!! What is the alternative now.My email notification which was working in 4.0 is not working in 4.2 anymore.

    29 Aug 2011
  4. User avatar

    Anonymous

    This must clearly be a bug in the 4.4. instance of Jira!

    Having the type of notification in the FROM field is just plain stupid, and utterly useless. It breaks the automated notification/sorting that we have set up here also. 

    I think I'll have to look for the bug report form.... 

    29 Aug 2011
  5. User avatar

    Anonymous

    It also looks like the issues is not going away now, from ones components, they are still visible after they are resolved or closed, and the field which should say resolved and/or close, is not updated.

    And I also got a HTTP 404 error now, when we are trying to comment on issues.

    29 Aug 2011
  6. User avatar

    Anonymous

    Change of APi's should not be done when the update is done.All APi's must be backward compatible.This is simply leaving us with lot of code change now.

    03 Sep 2011
  7. User avatar

    Anonymous

    I have created a support case for the event showing up in the "from" and the only answer I am getting is that this change was made to fix a bug in gmail notifications and that Atlassian will not provide any guidance on how to remove the event as that would involve customizing the instance.  I do not think this is an acceptable answer.

    05 Sep 2011
  8. User avatar

    Anonymous

    Here is  Jira feature request created as a result of my support issue https://jira.atlassian.com/browse/JRA-25591

    Please vote on this if you find the new format inconvenient.

    06 Sep 2011
  9. User avatar

    John Dee

    So, is there any way to roll this back? I'm not seeing any way to really do that.

    23 Sep 2011
  10. User avatar

    Andreas Gounaris

    I've upgraded to JIRA 5.1.6 and want to customize email templates (just the header).

    Everything goes well except the deployment without restart. It never worked for me, changed the velocity.properties file according to your instructions.

    In fact, these instructions are in the document and the new lines where there, ready to be uncommented. Of course, I commented out the original cache line above.

    Nothing happens. I have to restart the server everytime I want to see my changes. It's overwhelming.

    17 Oct 2012
    1. User avatar

      Mike Beeson

      I also found this. There appears to be a missing part to the documentation. I got it to work by making a further change to the velocity.properties file:

      a) Comment out the line 'class.resource.loader.class=org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader'

      b) Add a new line 'class.resource.loader.class=org.apache.velocity.runtime.resource.loader.FileResourceLoader'

      From what I gather reading the Velocity documentation, the 'normal' resource loader has a caching mechanism that has an infinite timeout, so the file resource loader is needed instead.

      28 Aug 2013
  11. User avatar

    Anonymous

    I would love have additional X-headers like

    X-Issue ($issue.key)

    X-Jira-Author: ${fullname}

    or similar to better filter emails

    24 Oct 2012
    1. User avatar

      Anonymous

      JEMH as an X-Header Field Processor that supports exactly that, eg 'X-JEMH-priority: critical' etc.

      25 Oct 2012
  12. User avatar

    Anonymous

    How can I as a user stop all email and watch them on my dashboard?

    26 Mar 2013
  13. User avatar

    Anonymous

     

    Makes sense that the Subject should have been changed to move the workflow event name (Assigned, etc.) after the id of the issue.   Putting it first (as it was in the older versions) prevented logical sorting of emails by Issue ID.  Instead,  the emails were all organized by Event name then JIRA/Issue ID.  That was messy.  

    We do need the event name back in the Subject of all of the workflow notifications.....just AFTER the Jira/Issue ID number.

    01 Apr 2013
  14. User avatar

    Omar Shehab

    What language is used in defining these templates i.e. the .vm files? For example in filtersubscription.vm there is probably a variable called searchRequest.getName(). Is there any documentation what all these objects and their attributes?

    27 Jun 2013
  15. User avatar

    Anonymous

    this feature is available in jira on demand environment? I try to customize email template, any suggestions?rting

    03 Jul 2013
    1. User avatar

      Justin Alex [Design Industries]

      JIRA OnDemand does not allow customizations of their interface via source files customization. This has been outlined in their Restricted Functions in Atlassian OnDemand page.

      15 Jul 2013
  16. User avatar

    Anonymous

    is it possible to extract the issue list of a project periodically in the form of a excel sheet and mail this  list to set of email-ids?

    22 Jul 2013
  17. User avatar

    Harry Kha

    The default format for email notifications isn't coming through the same way any more. I haven't made any customisations and the .vm files have not been altered. The only thing that has changed is that I removed some states in my workflow but I can't understand how that would have changed anything. Any help would be appreciated.

    06 Aug 2013
    1. User avatar

      Matt Doar [ServiceRocket]

      Are you using OnDemand? New versions there changed the email templates recently

      06 Aug 2013
      1. User avatar

        Harry Kha

        Hi Matt,

        I'm actually running a trial version on my local. I was running version 5.1 but have since upgraded to the latest version, tested to see if that would resolve the problem but it is still missing all the HTML markers. I haven't changed anything in my mail client either so I should be getting the correct format but it's just coming through in plain text now. Any ideas?

        07 Aug 2013
        1. User avatar

          Matt Doar [ServiceRocket]

          Some email clients won't show the images until you explicitly choose to see them?

          07 Aug 2013
          1. User avatar

            Harry Kha

            I'll keep digging to try and fix it. Thanks

            08 Aug 2013
  18. User avatar

    Marcus Silveira [Atlassian]

    In order to customize the space after the information frame on the new mail template of JIRA 6 to include other fields like assignee, reporter, duedate and status, you'd need to edit the vm file associated to the desired event (e.g. atlassian-jira\WEB-INF\classes\templates\email\html\issuescommented.vm) and add the following

    28 Nov 2013
    1. User avatar

      Tini Good

      What if you want to include a custom field?  Do you use the field name, or field ID?  Can you provide an example?

       

      25 Mar 2014
  19. User avatar

    Roel Van de Paar

    Is there any plugin that allows email customization without hacking?

    01 Jan 2014
    1. User avatar

      Andy Brook [The Plugin People]

      You probably need to reword that, if by 'hacking' you mean a complete UI drag drop abstraction from the underlying template language, no.  There are several addons that expose the Templates used with various deployment twists, one free, two commercial.  You will need to know velocity markup in order to understand / extend, current JIRA templates make things a bit simpler, when all you want to do is add some additional custom fields etc.

       

      02 Jan 2014
      1. User avatar

        Roel Van de Paar

        Hi Andy, Thanks. Hacking to me meant having to edit files on disk (now + on upgrades). Found another one

        03 Jan 2014
  20. User avatar

    Beat Schnyder

    Is there an easy way to remove all external content (icons) from all templates? They can't be displayed in my case because of security restrictions.

    22 Jan 2014
    1. User avatar

      Andy Brook [The Plugin People]

      Just use text notifications to remove any rich(er) content?  Removing all references to icons may be a challenge.  JIRA may also inject a few inline.  Is your problem with icons loading external URL resources, or strictly 'any' images?

      22 Jan 2014
      1. User avatar

        Beat Schnyder

        Hi Andy, thanks for your reply. It's all external content, that can't be displayed (currently avatar, action and issue type icons, logo). Loading of external content in emails is not in line with our security policy... I guess we'll have to switch to text then.

        23 Jan 2014
        1. User avatar

          Nathon Fowlie

          In respect to images it'd be good if the way the HTML templates were slightly modified to base64 encode the image data and embed it directly into the message content.

          This way you wouldn't have to expose your JIRA instance in order for images to load outside the company network. It would also mean MS Outlook would automatically display the images instead of providing the prompt to load external resources.

          25 Mar 2014
          1. User avatar

            Anonymous

            I think JIRA 6.1+ will already do inlining.  Its done as a post process after HTML template rendering.

            25 Mar 2014
  21. User avatar

    kris

    Half our users are having fits over the HTML email notifications (the other half love it of course).  Is there any way to stop all those images/icons from attaching to the tickets?  We have tickets ending up with multiple avatar attachments, or the little conversation bubble, each time a user relies to a notification.

    03 May 2014
    1. User avatar

      Andy Brook [The Plugin People]

      Not by default, you'll need to write your own mail handler or use one that already does this like JEMH which has attachment blacklisting (you upload image files etc, they get hashed and never added again).  Current releases maintain internal lists of the hashes to do this automatically.

      04 May 2014
  22. User avatar

    mouhcine aitounejjar

    For some reason, the changes I make to the file "WEB-INF/classes/templates/email/macros.vm" doesn't have any effect at all on the notification emails, even if let's say, I wrote random stuff in a specific macro in this file. 

    My "velocity.properties" files is correctly set to auto-reload templates without restarting the JIRA server.

    Anybody got an idea ? I thank you in advance for it !

    20 Oct 2014
  23. User avatar

    Srinivas

    Can we customize email templates to add labels of the issue?

    06 Jul 2015
  24. User avatar

    Adam Sully

    Are there any plans to implement this within the Filter Subscription screen or any other screens? If developer resources are limited, we can't be going and pulling velocity templates every time management would like a different field present in a subscription filter. Pushing this customization to such a deep part of the JIRA infrastructure limits its usefulness. 

    22 Jul 2015
  25. User avatar

    Larry Dillard

    We too would like to have the ability to add custom text to a subscription so we can let those receiving know what to do.  While I know in the code world nothing is simple, but this seems to be simple.  One text field for a "positive" result message, one text field for null result message .

    27 Jul 2015
  26. User avatar

    stephen stephen

    I want to add the date that an issue is created to the emails that go out to developers. Can anyone help with the syntax on doing that?

    It looks like the $issue class has a function getCreated()...I'm just not sure how to add that into the email.

     

     

    06 Aug 2015
Powered by Confluence and Scroll Viewport