keelapps/Mail Templates/Documentation
Mail Templates for Jira — documentation
Before you start
Mail Templates is an additional notification channel. Jira keeps sending whatever its own notification scheme is configured to send; this app adds a templated message on top, aimed at people who would otherwise receive nothing. It cannot suppress Jira's own mail — Forge gives apps no hook for that. Plan around that from the start, and see avoiding duplicate mail.
Turn it on for a project
You need to be a project administrator for that project, or a Jira administrator. The check runs as you, not as the app.
- Open the project, then Mail Templates in the project's tab bar (it may be under More).
- Pick one of the three event tabs and tick Send an email when…
- Write a subject and body, or press Start from an example to load a working template.
- Choose the recipients, then Save.
A project with no configuration sends nothing. Remove from this project deletes that project's rules entirely.
The three events
| Tab | Fires when |
|---|---|
| Issue created | a new issue is created in the project |
| Status changed | an edit moves the issue between statuses — other field edits are ignored |
| Comment added | a comment is added to an issue |
Each tab has its own subject, body, recipients and on/off switch. Turning one on has no effect on the others.
Template variables
Both the subject and the body interpolate these. Anything that is not a known
variable is left exactly as typed — so a typo shows up in the message as
{{isue.key}} rather than silently vanishing.
| Variable | Value |
|---|---|
{{issue.key}} | ENG-1234 |
{{issue.summary}} | the issue's summary line |
{{issue.status}} | current status name |
{{issue.issuetype}} | Bug, Task, Story… |
{{issue.priority}} | priority name |
{{issue.assignee}} | assignee display name |
{{issue.reporter}} | reporter display name |
{{issue.labels}} | comma-separated labels |
{{issue.duedate}} | due date |
{{issue.created}} | creation timestamp |
{{issue.updated}} | last update timestamp |
{{issue.url}} | link to the issue |
{{project.key}} | ENG |
{{project.name}} | Engineering |
{{actor.name}} | who triggered the event |
{{transition.from}} | previous status — status-change rules only |
{{transition.to}} | new status — status-change rules only |
{{comment.body}} | the comment text — comment rules only |
{{comment.author}} | who commented — comment rules only |
The body accepts a small markdown subset: **bold**,
*italic*, - bullets, #### headings and
[links](https://…). Anything else is sent as plain text. The preview
below the editor is rendered by the same code that sends the real message.
The app reads only the issue fields your template actually references. A template
that never mentions {{issue.priority}} causes no read of priority.
Recipients
Tick any combination of Reporter, Assignee, Watchers and Voters, and add named people or Jira groups under Specific people. The point of the app is that last part: a group or a fixed list that is not on the watcher list.
Everyone on the list still has to be able to see the issue. Jira drops recipients who cannot, so a rule can never widen who has access to what.
A rule that addresses nobody sends nothing and records Nobody to send to in the log.
Site settings and quotas
Jira administrators get a site page under Settings → Apps → Mail Templates for Jira. It carries a site-wide kill switch, hourly send limits per project and for the whole site, and the list of projects that have rules configured.
The limits exist because a bulk edit of five hundred issues is five hundred events. When a limit is reached the remaining events are recorded as Hourly limit reached rather than being sent.
Reading the send log
The Recent sends tab lists the most recent events for the project, whatever happened to them. An app that silently does nothing is the most confusing thing it can be, so every outcome is named.
| Result | Meaning |
|---|---|
| Sent | handed to Jira for delivery |
| Turned off | the rule, the project or the site switch was off when the event arrived |
| No matching rule | nothing was configured for that event type |
| Already sent | a duplicate delivery of the same event; one event, one email |
| Hourly limit reached | the project or site quota was exhausted for that hour |
| Nobody to send to | the rule addressed no one, or Jira dropped everyone for lack of access |
| No subscription | the site's subscription has lapsed — see below |
| Blocked by Jira | Jira refused the send; the detail column carries its reason |
| Failed | a transient error; these are retried |
If the subscription lapses, the app stops sending and records No subscription against each event. Mail goes out under your organisation's name and cannot be recalled, so this is the one thing the app refuses rather than assumes. Your configuration stays readable throughout.
Why did no email arrive?
Work down this list; the send log answers most of it.
- Is the rule on? Each event tab has its own tick box.
- Is the site switch on? Check the admin page.
- Did the event actually match? A status change needs a real status transition; editing a summary is not one.
- Can the recipient see the issue? Jira drops those who cannot — the log says Nobody to send to.
- Was the hourly limit hit? The log says so.
- Is the subscription active? The log says No subscription.
Delivery itself is Jira's. Once the log says Sent, the message is in Jira's notification pipeline and lands wherever that user's Jira notifications normally land.
Avoiding duplicate mail
Someone who is already notified by Jira's own scheme — a watcher, say — will get two messages: Jira's and yours. To stop that, switch the matching event off in the project's notification scheme in Jira.
Check what else uses that scheme first. Notification schemes are frequently shared between projects, and turning an event off affects all of them.
Permissions
The app asks for four things, and none of them can change your Jira data:
| Scope | What it is for |
|---|---|
read:jira-work | read the issue fields a template references, tell a status transition from any other edit, and check whether the caller is a project admin |
read:jira-user | resolve names for the recipient picker |
send:notification:jira | the only write permission, and it permits exactly one call: handing a message to Jira's notification service |
storage:app | rules, send log, quota counters, dedupe claims |
There is no external permission, so the app cannot reach any host
outside Atlassian — Forge enforces that at the platform level, not on our word.
What it will never do
These are deliberate and permanent. Each one would require either egress or permissions that this product exists to avoid:
- No attachments
- No custom sender address — mail comes from Jira
- No unsubscribe management
- No rich-text editor — the markdown subset above is the whole of it
- No suppressing or replacing Jira's own notifications