Skill Builder

Email in Jira Exercises

Author: Matt Doar

Version: 1
Date: 1 October 2017
 Jira and Email Exercises

TABLE OF CONTENTS
1.1 Getting Started ................................................................................................................... 2

1.2 Jira Server and Cloud Differences.................................................................................... 2

2 Outgoing Email .................................... 3

2.1 Exercise 1: Confirm that you can send email from Jira. ................................................ 3

2.2 Exercise 2: Issue Changes should send email................................................................ 3

2.3 Exercise 3: Outgoing Mail Log .......................................................................................... 3

2.4 Exercise 5: Other Mail Server errors ................................................................................ 4

3 Incoming Email .................................... 5

3.1 Exercise 1: Check that you can read email in Jira .......................................................... 5

3.2 Exercise 2: Comment on an Issue .................................................................................... 5

3.3 Exercise 3: Create an Issue ............................................................................................... 6

3.4 Exercise 4: Incoming Email Logs ..................................................................................... 6

3.5 Exercise 5: Other Errors .................................................................................................... 6

3.6 Exercise 6: Stretch ............................................................................................................. 7

4 Using Gmail with Jira ............................. 8

4.1 Create a Google Account .................................................................................................. 8

4.2 Add an Incoming Mail Server ............................................................................................ 8

4.3 Create an Incoming Mail Handler...................................................................................... 8

1
 Jira and Email Exercises

1.1 Getting Started

For these exercises, you will need to be a member of the jira-administrators group in a Jira Server
instance that has an outgoing email server configured, or a Jira Cloud instance.
If you are using a non-production test Jira instance and want to set up a Gmail account for this, there
are instructions on doing this below.
Using Gmail with Jira
o Create a Google Account

1.2 Jira Server and Cloud Differences

Working with email in Jira is very similar whether you are using Jira Cloud or Jira Server. The are a few
differences listed here.
1. The outgoing mail server in Jira Cloud is not configurable by Jira administrators. You can enable
and disable it though.
2. Jira Cloud does not let you see the outgoing mail queue
3. The default incoming POP/IMAP mail server in Cloud is named mailstore. If you delete it you will
need to contact Atlassian Support to recreate it, since the password is not stored in backups from
Cloud.
4. The Local Files option for incoming mail servers is not present, only the mail server named POP
Mail Server.
5. Jira Cloud has an default incoming mail handler named Cloud Email Handler. This is for adding
comments only, not creating issues.
Note: Jira Service Desk has a different way of handling incoming email that involves storing incoming
emails in the Jira database. This is different from the regular Jira email that is covered in this badge.

When searching for an administration page, use the gg shortcut to make it faster.

2
 Jira and Email Exercises

2 OUTGOING EMAIL

2.1 Exercise 1: Confirm that you can

send email from Jira.
Send a test email to an email address that you can read from.
Tips:
1. Check that outgoing email is not disabled at the command line (Server only)
2. Check that outgoing email is not disabled on the Outgoing Mail server administration page

2.2 Exercise 2: Issue Changes should

send email
Check that adding a comment to an issue, or editing an issue, sends you an email.
Tips:
1. Check that your Profile setting "My Changes" is enabled
2. Use the Notification Helper in a View Issue page to see whether you should receive email for a
comment or edit on a particular issue
3. Check the Outgoing Mail queue to see if your email is there (Server only)
4. Flush the Outgoing Mail queue (Server only)
5. Check your Spam folder.
6. Gmail searches need to add "in:all" to search for spam.

2.3 Exercise 3: Outgoing Mail Log

(Server only)
Users can enable outgoing mail logging., find and read the outgoing mail log.
Watch an email being delivered
Enable DEBUG logging and see the log messages
Exercise 4: Invalid Email Address

3
 Jira and Email Exercises
(Server only)
1. Create a new Jira user with an invalid email address
2. Add the user as a watcher to an issue
3. Watch the outgoing mail log messages when Jira tries to deliver email to that user.

2.4 Exercise 5: Other Mail Server errors

(Server only)
If you are using a production mail server you may see errors about:
1. Quotas - some email servers are configured to only accept a limited number of emails per second.
Jira can sometimes exceed that limit temporarily
2. Cannot Relay - some email servers will only allow you to send email to a specific domain, e.g.
mycompany.com. This means that users with non-company email addresses will not receive email

4
 Jira and Email Exercises

3 INCOMING EMAIL

3.1 Exercise 1: Check that you can read

email in Jira
1. Check that incoming email is not disabled at the command line (Server only)
2. Check that at least one incoming email server (POP/IMAP) is not present at the top of the Incoming
Mail server administration page
3. Check the Services page to see the matching Service has been defined for the incoming email
handler

3.2 Exercise 2: Comment on an Issue

