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, IMAP, or Microsoft Graph mail server.
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 don't need to update the settings in your custom email servers or other service providers if they use POP3, IMAP, or Microsoft Graph. They'll continue working.
Step 2: Configure a mail server/service
POP, IMAP, or Microsoft Graph email messages
To have issues and comments created from email, you should set up a mail account for a POP, IMAP, or Microsoft Graph mail server that Jira can access – typically, one mail account for each Jira project. For example, for the ABC project, you can create the 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, IMAP, or Microsoft Graph mail server, configure Jira to receive email from that mail server account.
You can configure Jira mail servers so that the recipients of email notifications can simply reply to these messages and have the body of their replies added as comments to relevant issues.
To provide this ability, set the From address in a Jira SMTP mail server to match a monitored account of a POP, IMAP, or Microsoft Graph mail server. As a result, the Jira SMTP server will use the same mail account as the POP, IMAP, or Microsoft Graph mail server. Learn more about SMTP mail server configuration
In the following Step 3, learn 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 POP, IMAP, or Microsoft Graph services. The difference is that instead of email messages being read from a mail account, they are read from a directory on the disk.
External email services are beneficial as they eliminate potential security risks associated with anonymous email accounts. You can set up an external email service to dump incoming email messages in the import/mail subdirectory of the Jira home directory. This subdirectory is regularly scanned for new messages.
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 a message is processed successfully, it’ll be deleted from your mail account on a POP mail server or from the file system (for file system messages). On an IMAP and Microsoft Graph mail server, processed messages aren’t deleted but instead 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've configured Jira to receive messages from a mail server, you should configure Jira to manage these messages through a mail handler:
- From the top navigation bar select Administration
> System. In the left-side panel, select Incoming mail.
On the Incoming mail page, select Add incoming mail handler. You’ll be redirected to the form for creating a mail handler.
In the Name field, set a name for the mail handler. The name can describe what the mail handler will do. For example,
Create issues or comments from Example Company's IMAP mail server.In the Server field, select the mail server you configured in Step 1: Configure Jira as an OAuth 2.0 client. This can be a POP, IMAP, or Microsoft Graph mail server, or the Local files option for an external mail service that writes messages to the file system.
In the Delay field, set the delay in minutes between the running time of the mail handler. The delay effectively defines the frequency with which Jira scans the mail server that you selected.
- In the Handler field, select one of the mail handlers. Learn more about mail handlers
- The Folder Name field appears in the dialog if you selected either an IMAP mail server or the Local Files option in the Server field:
For an IMAP mail server, if you want the mail handler to scan for new messages from a folder other than
Inboxin your mail account, set the name of this folder.For the Local files option, if your file messages are being written to a subdirectory in the
import/mailsubdirectory of the Jira home directory, set the subdirectory structure inimport/mail.
Select Next to continue with setting the remaining options specific to the mail handler you selected.
- Optional: Select Test to test the mail handler. If you're using the local files as the server, copy a saved email that contains the
"Subject: "line to the configured directory. Jira will remove this file after it's parsed or log a message about why an issue can’t be created. As a minimum configuration, you should specify theproject,issuetype, andreporterusernameproperties. A sample email file will look as follows:To: jira@example.comFrom: some-jira-user@example.comSubject: (TEST-123) issue summary title hereThe body of the email goes here Select Add/Save to save the mail handler.
Here are a few important things to know about the relation between Jira mail handlers and Jira services:
A mail handler is part of a service. When you create a mail handler, its service will appear as an entry on the Services page. Learn more about Jira services
You can edit a mail handler only on the Incoming mail page, in the Mail handlers section.
In the Mail handlers section, to remove a mail handler, select Delete for it. Since a mail handler is part of a service, if you delete the service on the Services page, its associated handler will be removed from Mail handlers section.
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 the mail account foo@example-co.com on a POP, IMAP, or Microsoft Graph mail server configured against a Jira server will be processed in the following way:
- 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 incoming replies to outgoing email notifications list the Jira SMTP server instead of any incoming mail server, you should add the
reply-toheader to outgoing notifications in your project. You can do this in the project view for your project in Jira 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