_Today’s blog is by guest author Chris Dunne, who writes for the [GetJirified](https://getjirified.com/) blog. The original post can be found [here](https://getjirified.com/customizing-jira-email-notifications-using-zapier-sparkpost/)._

## Creating Magic using webhooks with Zapier and SparkPost for email

[JIRA Service Desk is a great product](https://www.atlassian.com/software/jira/service-desk). It provides all the essential features to set up a fully functional business and customer friendly service desk. It is, like the rest of JIRA, quite flexible.  
But there is one area that I believe is seriously lacking in terms of flexibility. **Email Handling!**  
Whilst many users will prefer to login to the portal and raise requests, others will prefer to email. The majority will prefer to receive change notifications for requests by email too.  
The ‘Default’ Email Notifications feature is baked into JIRA Service Desk. This will send customers email notifications using Atlassian’s own built-in HTML email template.

But many JIRA Service Desk customers want to send these emails with their own branding, own look and feel, and customized data items in the body of the email.

The lack of ability to customize this essential function has been outstanding for a long time. Check out [JSD-218 – As an Admin I want to be able to customize the Service Desk notifications’ subject, content and format](https://jira.atlassian.com/browse/JSD-218)

Read through the 330+ comments and you can see there is a lot of frustration in the community with Atlassian’s lack of progress on this issue. Only recently Atlassian announced a slow rollout of features related to Email customization in a beta program for JIRA Cloud customers.

The comments do provide some workarounds using ScriptRunner and velocity template modifications but I wanted to see if I could come up with an alternative that didn’t involve add-ons.

Without further ado, let’s define the requirements. We would like to be able to do the following:

- **Send emails in response to events on issues in JSD.**
- **We want to be able to completely customize the look and feel of those emails.**
- **We want to be able to insert data from the issue into those emails.**
- **The emails should come from an email domain that the customer recognizes and won’t be blocked or treated as spam.**
- **Customers should be able to reply to these emails.**

In this article I will show you how you can do all of this in JIRA Service Desk (for both cloud and server versions). We will use a combination of JIRA’s webhooks, Zapier, and SparkPost.

## JIRA Email Notifications

So what are these email notifications that JSD / JIRA sends? They are emails, triggered by JIRA issue events that are sent to a defined set of recipients. The content of the email is defined in a template.

When we are dealing with JIRA Service Desk there are actually two flavours of email notifications.

- **JSD Customer Notifications.** These are the notifications that are baked into the JIRA Service Desk project. There is very little we can do to change the behaviour of these notifications, or customize the content. We cannot change the layout or content without cracking open the source code, and on Cloud this is not even an option.
- **JIRA User Notifications.** This is the traditional means of sending email notifications. Using notification schemes, we have the ability to define who receives the notifications for each type of event. But these email notifications are only sent to licensed JIRA users and not to JIRA Service Desk customers (free, and unlicensed). For the server instance we can also modify the Velocity templates used to control the layout and appearance of the emails.

Here are some examples of the out-of-the-box notifications; one is a standard JIRA Service Desk notification a customer would receive and the other is the type of notification received by licensed JIRA users.

The challenge for many Atlassian customers, and the challenge we set out to tackle in this article, is to provide a mechanism to change the content and branding of the emails, preferably without additional plugins.

## An Alternative Approach

We want to send customized emails in response to events in our primary system. When you think about it this sounds a lot like the function of transactional email systems like Mandrill and SparkPost.

These are normally used in e-commerce systems to send receipts and other automated replies. They provide users with the ability to trigger emails and define templates for the content of those emails.

So I thought – could we disable JIRA’s native notifications and instead use one of these transactional email systems.

To do that we need a means of sending a message to our transactional email system when an event of interest occurs in JIRA. **[JIRA has webhooks](https://confluence.atlassian.com/adminjiraserver071/managing-webhooks-802592245.html)** which can do exactly that. But we need something that would catch the webhook, parse the content, and trigger the sending of the email.

**[Zapier](https://zapier.com/)** has the capability to do this and is quite easy to set up.

Finally, we need to have something to actually send the email. There’s a bunch of candidates, but the new kid on the block is **[SparkPost](https://www.sparkpost.com/)** and I’ve decided for the purposes of this post to give it a try.

So the next step is to set up our accounts with Zapier and SparkPost.

## Zap it

Firstly lets set up the Zapier account we need and create the webhook we are going to use.

1.  Create your account on the [Zapier site here](https://zapier.com/sign-up/), and sign up for a free plan.
2.  Click **Make a Zap** and then select **Choose App** under trigger. Type Webhook and select the result.
3.  Select the **Catch Hook** option and then click the **Save + Continue** button.
4.  On the next screen select **Continue**. A custom webhook URL is generated. This is the webhook that JIRA will use to trigger the Zap. Click the **Copy to Clipboard** button.
5.  Click **OK, I did this** button and keep this window open. Zapier is waiting to intercept this webhook. So we need to open another window and set up the webhook in JIRA.
6.  Go to **JIRA->Admin->System->Webhooks** and configure the webhook.
7.  Give the Webhook a name.
8.  Paste the URL copied to the clipboard in step 4 into the **URL** field.
9.  Select the events that will trigger this webhook. We will select the **Issue Created** and the **Issue Updated** event.
10. Click the **Save** button.
11. Now create an issue in any project and switch back to your Zapier browser window. Zapier should detect the webhook. You can click the **view your hook** link to see the actual data sent.

> _Note: In part 2 of this article we will further customize this to fire events from our workflow, restrict the issues we are interested in using JQL, and create webhooks for other events._

Here’s a screencast showing you what to do.

<iframe src="https://www.youtube.com/embed/0ExPlnzTqec?feature=oembed"></iframe>

So we have JIRA talking to Zapier and sending the details of events as JSON.

But this is only half the story. We can’t complete the full Zapier definition yet as we need to also configure SparkPost.

## Spark it

Now we are going to set up our email system using SparkPost. We just want to test a very basic scenario and ensure that we can send an email with some data from our JIRA issue created/updated event.

So first we need an account and then an email template.

**Setting up a SparkPost Account and Linking it to Zapier**

1.  First things first, set up a [SparkPost account here](https://app.sparkpost.com/sign-up). When you first set up an account, SparkPost will ask you about your sending domain. I advise skipping this for now. Click the **Skip For Now** button.
2.  Click the **Get A Key** button under ‘Send with REST’. Copy the Key to notepad.
3.  Switch back to Zapier. The next step is to set up the Action which will be called when the Zap is triggered by the webhook.
4.  In Choose App, type **SparkPost** and select it. The next step is to Choose the Action. There is only one – **Send Email**.
5.  Click the **Connect a New Account** button. Paste the key you just copied and click **Yes, Continue**.
6.  Click the **Test** button next to the new account. If this is successful, click **Save + Continue**.

Here’s another short screencast to demonstrate these steps, although in this case I already had a SparkPost account.

<iframe src="https://www.youtube.com/embed/QCC1mPd7uos?feature=oembed"></iframe>

So we’ve connected Zapier and SparkPost. Next we need to trigger an email in SparkPost. We need a template for the email.

**Setting up the SparkPost Email Template**

1.  On the next screen we can select the Template for the email that SparkPost will send. Right now we don’t have any template, but there is a draft template called “My First Email” set up for you in SparkPost.
2.  Switch to the SparkPost browser window.
3.  Click **Templates**. Then click **My First Email**. This will bring you into the editor. We are just going to use the default template as this is really a proof of concept.
4.  Our Zap is going to take some data from the webhook body and construct a subject line that contains the Issue Key and Summary. In the Subject field in the template editor enter the text “**{{mysubject}}**” (without the quotes).
5.  Click the button to **Save & Publish**.

Double-check your work with this screencast.

<iframe src="https://www.youtube.com/embed/5bx7b7HEoRY?feature=oembed"></iframe>

## Complete the Zap

1.  Switch back to Zapier to complete the configuration.
2.  Select **My First Email** in the Template ID field.
3.  In the Inline Recipients field choose **Issue Fields Reporter EmailAddress**.
4.  In Substitution Data we provide key value pairs. The first field box is the key and here we can enter the key name **mysubject**. The second box is the value and here we can select **Issue Key** from the dropdown. After Issue Key, type a ” – ” (space, hyphen space) and then select **Issue Fields Summary** from the dropdown. This builds up a string of text for the subject line which will be injected into our email template.
5.  Click **Continue** and a test email should be sent to you.

This screencast shows the setting up of the key value pairs in Zapier.

<iframe src="https://www.youtube.com/embed/zwDnJVh66CE?feature=oembed"></iframe>

Now let’s see if it was all worth it. Create an Issue in JIRA using your own account. You should receive a notification from sandbox@sparkpost.com and the email subject line should contain your new issue key and summary. Then update any field, such as the description field. You should very quickly receive another email from SparkPost.

Hopefully it worked. If not, get in touch with me on the comments and I’ll try to help you diagnose it.

## Zapier and SparkPost Together

OK so there are quite a few steps involved but they are reasonably simple and give you a good sense of the power of Webhooks and Zapier. Let’s review where we are at and what we can do next.

At the beginning of this post we set a number of requirements.

- **Send emails in response to events on issues in JSD**. We are using webhooks, triggered by JIRA events, to trigger emails using Zapier and SparkPost.
- **We want to be able to completely customize the look and feel of those emails**. Although we didn’t show it here we have full access to the email template in SparkPost and we can completely customize the emails. Check out the SparkPost [docs](https://support.sparkpost.com/customer/en/portal/articles/1929890-creating-a-template?b_id=7411) for more information.
- **We want to be able to insert data from the issue into those emails**. We can inject substitution data (issue data from webhook body JSON content) into the templates. In this example we only injected data into the Subject but we can also do this in the body of the email. You can read up on the substitution data and its capabilities [here](https://developers.sparkpost.com/api/#/reference/substitutions-reference).
- **The emails should come from an email domain that the customer recognises and won’t be blocked or treated as spam**. We used the \*.sparkpost.com domain as the sender domain for our proof-of-concept. You can set up your own sending domain and then verify it with SPF and DKIM to allow SparkPost send emails from your own domain. See docs [here](https://support.sparkpost.com/customer/en/portal/articles/1933318-creating-sending-domains?b_id=7411).
- **Customers should be able to reply to these emails**. We have not yet addressed this requirement. But I believe it is possible and this worked in my initial tests. You would first need to set up sending from your company mail domain so that notifications arrive in recipients inboxes coming from support@company.com. When customers reply, the replies will go to this address. If you have JIRA set up to poll this account then JIRA should be able to process those emails and add the replies to the original issue. Alternatively you could auto-forward the emails to whatever email address is configured in JIRA.

To be honest I have not had time to completely test all scenarios and this is merely a proof-of-concept. I hope it inspires others to try this out and if you feel like it please add comments below and share your results.

In the next post (assuming there is interest), I will look into how you can send the emails from your own domain, how to filter the events using JQL, and how we can customize the email templates. I’ll also look at triggering the emails from workflow transitions and by using the JIRA Automation Plugin.

We won’t be able to create an email notification system as flexible as Notification Schemes but I think we can solve the problem of customizing email content for JIRA Service Desk customers.

\-Chris Dunne