1. Create an issue and make sure you have permission to comment on the issue
2. Using an email address you own, send an email to the email address
For example, jira@yourcompany.atlassian.net for Cloud
Put the Jira issue key in the email subject, e.g. MYPROJ-123
Make sure you send the email from an account that uses the same address as your user in Jira
3. Wait for the mail handler to read the email you sent. Alternatively, edit the mail handler and change
the interval to a new value. On a non-oerloaded Jira this should cause the mail to be read almost
immediately.
4. Use the Test link in the second page of configuring the incoming mail handler to confirm that an
incoming mail handler is configured correctly and has no errors when it runs
Tips:
1. The user chosen by Jira from the email (From Address) needs to have permission to add a
comment to an issue
2. If you run the incoming email handlers too frequently, they may not finish before running again. 15
minutes is a good minimum interval
3. Every time you change the interval for an incoming mail handler, it runs immediately when you save
it

5
 Jira and Email Exercises

3.3 Exercise 3: Create an Issue

1. Set up an incoming mail handler to create or comment on an issue. You will need to specify a
project and issue type
2. Experiment with the mail handler configuration for cc and watcher, attachments of different sizes,
and default reporter
Tips:
1. Does the user chosen by Jira have permission to create an issue in the specified project?
2. Are the attachments in the email larger than the maximum allowed attachment size in Jira?
3. Is the size of the text in the email body larger than the maximum text size (number of characters)
allowed in Jira. By default this is only about 32,000 characters
Note: if there are required fields, then Jira will create the issue with no values in those fields. However,
the next time someone tries to edit the issue they will have to provide values for the fields.

3.4 Exercise 4: Incoming Email Logs

(Server only)
1. Users can enable incoming mail logging., find and read the incoming mail log.
2. Watch an incoming email being process
3. Enable DEBUG logging and see the log messages
4. Set the Forward address in an incoming mail handler to receive messages from Jira when an email
cannot be process
Exercise 4: Common Errors
When the From Address in the email is not found in for a Jira user, and no default reporter was set,
then no issue was created
Wrong Reporter - there are two users in Jira with the same email address, and Jira chose the one that
was not expected
The email subject is empty, so no issue Summary field could be created from the email. Summary is a
required field in Jira.

3.5 Exercise 5: Other Errors

Email in the mailbox was not addressed to an email address that the incoming mail handler is handling.
If all is well, there should be no old mail in any mailbox read by Jira. In practice there may be some
email that got left over. Periodically check for emails that are not being discarded by Jira and delete
them. If they haven't ben processed in the last hour, then those message likely never will be processed

6
 Jira and Email Exercises
If you have more than about 6 incoming mail handlers they may take up too much of Jira running and
stop other things such as LDAP synchronization or Data Center heartbeat from running properly.

3.6 Exercise 6: Stretch

1. Add a Split Regex incoming mail handler
2. (Server only) Use the Local Files mail server for an incoming mail handler to test how different
emails are processed. Note that this can also be used to effectively disable an incoming mail
handler
3. Find out what characters in incoming email can stop Jira from processing the email. And what
happens to the email afterwards.

7
 Jira and Email Exercises

4 USING GMAIL WITH JIRA

4.1 Create a Google Account

1. Create the Google account, which includes a gmail account, at
https://accounts.google.com/SignUp?hl=en. The current email address and phone field can be left
blank. For a user id something such as jiratest plus a user id such as jsmith is good, so
"jiratestjsmith"
2. Don't enable two factor authentication for this test account
(https://myaccount.google.com/u/3/security)
3. Under your gmail Settings, Forward and POP/IMAP, check the Enable IMAP setting and click on
Save Changes. More info at https://support.google.com/mail/answer/7126229
4. Go to My Account, Sign-in and Security, Connected Apps, scroll down and enable "Allow less
secure apps". More info at https://support.google.com/accounts/answer/6010255?hl=en

4.2 Add an Incoming Mail Server

1. Make sure email is not disabled in the Jira install file bin/setenv.sh. Search for a line with
DISABLE NOTIFICATIONS in it
2. Now navigate to Jira, System, Incoming Mail
3. Click on "Add POP / IMAP Server"
4. Choose a name for the mail server such as "gmail test imap server"
5. For Service Provider select "Google Apps Mail"
6. Provide the user name and password
7. Click on the Test Connection button and debug any failures to connect
8. Note that you have to click on Update after Test Connection to save your changes

4.3 Create an Incoming Mail Handler

1. Create an incoming mail handler using the new gmail mail server
2. Send mail to the new gmail address from some other user.
3. Watch as Jira reads from the new gmail account after a minute or so

8
 Jira and Email Exercises
Q) Can we use email+alias or a tag/folder?
A) No, this for sending email from gmail
More help? https://javaee.github.io/javamail/FAQ#gmail