Atlassian JIRA has two different places to setup an email connection: incoming and outgoing. This probably goes without saying, but let me briefly define these for you:
- Incoming: This is where you add one or more email server connections for incoming email. This email will be used to create JIRA issues, comments, and potentially users.
- Outgoing: This is where you add one email server for sending email from JIRA. These will typically be notifications, such as that an issue was created, assigned, or commented on. JIRA can only have one outgoing email connection.
At first glance, you might think, “OK, we already have email@example.com, so let’s use that for JIRA.” And you plug that in for incoming and outgoing email. But that can cause some problems.
The biggest issue is email loops. This is particularly prevalent if you’re using Gmail (either a personal account or Google Business) for your JIRA instance. Here’s what can end up happening:
- New email comes in to firstname.lastname@example.org. JIRA creates an issue from it.
- You add a comment to that issue.
- An outgoing notification is generated, and this is sent through email@example.com.
- JIRA sees this outgoing message as a new/unread email.
- JIRA looks at the issue key in the subject line or email header and pulls in this sent message as a new comment on that issue.
- This generates an Issue Commented event because the comment wasn’t created by your profile, so that sends a new notification through email.
- Repeat steps 3-6 until your SMTP gateway decides it has had enough, locks its door, and turns rock music up really loud so it can’t hear you yelling.
Option 1: Use separate mailboxes for incoming and outgoing
There are a couple of things you can do to avoid this. The best and easiest is to use different mailboxes for incoming and outgoing email for JIRA, and make sure these are dedicated mailboxes.
As a reminder, JIRA deletes all email that it imports (or, at least, it issues a delete command; Gmail ignores this command and just deletes all the labels off the email instead, so the mail is still in your mailbox. Exchange will delete the email completely, and there won’t even be a copy in Deleted Items), so it’s best to not share that incoming mailbox with other purposes if you can avoid it.
For outgoing, a dedicated SMTP gateway that is only used for outgoing mail is recommended. You can have other services using it, but it shouldn’t be used as a mailbox for incoming email.
Option 2: Use filters to apply labels
A second option is to use an IMAP connection and a rule/filter on your incoming mail to make sure the right mail is put into a particular folder, then JIRA only pulls in email from that folder. This can be done very easily with Exchange and will let you have multiple incoming mail handlers in JIRA that all connect to the same mailbox; just use some filters in Exchange to drop mail into the right folder. It’s a bit trickier with Gmail.
The problem with Gmail is that, instead of folders, we’re dealing with labels. When we point JIRA at a particular label, it’ll only pull in email with that label, which helps cut down on stuff being added accidentally. But if we’re not careful with how we create the rule in Gmail, we could accidentally label our outgoing email. Unlike Exchange, which has a separate folder for Inbox and Sent, these are all just labels in Gmail, and our filters could inadvertently label outgoing mail so it gets pulled into JIRA.
It’s not complex, necessarily, just something we need to think through. I recommend a few different labels, and unfortunately I can’t just give them to you because the circumstances of your email may be different from other places. But I can give you some suggestions.
You want to label (most) everything sent to your help@ mailbox with a word you’ll use for the incoming mail handler. I suggest JIRA. This filter will look like to:firstname.lastname@example.org and you’ll set that to label emails automatically with “JIRA”. When the email is pulled into JIRA, it will delete the label from the email, thus preventing a loop.
The problem with this is that you likely have things being sent to that mailbox that you don’t want created as issues. By way of example, a recent client of mine had a distribution list of email@example.com and “everyone” just went to every mailbox. So we needed a filter for to:firstname.lastname@example.org that marked as read, skipped the inbox, and deleted the message (which was likely overkill; we could have just deleted, but I don’t trust Gmail at this point). Think through what email your help@ mailbox receives and build labels appropriately. This applies equally to Exchange, where you may need a rule to shunt certain messages to a different folder.
One of the annoying things about labels in Gmail is that they apply sequentially but the only way to change the order of filters is to delete them, then recreate them in the order you want read. So we had one filter to grab certain messages and delete them, and a later filter to apply the JIRA label. You may have to play around with your labels a bit before you get this working right.
I recommend doing some testing by searching in Gmail while sending email through your mailbox before you connect the mail handler. Once you do connect it, you’ll want to have your Outgoing Mail window in JIRA open and be able to quickly click the Disable button if you start to get a loop. When I was first sorting this all out, I’d see 20 comments get created real quick by a loop and realize I needed to disable Outgoing while I changed how things were working.
One last thing to mention is that, depending on the service you’re using, you can overload your outgoing mail server and it’ll throttle your mail delivery. If you’re using Gmail, even Google for Business, this limit is pretty low. While their documentation doesn’t say it, I think I’ve hit SMTP throttling at around 1-200 emails in a 60 minute period. It’ll unlock after an hour or so unless you hit their maximum daily rate, in which case you’ll need to wait 24 hours.
You can’t selectively delete emails from the mail queue in JIRA, so if you have legitimate notifications mixed in with looped or accidental messages, you’ll effectively have to wait for the throttle to relax, reprocess your mail queue, and then watch a few messages get through before it gets throttled again. The last time I had to deal with it (following a bulk change where a client sent 400 notifications in addition to all the customer interactions happening at the time), it was 6-7 hours to get all of the email through.
My recommendation is always to use a dedicated SMTP. Mandrill has been recommended to me, but I haven’t used it myself, so take a look around and find something that works for your organization. If you can run your own email server, I’ve used Exim, HMailServer, and Exchange in the past with good success.
Got a question? Comment below or visit answers.atlassian.com.