Creating issues and comments from email

Still need help?

The Atlassian Community is here for you.

Ask the community

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

  1. Choose the Jira icon (,  or ) > Jira settings > System
  2. Select Mail > Incoming Mail
  3. Click Add incoming mail handler (or click Edit next to an existing mail handler).
  4. Enter a name that describes what your mail handler will do (e.g. "Create issues or comments from Company A's IMAP mail server")
  5. 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/mail subdirectory of the Jira home directory, specify the subdirectory structure (within import/mail) here.

  6. Specify the delay in minutes between the mail handler's running time, or the frequency with which the mail server is scanned.
  7. Choose the type of mail handler (more info on the default mail handlers below).
  8. Click Next to fill in options specific to the selected mail handler. 
  9. 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:

    To: jira@example.com
    From: some-jira-user@example.com
    Subject: (TEST-123) issue summary title here
    Body of the email goes here 

  10. Click Add to save your mail handler.

For Jira to process an email, the sent date must not be older than 7 days.

Receive emails from new users

To allow Jira to handle email messages sent from people without a Jira user account:

  1. Create an anonymous or dummy mail account on your mail server.
  2. Create an equivalent anonymous or dummy Jira user account, whose email address matches the mail account you just created. 
  3. When configuring your mail handler options, set the Default Reporter to be the anonymous or dummy Jira user account.

Delete a mail handler

  1. Choose the Jira icon (,  or ) > Jira settings > System
  2. Select Mail > Incoming Mail
  3. 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

Option Details
Handler params

The default parameters for this handler are:

createusers=false,senderEmail=no-reply@<URL>.atlassian.net,stripquotes=true,bulk=ignore
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

Option Details
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.

  • 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 isn't an escape syntax.

Examples:

/----\s*Original Message\s*----/

or

/_____________*/
Project

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. issues@mycompany.com). 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.

Bulk

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:

  • Ignore the email and do nothing
  • Send the email to the specified forward email address (recommended to prevent mail loops between Jira applications and other automated services)
  • Delete the email permanently
  • Accept the email for processing
Forward Email

If the mail handler has problems processing an email, a status message can be forwarded to a specified email address.

Create Users

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.

Default Reporter

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.

Notify Users

If you select the Create Users option, you can choose to notify new users of their account details.

CC Assignee

Automatically assign the issue to the first CCed email address.

CC Watchers

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:

Issues and comments from email

  • 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.

Pre-processing tips

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.

Troubleshooting

  • 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.

Last modified on Aug 7, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.