nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

[Jira 10.x] Images/icon and CSS styles not rendering in custom Velocity (.vm) email templates

Pratik Lodha_otwj1m

Hello Atlassian Community,

I am currently working on custom email notifications in Jira 10.3.5 using Velocity (.vm) templates. I am parsing some of the standard Jira email templates alongside my own custom wrappers, but I am running into rendering issues when the emails are actually delivered to the inbox.

Specifically, I am facing two distinct issues:

1. CSS Styles are Dropped or Ignored Any custom CSS classes I apply do not seem to render in the final email. Does Jira 10.x require strict inline CSS, or is there a specific standard stylesheet I should be parsing to inherit formatting?

2. Images are Broken or Blocked

Check comment logo
Check user logo.

Please check the attached screenshots for reference showing the previously working version and the current failed version.

Any advice or best practices would be greatly appreciated!

Previous (v9.4.14)

Screenshot 2026-06-08 174842.png

Current ( v10.3.19)

Screenshot 2026-06-08 174943.png

Accepted answers

All comments

Artem Nek_Votazz

Hi @Pratik Lodha

A few things changed in Jira 10.0 around email/Velocity that could be behind
this — worth checking which one applies rather than assuming. Here's where I'd
look first.

The most likely candidate is the new Velocity allowlists introduced in Jira 10.0
(the main difference from 9.4.14):
• a file / file-type allowlist — custom .vm templates only render if allowlisted
(resource.loader.file.allowlist, file.resource.loader.filetype.allowlist)
• a method allowlist — method calls inside a template that aren't allowlisted get
blocked and logged

If that's what's happening, your custom wrappers and the helpers they call (the
CSS inliner and the image helpers) would be getting silently blocked — which would
fit both of your symptoms.

To confirm rather than guess, set:
atlassian.velocity.method.allowlist.debug=true
It keeps enforcement off but logs every blocked template/method, so the log names
the exact .vm files and calls involved. If you can run that and share what it logs
(or the related warnings in atlassian-jira.log), it'd point straight at the cause.

On your two questions:

1) CSS — mail clients strip <style>/class CSS, so it generally needs to be inlined.
Jira does this via Botocss, but it's opt-in: BotocssMailUtility#applyStyles (or
Botocss#inject), or inline styles directly. If you were relying on classes, that
could be why they drop — and if BotocssMailUtility isn't allowlisted on 10.x, the
inlining step may not run at all. Also worth knowing: the template structure
changed in 10.x — header.vm has different semantics now (actor details moved out
of the chrome), so #defaultMailHeader() is preferred over parsing header.vm
directly; footer.vm is unchanged.

2) Images — embedding logos as cid: (attached / Content-ID), or bundling the
graphics into the template archive, tends to be more reliable than URLs that need
a live Jira session (those often break in mail clients). It's also worth checking
whether the image macros are being caught by the method allowlist — same debug
flag.

If you can share a snippet of your custom wrapper plus whatever the debug log
shows, it'd be much easier to pin down which of these is actually biting you.

Docs:
• JIRA email template changes:
https://developer.atlassian.com/server/jira/platform/jira-email-template-changes/
• Velocity file allowlist:
https://developer.atlassian.com/server/framework/atlassian-sdk/velocity-file-allowlist/
• Velocity method allowlist:
https://developer.atlassian.com/server/framework/atlassian-sdk/configuring-the-velocity-allowlist/

Pratik Lodha_otwj1m

#disable_html_escaping()
#parse("templates/email/html/includes/emailconstants.vm")

#set ($issueLink = "")
#if ($issue)
#set ($issueType = $issue.getIssueType())
#set ($issueLink ="<a href='${baseurl}/browse/${issue.getKey()}'>#renderIssueTypeIcon(${issueType}) $xmlutils.escape($issue.getKey())</a>")
#end

#if ($author)
#set($actionerUser = $author)
#set ($authorLink = "#authorlinkname($author.name $linkstyle)")
#else
#set($actionerUser = $remoteUser)
#set ($authorLink = "#authorlinkname($remoteUser.name $linkstyle)")
#end

#set($headerTitle = $authorLink + "<strong>triggered</strong>" + " action ")
#parse("templates/email/html/includes/header.vm")

#set ($issueTitleBody="#parse('templates/email/html/includes/patterns/issue-title.vm')")
#rowWrapperNormal($issueTitleBody)

#rowWrapperNormalBegin('' 'wrapper-special-margin')
<table class="keyvalue-table">
<tr>
<th>Notification message:</th>
</tr>
<tr>
<td>$message</td>
</tr>
</table>

<hr>

