Creating issues and comments from email
Configuring issue or comment creation from email
Issues and comments in Jira can be generated either from:
- email messages sent to an account on a POP or IMAP mail server, or
- messages written to the file system generated by an external mail service.
Note that for all of the following procedures, you must be logged in as a user with the Jira Administrators global permission.
Step 1: Configure Jira as an OAuth 2.0 client
This is mandatory if you're using Gmail or Microsoft Exchange Online, which have deprecated using basic authentication.
You'll need to configure Jira as an OAuth 2.0 client. Once you do, you'll be able to select your OAuth 2.0 integration with Google or Microsoft as an authentication method for mail servers. For more info on how to do this, see Configure an outgoing link.
You do not need to update the settings in your custom email servers or other service providers if they use IMAP or POP3. They will continue to work.
Step 2: Configure a mail server/service
POP or IMAP email messages
To set up issue and comment creation from email, you will need to create a mail account for a POP or IMAP mail server that Jira can access – typically, one mail account for each Jira project. For example, for the 'ABC' project, you might establish an account abc-issues@example.com
Jira will periodically scan for new email messages received by your mail account (via a service) and appropriately create issues or comments for any emails it finds (via a mail handler).
Jira's mail handlers can also optionally create new user accounts for senders not previously seen. See the Create a new issue or add a comment to an existing issue section for more details.
Note that this is not possible if you are using External User Management.
Once you have created a mail account on a POP or IMAP mail server, configure Jira to receive email from that mail server account.
Tip: You can configure Jira's mail servers so that recipients of email notifications can simply reply to these messages and have the body of their replies added as comments to the relevant issue. To do this, simply set the From address in Jira's SMTP mail server to match that of the POP or IMAP mail server's account being monitored. In most cases, this means having Jira's SMTP and POP or IMAP mail servers use the same mail account. See below for details on how to configure Jira to handle these emailed replies.
File system messages
To set up issue and comment creation from messages written to the file system by an external mail service, your external mail service must be able to write these messages within the import/mail subdirectory of the Jira home directory.
External mail services are very much like the POP or IMAP services above, except that instead of email messages being read from a mail account, they are read from a directory on the disk. External mail services are useful because they overcome the potential security risks associated with anonymous mail accounts. Instead you can simply configure your external mail service to dump incoming email messages within the Jira Home Directory's import/mail subdirectory, which is scanned periodically.
Please also be aware that Jira expects only one message per file, so your external mail service should be configured to generate such output.
Note — how Jira handles messages on a mail server/service:
- For mail accounts, Jira scans email messages received by your mail account's 'Inbox' folder. However, for IMAP mail servers, you can specify a different folder within your mail account.
- If Jira successfully processes a message, Jira deletes the message from your mail account (on a POP) or file system (i.e. for file system messages). On an IMAP mail server processed messages are not deleted but marked as read.
- If Jira does not successfully process a message, the message will remain either in your mail account or on the file system.
Step 3: Configure a mail handler
Once you have configured Jira to receive messages from a mail server/service, you configure Jira to handle these messages through a 'mail handler'.
- From the top navigation bar select Administration
> System. - Select Mail > Incoming Mail to open the Incoming Mail page.
- Click the Add incoming mail handler button (or the Edit link next to an existing mail handler) in the Mail Handlers section to open the Mail Handler dialog box.
- Specify a Name that describes what your mail handler will do — for example, 'Create issues or comments from Example Company's IMAP mail server'.
- Select the mail Server that you configured in step one (above). This is either a POP or IMAP mail server or the Local Files option for an external mail service that writes messages to the file system.
- Specify the Delay (in minutes) between the mail handler's running time. This effectively defines the frequency with which Jira scans the Server that you specified in the previous step.
- Choose the type of mail Handler from dropdown list. For more information, refer to the Mail Handlers section below.
- If you chose either an IMAP mail server or the Local Files option in the Server field, then a Folder Name field appears below the Handler dropdown list:
- For an IMAP mail server, if you want mail handler to scan for new messages from a folder other than the 'Inbox' in your mail account, specify the name of that folder here.
- For the Local Files option, if your file messages are being written to a subdirectory within the
import/mailsubdirectory of the Jira home directory, specify the subdirectory structure (withinimport/mail) here.
- Click Next to continue with specifying the remaining options specific to mail Handler you selected above. For more information, see the Mail Handlers section below.
- (Optional) Click the Test button to test your mail handler. If you are using Local Files as the server, copy a saved email that contains a "Subject: " line to the configured directory. Jira will remove this file after it is parsed, or log a message about why an issue could not be created. You may have to specify the project, issuetype and reporterusername properties as a minimum configuration.
A sample email file might look like this:To: jira@example.comFrom: some-jira-user@example.comSubject: (TEST-123) issue summary title hereBody of the email goes here - Click the Add / Save button to save your mail handler.
Note — the relationship between Jira mail handlers and services:
- A Jira mail handler is part of a Jira service. Hence, when you create a mail handler, its service will appear as an entry on the Services page.
- Be aware that editing mail handlers can only be performed through the Mail Handlers page (described above).
- On the Mail Handlers page, clicking the Delete link associated with a mail handler removes that handler. Since a mail handler is part of a service, then if you delete a mail handler's service on the Services page, its associated handler will also be removed from the Mail Handlers page.
Mail handlers
Jira provides the following default mail handlers:
For more information about how these mail handlers create issues and comments in Jira, refer to Issue/comment creation (below).
Also refer to the Handy tips with mail handlers (below) for tips on tweaking mail handlers to allow Jira to handle the following types of email messages:
- Email sent from people without a Jira user account.
Create a new issue or add a comment to an existing issue
This email handler doesn't use regex. We advise using the Add a comment before a specified marker or separator in the email body handler instead. For more information, see Set up Jira notifications.
This message handler creates a new issue, or adds a comment to an existing issue. If the subject contains an issue key, the message is added as a comment to that issue. If no issue key is found, a new issue is created in the default project.
To configure a 'Create a new issue or add a comment to an existing issue' mail handler:
- If you have not already done so, begin configuring your mail handler (above).
On the Create a new issue or add a comment to an existing issue dialog box, complete the following fields/options:
Project Specify the project key of the default project to which new issues are created by this handler — for example,
JRA. Note:- This field is only relevant for issue creation, not for issue commenting.
- If an email message contains an issue key in its subject line and that issue key exists in your Jira installation, the handler will add the email message content as a comment on the issue, regardless of which project the issue is in.
Issue Type Choose the default issue type for new issues. Strip Quotes Select this checkbox to remove quoted text from from an email message's body (e.g. from previous email replies) before the body's content is added to the Jira issue's comment. Catch Email Address If specified, only email messages whose To:, Cc:, Bcc: lines contain the recipient specified in this field will be processed — for example,
issues@mycompany.comMake sure not to put the Catch email address in the Bcc header when sending email but rather place it in the To: and Cc: headers. This is because m ail servers tend to strip the Bcc header. Additionally, the Mail handler will look for the Catch email address in this header only if the header is available in the email source.Upon specifying an address here, all email messages whose To:, Cc:, Bcc: lines contain addresses other than the Catch Email Address are ignored. This is useful if you have multiple aliases for the same mail account (e.g.
foo-support@example-co.comandbar-support@example-co.comaliases forsupport@example-co.com) for multiple mail services (e.g. each one to create issues in separate Jira projects).Note: in practice, this option is rarely useful and should not be confused with the more common Default Reporter. You can only specify one catch email address and one issue type per mail handler.
In addition, there is a known bug in Jira 7.0.0 and JIRA 7.0.1, which means that multiple email handlers that are used to create issues in different projects when an email is sent to multiple aliases will not process the email correctly. This has been fixed in JIRA 7.0.2. For more information, see JRA-41831 - Getting issue details... STATUS .
Bulk This option only affects 'bulk' email messages whose header has either its Precedence: field set to bulk or its Auto-Submitted field not set to no. Such messages would typically be sent by an automated service. When such an email message is received, the following action will be performed, based on the option you choose:
- Ignore the email and do nothing
- Forward the email (i.e. to the address set in the Forward Email text field)
- Delete the email permanently
- Accept the email for processing
It is generally a good idea to set bulk=forward and set a Forward Email address, to prevent mail loops between Jira and another automated service (eg. another Jira installation).
Forward Email If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.
Note: An SMTP mail server must be configured for this option to function correctly.Create Users Select this checkbox if you want Jira to create new user accounts from any received email messages whose From: field contains an address that does not match one associated with an existing Jira user account. This allows the creator of the email message to be notified of subsequent updates to the issue, which can be achieved by configuring the relevant project's notification scheme to notify the Reporter of updates.
The username and email address of these newly created Jira user accounts will be the email addresses specified in the From: fields of these received messages. The password for these new Jira users is randomly generated and an email message is sent their addresses informing them about their new JIRA user account.
Users created this way will be added to the default group/s of the default Jira application (and therefore take up a license for this application).See the Managing groups documentation.
Note: this option is not compatible with Default Reporter field option below and as such, choosing the Create Users option will hide the Default Reporter option.Default Reporter Specify the username of a default reporter, which will be used if the email address in the From: field of any received messages does not match the address associated with that of an existing Jira user — for example, a Jira username such as
emailed-reporter Note:- This option is not available if the Create Users checkbox is selected.
- Please ensure that the user specified in this field has the Create I ssues project permission for the relevant Project (specified above) as well as the Create Comments project permission for the other relevant projects to which this mail handler should add comments.
- When an issue is created and this option is specified, the email message's From: field address is appended in a brief message at the end of the issue's Description field, so that the sender can be identified.
Notify Users Clear this checkbox if you do not want Jira to send out an email message notifying users whose accounts have been created by the Create Users option above.
Note: this option only functions if the Create Users checkbox has been selected.CC Assignee Select this checkbox if you want Jira to automatically assign the issue created to a Jira user:
- Whose email address (registered with their Jira account) matches the first matching address encountered in the To:, then Cc: and then Bcc: field of the email message received.
- Who also has the Assignable User project permission for the relevant Project (specified above).
CC Watchers Select this checkbox if you want Jira to automatically add Jira users to the issue created, where those users' email addresses (registered with their Jira accounts) match addresses encountered in the To:, Cc: or Bcc: fields of the email message received.
Please note that when an issue is created, new Jira users created by the Create Users option (above) cannot also be added to the issue's watchers list by this CC Watchers option. Jira users must already exist in Jira's userbase, and must have an email address.- Test and save your mail handler (above).
Add a comment from the non quoted email body
This email handler doesn't use regex. We advise using the Add a comment before a specified marker or separator in the email body handler instead. For more information, see Set up Jira notifications.
This message handler creates a comment, but only uses the 'non quoted' lines of the body of the email message. A quoted line is any line that starts with a '>' or '|' symbol and such lines of text will not be added to the comment. The issue to which the comment is added is chosen from the first issue key found in the email subject. The author of the comment is taken from the address of the email message's From: field.
To configure an 'Add a comment from the non quoted email body' mail handler:
- If you have not already done so, begin configuring your mail handler (above).
On the Add a comment from the non quoted email body dialog box, complete the following fields/options:
Catch Email Address If specified, only email messages whose To:, Cc:, Bcc: lines contain the recipient specified in this field will be processed — for example,
issues@mycompany.com
Make sure not to put the Catch email address in the Bcc header when sending email but rather place it in the To: and Cc: headers. This is because m ail servers tend to strip the Bcc header. Additionally, the Mail handler will look for the Catch email address in this header only if the header is available in the email source.Upon specifying an address here, all email messages whose To:, Cc:, Bcc: lines contain addresses other than the Catch Email Address are ignored. This is useful if you have multiple aliases for the same mail account (e.g.
foo-support@example-co.comandbar-support@example-co.comaliases forsupport@example-co.com) for multiple mail services (e.g. each one to create issues in separate Jira projects). Note: in practice, this option is rarely useful and should not be confused with the more common Default Reporter. You can only specify one catch email address and one issue type per mail handler.Bulk This option only affects 'bulk' email messages whose header has either its Precedence: field set to bulk or its Auto-Submitted field not set to no. Such messages would typically be sent by an automated service. When such an email message is received, the following action will be performed, based on the option you choose:
- Ignore the email and do nothing
- Forward the email (i.e. to the address set in the Forward Email text field)
- Delete the email permanently
- Accept the email for processing
Forward Email If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.
Note: An SMTP mail server must be configured for this option to function correctly.Create Users Select this checkbox if you want Jira to create new user accounts from any received email messages whose From: field contains an address that does not match one associated with an existing Jira user account. This allows the creator of the email message to be notified of subsequent updates to the issue, which can be achieved by configuring the relevant project's notification scheme to notify the Reporter of updates.
The username and email address of these newly created Jira user accounts will be the email address specified in the From: field of the message. The password for the new user is randomly generated, and an email is sent to the new user informing them about their new account in Jira.
Users created this way will be added to the default group/s of the default Jira application (and therefore take up a license for this application).See the Managing groups documentation.
Note: this option is not compatible with Default Reporter field option below and as such, choosing the Create Users option will hide the Default Reporter option.Default Reporter Specify the username of a default reporter, which will be used if the email address in the From: field of any received messages does not match the address associated with that of an existing Jira user — for example, a Jira username such as
emailed-reporter
Note:- This option is not available if the Create Users checkbox is selected.
- Please ensure that the user specified in this field has the Create Issues project permission for the relevant Project (specified above) as well as the Create Comments project permission for the other relevant projects to which this mail handler should add comments.
Notify Users Clear this checkbox if you do not want Jira to send out an email message notifying users whose accounts have been created by the Create Users option above.
Note: this option only functions if the Create Users checkbox has been selected.Test and save your mail handler (above).
Add a comment with the entire email body
This message handler creates a comment based on the entire body of the email message received. The issue to which the comment is added is chosen from the first issue key found in the email subject. The author of the comment is taken from the address of the email message's From: field.
To configure an 'Add a comment with the email body' mail handler:
- If you have not already done so, begin configuring your mail handler (above).
On the Add a comment with the entire email body dialog box, complete the following fields/options:
Catch Email Address If specified, only email messages whose To:, Cc:, Bcc: lines contain the recipient specified in this field will be processed — for example,
issues@mycompany.comMake sure not to put the Catch email address in the Bcc header when sending email but rather place it in the To: and Cc: headers. This is because m ail servers tend to strip the Bcc header. Additionally, the Mail handler will look for the Catch email address in this header only if the header is available in the email source.Upon specifying an address here, all email messages whose To:, Cc:, Bcc: lines contain addresses other than the Catch Email Address are ignored. This is useful if you have multiple aliases for the same mail account (e.g.
foo-support@example-co.comandbar-support@example-co.comaliases forsupport@example-co.com) for multiple mail services (e.g. each one to create issues in separate Jira projects). Note: in practice, this option is rarely useful and should not be confused with the more common Default Reporter. You can only specify one catch email address and one issue type per mail handler.Bulk This option only affects 'bulk' email messages whose header has either its Precedence: field set to bulk or its Auto-Submitted field not set to no. Such messages would typically be sent by an automated service. When such an email message is received, the following action will be performed, based on the option you choose:
- Ignore the email and do nothing
- Forward the email (i.e. to the address set in the Forward Email text field)
- Delete the email permanently
- Accept the email for processing
Forward Email If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.
Note: An SMTP mail server must be configured for this option to function correctly.Create Users Select this checkbox if you want Jira to create new user accounts from any received email messages whose From: field contains an address that does not match one associated with an existing Jira user account. This allows the creator of the email message to be notified of subsequent updates to the issue, which can be achieved by configuring the relevant project's notification scheme to notify the Reporter of updates.
The username and email address of these newly created Jira user accounts will be the email address specified in the From: field of the message. The password for the new user is randomly generated, and an email is sent to the new user informing them about their new account in Jira.
Users created this way will be added to the default group/s of the default Jira application (and therefore take up a license for this application).See the Managing groups documentation.
Note: this option is not compatible with Default Reporter field option below and as such, choosing the Create Users option will hide the Default Reporter option.Default Reporter Specify the username of a default reporter, which will be used if the email address in the From: field of any received messages does not match the address associated with that of an existing Jira user — for example, a Jira username such as
emailed-reporter Note:- This option is not available if the Create Users checkbox is selected.
- Please ensure that the user specified in this field has the Create Issues project permission for the relevant Project (specified above) as well as the Create Comments project permission for the other relevant projects to which this mail handler should add comments.
Notify Users Clear this checkbox if you do not want Jira to send out an email message notifying users whose accounts have been created by the Create Users option above.
Note: this option only functions if the Create Users checkbox has been selected.- Test and save your mail handler (above).
Create a new issue from each email message
This message handler creates a new issue for each incoming message.
To configure an 'Create a new issue from each email message' mail handler:
- If you have not already done so, begin configuring your mail handler (above).
On the Create a new issue from each email message dialog box, complete the following fields/options:
Project Specify the project key of the default project to which new issues are created by this handler — for example,
JRA. Note:- This field is only relevant for issue creation, not for issue commenting.
- If an email message contains an issue key in its subject line and that issue key exists in your Jira installation, the handler will add the email message content as a comment on the issue, regardless of which project the issue is in.
Issue Type Choose the default issue type for new issues. Catch Email Address If specified, only email messages whose To:, Cc:, Bcc: lines contain the recipient specified in this field will be processed — for example,
issues@mycompany.comMake sure not to put the Catch email address in the Bcc header when sending email but rather place it in the To: and Cc: headers. This is because m ail servers tend to strip the Bcc header. Additionally, the Mail handler will look for the Catch email address in this header only if the header is available in the email source.Upon specifying an address here, all email messages whose To:, Cc:, Bcc: lines contain addresses other than the Catch Email Address are ignored. This is useful if you have multiple aliases for the same mail account (e.g.
foo-support@example-co.comandbar-support@example-co.comaliases forsupport@example-co.com) for multiple mail services (e.g. each one to create issues in separate Jira projects). Note: in practice, this option is rarely useful and should not be confused with the more common Default Reporter. You can only specify one catch email address and one issue type per mail handler.Bulk This option only affects 'bulk' email messages whose header has either its Precedence: field set to bulk or its Auto-Submitted field not set to no. Such messages would typically be sent by an automated service. When such an email message is received, the following action will be performed, based on the option you choose:
- Ignore the email and do nothing
- Forward the email (i.e. to the address set in the Forward Email text field)
- Delete the email permanently
- Accept the email for processing
Forward Email If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.
Note: An SMTP mail server must be configured for this option to function correctly.Create Users Select this checkbox if you want Jira to create new user accounts from any received email messages whose From: field contains an address that does not match one associated with an existing Jira user account. This allows the creator of the email message to be notified of subsequent updates to the issue, which can be achieved by configuring the relevant project's notification scheme to notify the Reporter of updates.
The username and email address of these newly created Jira user accounts will be the email address specified in the From: field of the message. The password for the new user is randomly generated, and an email is sent to the new user informing them about their new account in Jira.
Users created this way will be added to the default group/s of the default Jira application (and therefore take up a license for this application).See the Managing groups documentation.
Note: this option is not compatible with Default Reporter field option below and as such, choosing the Create Users option will hide the Default Reporter option.Default Reporter Specify the username of a default reporter, which will be used if the email address in the From: field of any received messages does not match the address associated with that of an existing Jira user — for example, a Jira username such as
emailed-reporter Note:- This option is not available if the Create Users checkbox is selected.
- Please ensure that the user specified in this field has the Create Issues project permission for the relevant Project (specified above) as well as the Create Comments project permission for the other relevant projects to which this mail handler should add comments.
- When an issue is created and this option is specified, the email message's From: field address is appended in a brief message at the end of the issue's Description field, so that the sender can be identified.
Notify Users Clear this checkbox if you do not want Jira to send out an email message notifying users whose accounts have been created by the Create Users option above.
Note: this option only functions if the Create Users checkbox has been selected.CC Assignee Select this checkbox if you want Jira to automatically assign the issue created to a Jira user:
- Whose email address (registered with their Jira account) matches the first matching address encountered in the To: , then Cc: and then Bcc: field of the email message received.
- Who also has the Assignable User project permission for the relevant Project (specified above).
CC Watchers Select this checkbox if you want Jira to automatically add Jira users to the issue created, where those users' email addresses (registered with their Jira accounts) match addresses encountered in the To:, Cc: or Bcc: fields of the email message received.
Please note that when an issue is created, new Jira users created by the Create Users option (above) cannot also be added to the issue's watchers list by this CC Watchers option. Jira users must already exist in Jira's userbase, and must have an email address.- Test and save your mail handler (above).
Add a comment before a specified marker or separator in the email body
This message handler creates a comment from the body of an email message - but ignores any part of the body past a marker or separator that matches a specified regular expression (regex).
For mail systems like Lotus Notes and Outlook, the core content of an email message is separated from other (e.g. replied or forwarded) content in the body by some predictable text string like '---- Original Message ----' or 'Extranet\n email.address/DOM/REG/CONT/CORP@CORPMAIL'. Hence, use this message handler, which can take any valid regex, to filter core from extraneous content from various different mail systems.
Also note that the issue to which the comment is added is chosen from the first issue key found in the email subject.
The Add a comment before a specified marker or separator in the email body mail handler has the following behavior with respect to received email messages:
- If the regex pattern (specified in the mail handler) is found, the text in the email message body before the first regex pattern match is used for the comment and the remainder of the body is discarded.
- If the regex pattern (specified in the mail handler) is not found, the entire text in the email message body is used for the comment.
- If no regex pattern is specified in the mail handler, the entire text in the email message body is used for the comment.
- If the regex expression specified in the mail handler is erroneous, the entire text in the email message body is used for the comment.
To configure an 'Add a comment before a specified marker or separator in the email body' mail handler:
- If you have not already done so, begin configuring your mail handler (above).
On the Add a comment before a specified marker or separator in the email body dialog box, complete the following fields/options:
Split Regex Specify a regular expression matching the text that separates the content of the email message mail body from other (replied or forwarded) content in the body.
Please Note:- The regex must begin and end with a delimiter character, typically '
/'. - Commas are not allowed in a regex, as they are used to separate each mail handler field/option when they are integrated into a Jira service and there is not (as yet) an escape syntax.
For example:
/----\s*Original Message\s*----/or
/_____________*/Catch Email Address If specified, only email messages whose To:, Cc:, Bcc: lines contain the recipient specified in this field will be processed — for example,
issues@mycompany.com
Make sure not to put the Catch email address in the Bcc header when sending email but rather place it in the To: and Cc: headers. This is because m ail servers tend to strip the Bcc header. Additionally, the Mail handler will look for the Catch email address in this header only if the header is available in the email source.Upon specifying an address here, all email messages whose To:, Cc:, Bcc: lines contain addresses other than the Catch Email Address are ignored. This is useful if you have multiple aliases for the same mail account (e.g.
foo-support@example-co.comandbar-support@example-co.comaliases forsupport@example-co.com) for multiple mail services (e.g. each one to create issues in separate Jira projects). Note: In practice, this option is rarely useful and should not be confused with the more common Default Reporter. You can only specify one catch email address and one issue type per mail handler.Bulk This option only affects 'bulk' email messages whose header has either its Precedence: field set to bulk or its Auto-Submitted field not set to no. Such messages would typically be sent by an automated service. When such an email message is received, the following action will be performed, based on the option you choose:
- Ignore the email and do nothing
- Forward the email (i.e. to the address set in the Forward Email text field)
- Delete the email permanently
- Accept the email for processing
Forward Email If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.
Note: An SMTP mail server must be configured for this option to function correctly.Create Users Select this checkbox if you want Jira to create new user accounts from any received email messages whose From: field contains an address that does not match one associated with an existing Jira user account. This allows the creator of the email message to be notified of subsequent updates to the issue, which can be achieved by configuring the relevant project's notification scheme to notify the Reporter of updates.
The username and email address of these newly created Jira user accounts will be the email address specified in the From: field of the message. The password for the new user is randomly generated, and an email is sent to the new user informing them about their new account in Jira.
Users created this way will be added to the default group/s of the default Jira application (and therefore take up a license for this application).See the Managing groups documentation.
Note: this option is not compatible with Default Reporter field option below and as such, choosing the Create Users option will hide the Default Reporter option.Default Reporter Specify the username of a default reporter, which will be used if the email address in the From: field of any received messages does not match the address associated with that of an existing Jira user — for example, a Jira username such as
emailed-reporter Note:- This option is not available if the Create Users checkbox is selected.
- Please ensure that the user specified in this field has the Create Issues project permission for the relevant Project (specified above) as well as the Create Comments project permission for the other relevant projects to which this mail handler should add comments.
Notify Users Clear this check box if you do not want Jira to send out an email message notifying users whose accounts have been created by the Create Users option above.
Note: this option only functions if the Create Users check box has been selected.- The regex must begin and end with a delimiter character, typically '
- Test and save your mail handler (above).
Custom mail handlers
You can design your own message handlers to better integrate your own processes into Jira. Such custom mail handlers configured using the standard procedure above.
For more information about creating custom mail handlers, see the Message Handler Plugin Module documentation.
Issue/comment creation
The following points describe how Jira processes each incoming email message and determines how its content gets added as either a comment to an existing issue or a new issue altogether.
- The subject of an email message is examined for an existing issue key:
- If an issue key is found in the subject, the content of the email message's body is processed and added as a comment to the issue with that issue key.
- If an issue key is NOT found in the subject, the in-reply-to header is examined:
- If the email message is found to be a reply to another email message from which an issue was previously created, the body is processed and added as a comment to that issue.
- If the email message is NOT found to be a reply, a new issue is created.
For example, an email message to a mail account foo@example-co.com on a POP or IMAP mail server configured against a Jira server will be processed as follows:
- Issue Creation:
- The subject of the email message will become the issue summary. Since all issues require a summary, each email message intended for issue creation should include a subject.
- The body of the email message will be the issue description.
- A bug will be created for project 'JRA' with the above information. (This is essentially based on the mail handler configuration above).
- Any attachments to the email message will become attachments to the issue (assuming attachments have been enabled in Jira). To ensure compatibility with various operating systems, any of the following characters in the filename will be replaced with an underscore character: \, /, ", %, :, $, ?, *, <, |, >.
- If the incoming email is set to a high priority, the corresponding issue will be created with a higher priority than the default priority that is set in your Jira system.
- The subject of the email message will become the issue summary.
- Comment Creation:
- The body of the email will become a comment on the issue.
Any attachments to the email will become attachments to the issue (assuming attachments have been enabled in Jira).
Handy tips with mail handlers
To allow Jira to handle email messages sent from people without a Jira user account:
- Create an 'anonymous'/'dummy' mail account on your mail server/service (above).
- Create an equivalent 'anonymous'/'dummy' Jira user account, whose Email field matches the mail account you created in the previous step.
- When configuring your mail handler(s) (above) to handle messages from this mail account, set the Default Reporter to this 'anonymous'/'dummy' Jira user account.
Best practices (pre-processing Jira email messages)
For Jira production servers, we recommend that setting up the following email message pre-processing:
- Since Jira mail handlers remove successfully processed email messages from your mail server, ensure that your mail is sent to a backup folder so that a record of what mail Jira processed is available.
If your mail folder contains replies to Jira's email notifications, set up rules that filter out auto-replies and bounces.
If you do not do this, there is a strong possibility of mail loops between Jira and autoresponders like 'out of office' notifications. Jira sets a 'Precedence:bulk' header (unless you have disabled this) and an 'Auto-Submitted' header on outgoing email, but some autoresponders ignore it.
There is no bulletproof way of detecting whether an email is a bounce or autoreply. The following rules (in procmail format) will detect most autoreplies:^From:.*mailer-daemon@ ^Auto-Submitted:.auto- ^Content-Type:\ multipart/report;\ report-type=delivery-status ^Subject:\ Delivery\ Status\ Notification ^Subject:\ Undeliverable ^Subject: Returned Mail: ^From:\ System\ Administrator ^Precedence:\ auto_reply ^Subject:.*autoreply ^Subject:.*Account\ signupEven with these rules, you may encounter autoreplies with nothing in the headers to distinguish it from a regular mail, In these cases you will just need to manually update the filters to exclude that sender.
- Set up a filter to catch email with huge attachments. Jira uses the standard JavaMail library to parse email, and it quickly runs out of memory on large attachments (e.g. > 50 MB given 512 MB heap). As the un-handled mail is not deleted, it will be reprocessed (causing another OutOfMemoryError) each time the mail service runs.
In practice this problem is rarely seen, because most mail servers are configured to not accept email with huge attachments. Unless you are sure your mail server will not pass a huge attachment on to Jira, it is best to configure a filter to prevent Jira encountering any huge attachments. - Set up spam filtering rules, so Jira does not have to process (and possibly create issues from) spam.
Troubleshooting
Jira's Logging & Profiling page has configuration options for Outgoing and Incoming mail.Whenever you create a new (or edit an existing) mail handler (above), a Test button is available to allow you to test your mail handler's configuration to ensure it works as expected.A useful tip for debugging mail-related problems in Jira is to set the -Dmail.debug=true property on startup. This will cause protocol-level details of Jira's email interactions to be logged in catalina.out (or standard output).
Common problems
- If Jira does not appear to be creating sending emails or creating issues and comments from email, your Jira instance could be experiencing OutOfMemory errors. Please check your log files for OutOfMemory errors. If there are OutOfMemory errors, please restart Jira and investigate the errors.
- If you find some incoming emails simply disappear, check that you have not accidentally started a second copy of Jira (e.g. in a staging environment) which is downloading and deleting mails. See Disable email sending/receiving for flags you should set to prevent mail being processed.
- If replies by email of Jira's notifications list Jira's SMTP server rather than the configured handler POP account (ie, in Outlooks' 'Reply-to' functionality), the project needs to be configured to add a 'reply-to' header in outgoing notifications. This can be configured in the project view for that particular project in Jira's Administration.
- If HTML/Rich Text formatting is not being process correctly by Jira, this is an expected behavior. The email comment handler was designed to do plain text conversion.
Do more with Jira
To create issues and add comments directly from your inbox, check out these apps on the Atlassian Marketplace:
- Email This Issue: Notify stakeholders both inside and outside the company about issues right from workflow transitions
- Outlook App for Jira: connect Jira issues with emails on all devices