Jira admins can configure their cloud apps to receive and process emails. Jira Work Management and Jira Software can receive emails from licensed users to create issues or add comments and attachments automatically.

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 custom mail server

Issues and comments in Jira can be generated from email messages sent to your cloud application's default mail server. Alternatively, you can set up additional POP or IMAP mail servers if you don’t want to use your application’s default mail server.

To generate issues and comments from emails, you’ll have to create a mail account for a POP or IMAP mail server that Jira can access. Jira periodically scans your new emails from your mail account, and it then creates issues and comments from your mails (via mail handlers). Learn more about mail handlers.

To set up an incoming mail server:

1. Choose > System.

2. Select Mail > Incoming Mail.

3. Click Add incoming mail server.

4. Give your mail server a name and description, and click Add.

5. Select the protocol, and enter the host name, port number, timeout, username and password fields. Learn more about incoming mail server fields.

6. Click Add.

Incoming mail server fields

To add an incoming mail server, you need to enter the following fields:

Add a Microsoft mail server with OAuth 2.0 integration

If you’re using Microsoft Exchange Online to create issues and comments from your email, then you need to configure OAuth 2.0 for your Microsoft email server. Microsoft will no longer support basic authentication, and your connection to the Microsoft Exchange Online server will not be operational.

To add an incoming Microsoft mail server:

1. Choose > System.
2. Select Mail > Incoming Mail.
3. Click Add incoming mail server.

4. Choose Microsoft as an email service provider.

5. Click Add.

6. Enter your Microsoft sign-in credentials to use your Microsoft mail server.

For Microsoft mail servers, Jira will auto-fill authorization and the token endpoint data. You’ll need to review and confirm permissions to let Jira access your information.

Upgrade your mail server from basic authentication to OAuth 2.0

Service providers like Microsoft will end the support for basic authentication. This means that you may no longer be able to create issues and comments from your Microsoft email address as Microsoft Exchange Online will not be operational. We recommend that you upgrade your existing mail servers that have basic authentication to OAuth 2.0. Learn more about adding mail servers with OAuth 2.0 integration.

To upgrade your mail server:

1. Choose > System.
2. Select Mail > Incoming Mail.

3. Click Add incoming mail server.

4. Give your mail server a name and description.

5. Choose Microsoft as an email service provider.

6. Click Add.

7. Configure an incoming mail handler with the Microsoft mail server you configured from step 1. Alternatively, you can use a Microsoft mail server that you’ve configured earlier.

8. Delete the incoming mail server that uses basic authentication.

Edit an existing incoming mail server

You can make changes to your existing incoming mail server. For example, if you’ve changed the password for your POP or IMAP mail server, then you’ll have to update this field in Jira so that issues and comments can be generated from your email messages. Learn more about incoming mail server fields.

To edit an existing incoming mail server:

1. Choose > System.

2. Select Mail > Incoming Mail.

3. Find your mail server under Set up your incoming mail server, and click Edit.

4. Make changes to the respective fields you want to update, and click Save.

Delete an incoming mail server

You can delete an incoming mail server that you no longer need, or if it is not upgraded to OAuth 2.0 authentication.

To delete an incoming mail server:

1. Choose > System.

2. Select Mail > Incoming Mail.

3. Find the mail server you want to delete, and select Delete.

Configure a mail handler

1. Choose > 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.

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 > 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 Work Management 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

createusers=false,senderEmail=no-reply@<URL>.atlassian.net,stripquotes=true,bulk=ignore

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

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

/_____________*/

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:

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.

Advanced mail loop detection (for Jira Service Management)

When Jira Service Management 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 Management during a short period of time. When this happens, the advanced mail loop detector of Jira Service Management can block emails from specific email addresses, depending on your configuration.

 How to configure advanced mail loop detection

1. Choose > System
2. In the Mail section, click Incoming Mail.
3. 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 Management 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.

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.