#parse("com/nc/jira/custom/automation/rule/templates/custom-email-notification-fields-template.vm")

#rowWrapperNormalEnd()

#if($includeDescription)
#if ($issue.description)
#set($textParagraph = $issue.htmlDescription)
#rowWrapperNormal("#parse('templates/email/html/includes/patterns/text-paragraph.vm')", '', 'issue-description-container')
#end
#end

#set ($commentActionBody="#parse('templates/email/html/includes/patterns/comment-action.vm')")
#rowWrapperNormal($commentActionBody)
#parse("templates/email/html/includes/footer.vm")

Pratik Lodha_otwj1m

// Second File

#disable_html_escaping()
<table class="keyvalue-table">
#foreach($field in $templateFields)
#if($field.id == ("issuekey"))
#parse("templates/email/html/includes/fields/issuekey.vm")
#elseif($field.id == ("issuetype"))
#parse("templates/email/html/includes/fields/issuetype.vm")
#elseif($field.id == ("status"))
#parse("templates/email/html/includes/fields/status.vm")
#elseif($field.id == ("priority"))
#parse("templates/email/html/includes/fields/priority.vm")
#elseif($field.id == ("environment"))
#parse("templates/email/html/includes/fields/environment.vm")
#elseif($field.id == ("labels"))
#parse("templates/email/html/includes/fields/labels.vm")
#elseif($field.id == ("assignee"))
#parse("templates/email/html/includes/fields/assignee.vm")
#elseif($field.id == ("reporter"))
#parse("templates/email/html/includes/fields/reporter.vm")
#elseif($field.id == ("components"))
#parse("templates/email/html/includes/fields/components.vm")
#elseif($field.id == ("versions"))
#parse("templates/email/html/includes/fields/affectsversions.vm")
#elseif($field.id == ("fixVersions"))
#parse("templates/email/html/includes/fields/fixversions.vm")
#else
<tr>
<th>$field.name:</th>
<td>$field.value</td>
</tr>
#end
#end
</table>

Artem Nek_Votazz

@Pratik Lodha Thank you for the logs.

After digging into the 10.x specifics, I'd actually steer you away from the
Velocity allowlists as the cause on 10.3.5 — they probably aren't it here:

• The file allowlist only applies to .vm files loaded from the filesystem. If your
com/netcracker/... template is bundled inside the plugin JAR (which that path
suggests), the file allowlist doesn't touch it. If it's actually a loose file on
disk, then it would need allowlisting — worth confirming which it is.
• The method allowlist exists from 10.0, but on 10.3.x it runs in debug mode by
default: it logs non-allowlisted methods but doesn't block them. Enforcement
only turns on by default in 10.5. So on 10.3.5 your methods/macros are being
logged, not stripped.

So the more likely culprit is the template-structure + CSS changes between Jira 9
and 10. The stock templates and helper macros were reworked — header.vm has
different semantics now, and the chrome/row macros (#rowWrapperNormal, etc.) and
the email CSS changed. Your wrapper parses header.vm and leans on those macros and
on CSS classes (keyvalue-table, wrapper-special-margin, …), so if the stock pieces
you build on changed, both styling and layout would shift. Atlassian's migration
notes:
https://developer.atlassian.com/server/jira/platform/jira-email-template-changes/

On the two symptoms:
• CSS — email classes only show if Jira's CSS is inlined into the elements (mail
clients drop <style>/class CSS). That inlining is Botocss, and it's opt-in; if
the 9.x path that applied it changed, your classes come through bare and get
dropped.
• Icon — #renderIssueTypeIcon is what emits the issue-type icon, and how Jira
renders those has changed across versions, so that's the piece to inspect for
the broken image.

Quickest way to pin it: grab the raw HTML source of one delivered (broken) email
and check two things — are your classes still present but NOT converted into inline
style="…" (that's the CSS-inlining/Botocss issue), and what does the icon <img>
actually point at (a URL needing a Jira session vs a cid: attachment vs nothing).
Paste that and I can tell you which it is.

Igor Medeiros - Modus Create

Hi @Pratik Lodha

Adding to what Artem sent, custom Velocity templates tend to break exactly this way on major upgrades. Context objects and the CSS inliner shift between versions, and each upgrade means re-debugging the .vm files by hand.

If you would rather not maintain that layer yourself, our app Notification Assistant for Jira for Data Center keeps notification templates in a built-in editor. Recipients, JQL conditions, and layouts carry across upgrades without touching .vm files.

Feel free to reach out if you'd like to learn more.

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

jira

unknown-hosting-type

atlassian

jira-unknown-hosting-type