Creating issues and comments from email
Jira admins can configure their cloud apps to receive and process emails. Jira Core and Jira Software can receive emails from licensed users to create issues or add comments and attachments automatically.
If you're looking for a help desk solution, it may be more practical to use Jira Service Desk rather than setting up Jira Core or Jira Software for this purpose.
Jira Service Desk uses a built-in processor to receive and process issue requests from emails. Issues created in Jira Service Desk don't require the sender to have a license to create, view, comment, add attachments, or transition issues. Read more about receiving email requests with Jira Service Desk's email channel.
You can try Jira Service Desk for free. Select > Site administration. Then, choose Discover applications.
Configuring issue or comment creation from email
Issues and comments in Jira can be generated from email messages sent to your cloud application's default POP mail server. You can configure mail handlers to control how these emails are handled, or add another mail server depending on the needs of your team.
Configure a mail handler
- Choose > System
- Select Mail > Incoming Mail.
- Click Add incoming mail handler (or click Edit next to an existing mail handler).
- Enter a name that describes what your mail handler will do (e.g. "Create issues or comments from Company A's IMAP mail server")
Select the default server, or choose a server if additional ones have been configured.
For an IMAP mail server, if you want the 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 local files, if your file messages are being written to a subdirectory within the
import/mailsubdirectory of the Jira home directory, specify the subdirectory structure (within
- Specify the delay in minutes between the mail handler's running time, or the frequency with which the mail server is scanned.
- Choose the type of mail handler (more info on the default mail handlers below).
- Click Next to fill in options specific to the selected mail handler.
Click Test to make sure your mail handler is working properly.
Copy a saved email that contains a "Subject: " line to the configured directory. Jira will remove this file after it's 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:
- Click Add to save your mail handler.
For Jira to process an email, the sent date must not be older than 7 days.
If your sending domain has a Sending Policy Framework (SPF) validation configured, ensure that the email has passed this validation correctly. If your email is from such a domain, and does not pass the validation, then your email will be rejected.
Receive emails from new users
To allow Jira to handle email messages sent from people without a Jira user account:
- Create an anonymous or dummy mail account on your mail server.
- Create an equivalent anonymous or dummy Jira user account, whose email address matches the mail account you just created.
- When configuring your mail handler options, set the Default Reporter to be the anonymous or dummy Jira user account.
Delete a mail handler
- Choose > System
- Select Mail > Incoming Mail.
- Find the relevant mail handler and click Delete.
If you delete a mail handler service from Advanced > Services, note that its associated handler will also be deleted.
Configure additional mail servers
You can set up additional POP or IMAP mail servers if you want to link an another account to a Jira Core or Jira Software project. Jira will then use a service to scan for new email messages received by your mail account and a mail handler to create issues or comments.
How Jira handles messages on a mail server
- Jira scans email messages received in you'r account's inbox. With an IMAP server, you can specify a different folder to scan.
- If Jira successfully processes a message, it deletes the message from your mail account or file system. If a message is not successfully processed, it will remain in your mail account or file system.
Jira's mail handlers
As you create a new or edit an existing mail handler, check out the different options you can set for each handler by expanding the relevant section below.
Default email handler
This mail handler is automatically created with your default cloud mail server. If you want to create additional incoming mail rules, we recommend using one of the below customizable handlers.
Default email handler options
The default parameters for this handler are:
|Forward Email||If the mail handler has problems processing an email, a status message can be forwarded to a specified email address.|
Custom email handlers
Create a new issue or add a comment to an existing issue
This 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.
Add a comment from the non quoted email body
This handler creates a comment with the "non quoted" lines of the email message, removing any line that starts with ">" or "|". The comment will be added to the first issue key found in the email subject. The comment author will be pulled from the email From field.
Add a comment with the entire email body
This handler creates a comment based on the entire body of the email message received. The comment will be added to the first issue key found in the email subject. The comment author will be pulled from the email From field.
Create a new issue from each email message
This handler creates a new issue for each incoming message.
Add a comment before a specified marker or separator in the email body
This handler creates a comment from the body of an email message, but lets you filter any part of the body past a marker or separator that matches a specified regular expression (regex). The comment will be added to the first issue key found in the email subject. The comment author will be pulled from the email From field.
This is helpful when using mail systems like Lotus Notes and Outlook, which separate the core content from other content (e.g. replied or forwarded) by a predictable text string such as "
---- Original Message ----" or "
Extranet\n email.address/DOM/REG/CONT/CORP@CORPMAIL". Please make note of the following behavior when using this handler:
- 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.
Custom mail handler options
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.
Specify the project key of the default project where you want new issues to be created by this handler. (The project key comes before the issue key, e.g. JRA-122). This field is only relevant for issue creation, not for issue commenting.
|Issue Type||Choose the default issue type for new issues.|
|Strip Quotes||Remove quoted text from from an email message body (e.g. from previous email replies) so it doesn't appear in the issue comment.|
|Catch Email Address|
Process emails only if a specific recipient is included in the To, CC, or BCC lines (e.g. firstname.lastname@example.org). You can use this option if have multiple aliases for the same mail account and want to receive emails from only one alias.
You can only specify one catch email address and one issue type per mail handler. The Default Reporter option is more commonly used in place of catch emails.
This option only affects bulk emails, typically those sent by an automated service, whose header has the Precedence field set to "bulk" or the Auto-Submitted field set to "no". You can handle bulk emails several ways:
If the mail handler has problems processing an email, a status message can be forwarded to a specified email address.
Create new user accounts and send issue notifications when emails are received from an address that does not match any existing account. New users will be added to the default groups of the default Jira application and take up a license for that application.
The sender's email address will become the new account username and email address. New users will receive an email notification with more info about their new account and a password reset link.
Selecting this option will hide the Default Reporter option, as the two are not compatible.
If you don't select the Create Users option, specify the username of a default reporter to be used if the sender's email address doesn't match the address of an existing user.
Make sure the default reporter has Create Issues project permission for the previously selected project, as well as Create Comments project permission for other relevant projects the mail handler can add comments to.
When an issue is created using the default reporter, the original sender's address will appear in a brief message at the end of the issue's Description field.
If you select the Create Users option, you can choose to notify new users of their account details.
Automatically assign the issue to the first CCed email address.
Automatically add Jira users as watchers of the issue created and notify them of updates. Note that only existing users (not those created from the Create User option) can be added as watchers this way.
Issue and comment creation
The following diagram shows how Jira processes each incoming email message and determines how its content becomes a new issue or a comment on an existing issue:
- Any attachments to the email will become attachments to the issue if attachments have been enabled in Jira (they are by default)
- To ensure compatibility with various operating systems, the following characters will be replaced with an underscore in attachment filenames : \, /, ", %, :, $, ?, *, <, |, >.
- 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.
For additional mail servers you link to Jira applications, we recommend the following pre-processing tips:
- Because Jira mail handlers remove successfully processed email messages from your mail server, have your mail sent to a backup folder to maintain a record of what mail has been processed by Jira.
If your mail folder contains replies to Jira 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. The following rules (in procmail format) will detect most auto-replies:
^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\ signup
Even with these rules, you may encounter auto-replies 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. 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.
Advanced mail loop detection (for Jira Service Desk)
Advanced mail loop detection is only available in Jira Service Desk. The information on this page is only applicable to Jira Service Desk administrators.
When Jira Service Desk processes emails, it also keeps track of messages that come from unique senders. There may come a time when particular email addresses are sending a lot of emails to Jira Service Desk during a short period of time. When this happens, the advanced mail loop detector of Jira Service Desk can block emails from specific email addresses, depending on your configuration.
How to configure advanced mail loop detection
- Choose > System
- In the Mail section, click Incoming Mail.
- In the Advanced Configuration section, perform one of the following as needed:
- Increase the messages threshold, so that it does not trigger as easily (recommended).
- Set the threshold to 0 to disable it completely (not recommended, as it could cause a mail loop to spam your instance).
- Allowlist trusted domains, so that they are not impacted by the mail loop detector (not recommended as it may cause a mail loop even on the trusted domain).
Note the following details:
- By configuring a message threshold, once that message threshold is reached, Jira Service Desk will then handle these messages in bulk.
- Mail loops are commonly caused by out of office notifications, so even trusted domains could cause a mail loop.
- Make sure the default reporter has create issue permission.
- Ensure message sent date is within 7 days. Emails with a sent date that's older than 7 days won't be processed.
- It's expected that HTML/Rich Text formatting is not processed correctly by Jira. The email comment handler is designed to do plain text conversion.
Whenever you create a new mail handler, or edit an existing one, you should test its configuration to ensure it works as expected.