It is possible to automatically create issues or comments in JIRA based on incoming e-mail messages. This feature is very useful in scenarios such as helpdesks, where the users normally send an e-mail to a designated e-mail address and the support team picks up the issues from JIRA based on those e-mails!
Once configured correctly, any new e-mail that comes in will create a corresponding issue in JIRA, and the replies to the e-mail notifications on that issue will be created as comments on that issue. It is also possible to attach documents on the issue by attaching them on the e-mail, provided attachments are enabled in JIRA. If external user management is not enabled, it is also possible to create a user account-if they don't already have an account.
In this recipe, we will see how we can configure JIRA to enable this feature.
The following are the steps to enable issue creation from e-mail:
- Create an e-mail account on the server-typically, one e-mail account for each JIRA project. This mailbox should be accessible via POP, IMAP, or on the local file system. JIRA will periodically scan this mailbox and create issues or comments based on the e-mail.
- Navigate to JIRA's Administration | System | Mail| IncomingMail.
- Click on Add POP / IMAP mail server button.
- Enter the details for the POP or IMAP mail server created in Step1 and click on Add.
- Click on Add incoming mail handler button:
a. Name: Name of the mail handler.
b. Server: Pick one from the servers configured previously, or select the Local Files option for an external mail service that writes messages to the file system.
c. Delay: Choose a delay for the handler to run and scan the mails.
d. Handler: Select one of the handlers from the list. Details of available handlers can be found at https://confluence.atlassian.com/display/JIRA/Creating+Issues+and+Comments+from+Email#CreatingIssuesandCommentsfromEmail-messagehandlers. Let us pick the Create a new issue or add a comment to an existing issue handler.
e. Folder Name: For IMAP Server, specify the folder name if it is a folder other than Inbox. For the Local Files option, specify the subdirectory within the import/mail directory in JIRA Home.
- Click Next to add the handler parameters specific to the handle selected. This is the most important part, where we specify the parameters that will be used while creating the issue. Following is the list of important parameters for the handler we picked:
a.
Project: Project where the issue should be created.b.
Issue Type: Type of the issue to be created. For example, if we want the issue to be created as a bug, select Bug.c.
Strip Quotes: If enabled, it strips quoted text, for example, text from previous replies, from the e-mail body.d.
Catch Email Address: If added, JIRA will process only e-mails sent to this address. It is used when there are multiple aliases for the same e-mail inbox.e.
Bulk: Determines how to handle "bulk" e-mails. Possible options are:-
ignore: Ignore the e-mail and do nothing.-
forward: Forward the e-mail to the address set in the "Forward Email" text field.-
delete: Delete the e-mail permanently.-
accept: Accept the email for processing.f.
Forward Email: Error notifications and un-handled e-mails (used in conjunction with bulk forward handle parameter) will be forwarded to this address.g.
Create Users: If set to true, accounts will be created for new senders. This option is not compatible with the Default Reporter option.h.
Default Reporter: Can be used to create issue with the specified reporter when the sender does not match with an existing user. This option will not be available if Create Users is checked.i.
Notify Users: Only used if Create Users is checked. Indicates whether users should get a mail notification for the new accounts created.j.
CC Assignee: If set, the new issue will be assigned to a matching user in the To field, or Cc field or Bcc field-in the given order-depending on where the user is matched. The user should have Assignable User project permission.k.
CC Watchers: If set, matching users in To, Cc, and Bcc fields are added as watchers on the issue. Even the new users created by the Create Users option can be added as a watcher using this option. - Finish the handler creation.
JIRA is now configured to receive mails to the newly added mailbox.
The handler we set up scans the mailbox every N minutes as configured in the delay and picks up the new incoming messages. When a new message is received, JIRA scans through the subject to see if there are any mentions of an already existing issue. If there is one, the e-mail is added as a comment on the mentioned issue, with the e-mail body as the comment text. If there is no mention of an issue in the subject, JIRA still checks whether the e-mail is a reply to another e-mail that already created an issue or not. If so, the e-mail body is again added as a comment on that issue. This is done by checking the in-reply-to header in the e-mail.
If JIRA still couldn't find any matching issues, a new issue is created in the project and of the type configured in the handle parameters. The e-mail subject will become the issue summary and the e-mail body the description.
Any attachments on an e-mail, new, or replies, will be added as attachments on the issue.
More information about the creation of issues and comments from an e-mail and on how the other handlers work can be found at http://confluence.atlassian.com/display/JIRA/Creating+Issues+and+Comments+from+Email .
You can also write a custom mail handler, using the message-handler plugin module, by following the tutorial at https://developer.atlassian.com/jiradev/jira-platform/guides/email/tutorial-custom-message-mail-handler-for-jira.