We have seen how you can configure JIRA to send e-mails to notify users about updates on their issues. Although, this is only half of the story when it comes to JIRA's e-mail support.
You can also set up JIRA for it to periodically poll mailboxes for e-mails and create issues based on the e-mails' subject and content. This is a very powerful feature with the following benefits:
- It hides the complexity of JIRA from business users, so they can log issues more efficiently and leave the complexity to the IT team
- It allows users to create issues even if JIRA can only be accessed within the internal network. Users can send e-mails to a dedicated mailbox for JIRA to poll
For JIRA to retrieve e-mails and create issues from them, you need to add the POP/IMAP mail server configurations to JIRA. POP and IMAP are mail protocols used to retrieve e-mails from the server. E-mail clients, such as Microsoft Outlook, use one of these protocols to retrieve your e-mails.
Unlike outgoing mail servers, JIRA allows you to add multiple incoming mail servers. This is because while you only need one mail server to send e-mails, you may have multiple mail servers or multiple mail accounts (on the same server) that people will use to send e-mails to. For example, you might have one dedicated to provide support and another one for sales. It is usually a good idea to create separate mail accounts to make it easier when trying to work out which e-mail can go into which project. For this reason, adding POP/IMAP mail servers can be thought of as adding multiple mail accounts in JIRA. Perform the following steps to add an incoming mail server:
- Browse to the JIRA administration console.
- Select the System tab and then the Incoming Mail option.
- Click on the Add POP/IMAP mail server button.
- Enter a name and description for the mail server.
- Select the type of mail service provider. For example, if you are using your own hosted mail service or one of the recognized cloud provider such as Google.
- Specify the host name of the POP/IMAP server if you are using your own (custom provider).
- Enter the username/password credentials for the mail account.
- Click on the Add button to create the POP/IMAP mail server:
Mail handlers are what JIRA uses to process retrieved e-mails. Each mail handler is able to process e-mails from one incoming mail server and periodically scan for new e-mails.
JIRA ships with a number of mail handlers, each with their own features. In the following sections, we will discuss each of the handlers in detail.
Creating a new issue or adding a comment to an existing issue mail handler (also known as the Create and Comment Handler in previous versions of JIRA) is the most used mail handler. It will create new issues from the received e-mails and also add comments to existing issues if the incoming e-mail's subject contains a matching issue key. If the subject does not contain a matching issue key, a new issue is created. The following table lists the parameters required when creating the mail handler:
|
Parameter |
Description |
|
Project |
This is the project in which issues will be created. This is not used for commenting where the e-mail subject will contain the issue key. |
|
Issue Type |
This is the issue type for newly created issues. |
|
Strip Quotes |
If this is present in the parameters, quoted text from the e-mail will not be added as a part of the comment. |
|
Catch E-mail Address |
This specifies if JIRA is to only handle e-mails that are sent to the specified address. |
|
Bulk |
This specifies how to handle autogenerated e-mails such as those generated by JIRA. It is possible to create a loop if JIRA sends e-mails to the same mailbox where it also picks up e-mails. In order to prevent this, you can specify one of the following:
Generally, you can set it to forward. |
|
Forward Email |
If this is specified, then the mail handler is unable to process an e-mail message it receives. An e-mail message indicating this problem will be forwarded to the e-mail address specified in this field. |
|
Create Users |
If the e-mail is sent from an unknown address, JIRA will create a new user based on the e-mail "from" address and randomly generate a password. An e-mail will be sent to the "from" address informing the new JIRA account user. |
|
Default Reporter |
This specifies the username of a default reporter, which will be used if the e-mail address in the From field of any of the received messages does not match the address associated with that of an existing JIRA user. |
|
Notify Users |
Uncheck this option if you do not want JIRA to notify new users created as per the Create Users parameter. |
|
CC Assignee |
JIRA will assign the issue to the user specified in the To field first. If no user can be matched from the To field, JIRA will then try the users in the CC and then BCC list. |
|
CC Watchers |
JIRA will add users in the CC list (if they exist) as watchers of the issue. |
This mail handler extracts text from an e-mail's content and adds it to the issue with a matching issue key in the subject. The author of the comment is taken from the From field.
It has a set of parameters similar to the Create and Comment handler.
Adding a comment from the non-quoted e-mail body is very similar to the Full Comment handler, but it only extracts non-quoted texts and adds them as comments. Texts that start with > or | are considered to be quoted.
It has a set of parameters similar to the Create and Comment handler.
Creating a new issue from each e-mail message is quite similar to the Create and Comment handler, except this will always create a new issue for every received e-mail.
It has a set of parameters similar to the Create and Comment handler.
Adding a comment before a specified marker or separator in the e-mail body is a more powerful version of the comment handlers. It uses regular expressions to extract texts from e-mail contents and adds them to the issue:
|
Parameter |
Description |
|
Split Regex |
This regex expression is used to extract contents. There are two rules for the regex expression:
|
You can set up as many mail handlers as you want. It is recommended that you create dedicated mailboxes for each project you wish to allow JIRA to create issues from e-mails. For each account, you will then need to create a mail handler. The mailbox you set up needs to be accessible through POP or IMAP.
Perform the following steps to add a mail handler:
- Browse to the Incoming Mail page.
- Click on the Add incoming mail handler button.
- Provide a name to the new mail handler.
- Select an incoming mail server or Local Files.
- Specify how long JIRA can wait to poll the mailbox for new e-mails (in minutes). You will want to keep this long enough to allow enough time for JIRA to process all the e-mails, but not too long as you may end up having to wait for a long time to see your e-mails converted into issues in JIRA.
- Select the type of handler you want to add.
- Click on the Next button:
Depending on the handler type you select, the next screen will vary. On the next screen, you will need to provide the required parameters for the mail handler, as described in the preceding section. The following screenshot shows an example configuration dialog box, where new issues will be created in the Help Desk project as Task:
You can update the details of your mail handlers at any time. You will often need to tune your handler parameters a few times until you get your desired results. Perform the following steps to update a mail handler:
- Browse to the Incoming Mail page.
- Click on the Edit link for the mail handler you wish to update.
- Update the configure options.
Once updated, the changes will be applied immediately and JIRA will use the new handler parameters for the next polling run.
You can also delete mail handlers that are no longer required at any time. Perform the following steps to delete a mail handler:
- Browse to the Incoming Mail page.
- Click on the Delete link for the mail handler you wish to remove.
The default mail handlers that come with JIRA are often enough for simple e-mail processing needs. If you need to have more control or need special processing logics for your incoming e-mails, you can create custom mail handlers. However, creating new mail handlers requires you to have a knowledge of programming; a better option is to use an add-on called Enterprise Mail Handler (JEMH) for JIRA.
With JEMH, you can set up advanced e-mail routing, additional e-mail triggered operations such as updating an issue based on your e-mail content, audit of received/processed e-mails, and more. You can find more about JEMH at https://marketplace.atlassian.com/plugins/com.javahollic.jira.jemh-ui/server/overview.