• Products
  • Documentation
  • Resources

Create issues and comments from email

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.

If you're looking for a help desk solution, it may be more practical to use Jira Service Management rather than setting up Jira Work Management or Jira Software for this purpose.

Jira Service Management uses a built-in processor to receive and process issue requests from emails. Issues created in Jira Service Management 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 Management's email channel

You can try Jira Service Management 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 custom mail server

To configure mail servers, you must have Administer Jira global permissions .

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:


If your POP/IMAP mail server is standard one, then select POP or IMAP. For a secure POP/IMAP mail server, select SECURE_POP or SECURE_IMAP.

Host name

Use this field specify the host name or IP address of your the POP/IMAP mail server.

Port number

Leave this blank for a default value.

Defaults are:

POP: 110; SECURE_POP: 995; IMAP: 143; SECURE_IMAP: 993


Specify the timeout period in milliseconds. Leave it blank for a default value, which is 10000 ms. Specifying 0 or a negative value here will result in Jira waiting indefinitely for the POP/IMAP server to respond.


Specify the username to authenticate your POP/IMAP account.


Enter the password to authenticate your POP/IMAP account.

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.

If Microsoft OAuth authentication is not successful for your mail server, you can still see the mail server in the list of your configured mail servers. But, this mail server will not be visible to you while you’re configuring the mail handler.

While configuring an incoming mail handler for your Microsoft mail server, you can use the same name as the mail server which uses basic authentication. If you’ve configured a mail handler with a mail server that uses basic authentication, you can edit the mail handler. You can then select the Microsoft mail server that uses OAuth 2.0 integration for your mail handler configuration to upgrade the configuration.

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.

If your incoming mail server is configured with a mail handler, deleting the mail server might lead to an unexpected behaviour from the mail handler. You may have to reconfigure or delete your mail handler if you delete an associated mail server.

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.

  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 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:

  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 your account's inbox. With an IMAP server, you can specify a different folder to scan.

  • If Jira successfully processes a message, Jira deletes the message from your mail account (for POP server) or file system (for file system messages). On an IMAP mail server processed messages are not deleted but marked as read.

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



Handler params

The default parameters for this handler are:

1 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



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.


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


1 /_____________*/


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.


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:

Jira processesing each incoming email message
  • Any attachments to the email will become attachments to the issue if attachments have been enabled in Jira (they are by default).

  • The maximum limit for message data and attachments for an email is 25 MB.

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

    1 2 3 4 5 6 7 8 9 10 11 ^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)

Advanced mail loop detection is only available in Jira Service Management. The information on this page is only applicable to Jira Service Management administrators.

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.


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

Additional Help