Create issues and comments from email

Jira admins can configure their cloud apps to receive and process emails. Jira 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 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.

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

If you have incoming mail servers configured with Basic Authentication or App Passwords using Gmail or Microsoft email accounts, we recommend that you switch to OAuth to avoid any disruption as Google and Microsoft are phasing out support for Basic Authentication and App Passwords.

Open Authorization (OAuth) provides more security than Basic Authentication by allowing you to connect your email service to Jira without needing to share your password.

Microsoft OAuth

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 since Microsoft Exchange Online won’t work anymore. Depending on how your organization is configured, you may require consent from your Microsoft or Google admin. Learn more about getting consent from your Microsoft admin.

Configure a Microsoft mail server with OAuth 2.0 integration

To add an incoming Microsoft mail server:

Select () > System
Select Mail > Incoming Mail.
Select Add incoming mail server.
Give your mail server a name and description.
Select Sign in with Microsoft.
Enter your Microsoft 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

To upgrade your mail server:

Select () > System
Select Mail > Incoming Mail.
Select Add incoming mail server.
Give your mail server a name and description.
Select Sign in with Microsoft.
Select Add.
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 configured earlier.
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.

All emails processed by the incoming mail server will be marked as read and will not be deleted from the Microsoft inbox.

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.

Google OAuth

If you are using Gmail to create issues and comments from your email and would like to set up a mail server for your incoming emails on Jira, then you need to configure OAuth 2.0 for your Gmail email server. Depending on how your organization is configured, you may require consent from your Google admin. Learn more about getting consent from your Google admin.

Configure a Gmail mail server with OAuth 2.0 integration

To add an incoming Gmail mail server:

Select () > System
Select Mail > Incoming Mail.
Select Add incoming mail server.
Give your mail server a name and description.
Select Sign in with Google.
Enter your Gmail credentials to use your Gmail mail server.
Check “Read, compose, and send emails from your Gmail account” permissions.
Select on continue to finish signing in with your Gmail mail server.

For Gmail 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 or App Passwords to OAuth 2.0

To upgrade your mail server:

Select Add incoming mail server.
Give your mail server a name and description.
Select Gmail as an email service provider.
Select Sign in with Google.
Enter your Gmail sign-in credentials to use your Gmail mail server.
Check “Read, compose, and send emails from your Gmail account” permissions.
Select on continue to finish signing in with your Gmail mail server.
Configure an incoming mail handler with the Gmail mail server you configured from step 1. Alternatively, you can use a Gmail mail server you’ve configured earlier.
Delete the incoming mail server that uses Basic authentication/App passwords

Note:

If Gmail OAuth authentication is unsuccessful 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 email handler.
While configuring an incoming mail handler for your Gmail 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 Gmail mail server that uses OAuth 2.0 integration for your mail handler configuration to upgrade the configuration.
All emails processed by the incoming mail server will be marked as read and will not be deleted from the Gmail inbox.

Configure a custom 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:

Choose > System.
Select Mail > Incoming Mail.
Click Add incoming mail server.
Give your mail server a name and description, and click Add.
Select the protocol, and enter the host name, port number, timeout, username and password fields. Learn more about incoming mail server fields.
Click Add.

Incoming mail server fields

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

Protocol	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
Timeout	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.
Username	Specify the username to authenticate your POP/IMAP account.
Password	Enter the password to authenticate your POP/IMAP account.

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:

Choose > System.
Select Mail > Incoming Mail.
Find your mail server under Set up your incoming mail server, and click Edit.
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:

Choose > System.
Select Mail > Incoming Mail.
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

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.
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 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 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 (on a POP or IMAP mail server) or file system (i.e. for file system messages).

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

Option	Details
Handler params	The default parameters for this handler are: `1createusers=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: `1/----\sOriginal Message\s----/` or `1/_____________*/`
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 is not 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.
Default Reporter	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, and Add 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.
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.

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.
If you’re using Outlook, the incoming email’s priority might not match the priority in Jira. This will depend on how your priority schemes in Jira are configured.

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

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

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 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.
Make sure to add a subject to the email. The subject will fill the summary field of the issue. The email will not be processed if the subject in the email is not filled.
Every Jira site comes with its own preconfigured default mail server. You can also configure your own mail server for use on your site.

Whenever you create a new mail handler, or edit an existing one, you should test its configuration to ensure it works as expected.

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community