Creating Issues and Comments from Email

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

JIRA can be configured to automatically create issues or comments on existing issues based on incoming messages received by a mail server or external mail service.

This is especially useful in a helpdesk or support scenario, where users send support queries via email that you wish to track with JIRA. Subsequent email messages about the issue (for example, responses to Email Notifications) can be automatically recorded as comments. Additionally, any attachments in the emails can automatically be attached to the issue (with appropriate configuration).

Configuring issue or comment creation from email

On this page:

Step one: Configure a mail server/service

POP or IMAP email messages

To set up issue and comment creation from email, you will need to create a mail account for a POP or IMAP mail server that JIRA can access – typically, one mail account for each JIRA project. For example, for the 'ABC' project, you might establish an account abc-issues@example.com

JIRA will periodically scan for new email messages received by your mail account (via a service) and appropriately create issues or comments for any emails it finds (via a mail handler).

JIRA's mail handlers can also optionally create new user accounts for senders not previously seen. See the Create a new issue or add a comment to an existing issue section for more details.

(info) Note — how JIRA handles messages on a mail server/service:

  • For mail accounts, JIRA scans email messages received by your mail account's 'Inbox' folder. However, for IMAP mail servers, you can specify a different folder within your mail account.
  • 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).
  • If JIRA does not successfully process a message, the message will remain either in your mail account or on the file system.

Step two: Configure a mail handler

Once you have configured JIRA to receive messages from a mail server/service, you configure JIRA to handle these messages through a 'mail handler'.

To configure a JIRA mail handler:

  1. Log in as a user with the JIRA Administrators  global permission.
  2. Choose > System. Select Mail > Incoming Mail to open the Incoming Mail page.
    (tick) Keyboard shortcut: g + g + start typing incoming mail
  3. Click the Add incoming mail handler button (or the Edit link next to an existing mail handler) in the Mail Handlers section to open the Mail Handler dialog box.
  4. Specify a Name that describes what your mail handler will do — for example, 'Create issues or comments from Example Company's IMAP mail server'.
  5. Select the mail Server that you configured in step one (above). This is either a POP or IMAP mail server or the Local Files option for an external mail service that writes messages to the file system.
  6. Specify the Delay (in minutes) between the mail handler's running time. This effectively defines the frequency with which JIRA scans the Server that you specified in the previous step.
  7. Choose the type of mail Handler from dropdown list. For more information, refer to the Mail Handlers section below.
  8. If you chose either an IMAP mail server or the Local Files option in the Server field, then a Folder Name field appears below the Handler  dropdown list:
    • For an IMAP mail server, if you want 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 the Local Files option, 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.
  9. Click Next to continue with specifying the remaining options specific to mail Handler you selected above. For more information, refer to the Mail Handlers section below.
  10. (Optional) Click the Test button to test your mail handler. If you are using Local Files as the server, copy a saved email that contains a "Subject: " line to the configured directory. JIRA will remove this file after it is 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 
  11. Click the Add / Save button to save your mail handler.

(info) Note — the relationship between JIRA mail handlers and services:

Mail handlers

 JIRA provides the following default mail handlers:

JIRA Service Desk uses a built-in email processor to manage incoming emails in service desk projects. It's purpose-built for service desk projects and works differently from JIRA mail handlers. Issues created via JIRA email handlers don't show up as service desk customer requests. For this reason, we don't recommend using a JIRA mail handler for service desk projects.

For more information about how these mail handlers create issues and comments in JIRA, refer to Issue/comment creation (below).

Also refer to the Handy tips with mail handlers (below) for tips on tweaking mail handlers to allow JIRA to handle the following types of email messages:

  • Email sent from people without a JIRA user account.

Create a new issue or add a comment to an existing issue

This message 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.

To configure a 'Create a new issue or add a comment to an existing issue' mail handler:

  1. If you have not already done so, begin configuring your mail handler (above).
  2. On the Create a new issue or add a comment to an existing issue dialog box, complete the following fields/options:

    Project

    Specify the project key of the default project to which new issues are created by this handler — for example, JRA.

    (info) Note:

    • This field is only relevant for issue creation, not for issue commenting.
    • If an email message contains an issue key in its subject line and that issue key exists in your JIRA installation, the handler will add the email message content as a comment on the issue, regardless of which project the issue is in.
    Issue TypeChoose the default issue type for new issues.
    Strip Quotes

    Select this check box to remove quoted text from from an email message's body (e.g. from previous email replies) before the body's content is added to the JIRA issue's comment.

    If you find this feature is not working correctly, you can use the workaround explained here: JRA-28444 - Getting issue details... STATUS

    Catch Email Address

    If specified, only email messages whose To:, Cc:, Bcc: lines contain the recipient specified in this field will be processed — for example, issues@mycompany.com

    Upon specifying an address here, all email messages whose To:, Cc:, Bcc: lines contain addresses other than the Catch Email Address are ignored. This is useful if you have multiple aliases for the same mail account (e.g. foo-support@example-co.com and bar-support@example-co.com aliases for support@example-co.com) for multiple mail services (e.g. each one to create issues in separate JIRA projects).

    Note: in practice, this option is rarely useful and should not be confused with the more common Default Reporter. You can only specify one catch email address and one issue type per mail handler.

    In addition, there is a known bug in JIRA 6.4 to JIRA 7.0.1, which means that multiple email handlers that are used to create issues in different projects when an email is sent to multiple aliases will not process the email correctly. This has been fixed in JIRA 7.0.2. For more information, see JRA-41831 - Getting issue details... STATUS .

    Bulk

    This option only affects 'bulk' email messages whose header has either its Precedence: field set to bulk or its Auto-Submitted field set to no. Such messages would typically be sent by an automated service. When such an email message is received, the following action will be performed, based on the option you choose:

    1. Ignore the email and do nothing.
    2. Forward the email (i.e. to the address set in the Forward Email text field).
    3. Delete the email permanently.

    It is generally a good idea to set bulk=forward and set a Forward Email address, to prevent mail loops between JIRA and another automated service (eg. another JIRA installation).

    Forward Email

    If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.

    Create Users

    Select this check box if you want JIRA to create new user accounts from any received email messages whose From: field contains an address that does not match one associated with an existing JIRA user account. This allows the creator of the email message to be notified of subsequent updates to the issue, which can be achieved by configuring the relevant project's notification scheme to notify the Reporter of updates.

    The username and email address of these newly created JIRA user accounts will be the email addresses specified in the From: fields of these received messages. The password for these new JIRA users is randomly generated and an email message is sent their addresses informing them about their new JIRA user account.

    Users created this way will be added to the 'jira-users' group and given application access to JIRA (and therefore take up a license).

    (info) Note: this option is not compatible with Default Reporter field option below and as such, choosing the Create Users option will hide the Default Reporter option.

    Default Reporter

    Specify the username of a default reporter, which will be used if the email address in the From: field of any received messages does not match the address associated with that of an existing JIRA user — for example, a JIRA username such as emailed-reporter

    (info) Note:

    • This option is not available if the Create Users check box is selected.
    • Please ensure that the user specified in this field has the Create I ssues  project permission for the relevant Project (specified above) as well as the Create Comments   project permission for the other relevant projects to which this mail handler should add comments.
    • When an issue is created and this option is specified, the email message's From: field address is appended in a brief message at the end of the issue's Description field, so that the sender can be identified.
    Notify Users

    Clear this check box if you do not want JIRA to send out an email message notifying users whose accounts have been created by the Create Users option above.

    (info) Note: this option only functions if the Create Users check box has been selected.

    CC Assignee

    Select this check box if you want JIRA to automatically assign the issue created to a JIRA user:

    • Who's email address (registered with their JIRA account) matches the first matching address encountered in the To:, then Cc: and then Bcc: field of the email message received.
    • Who also has the Assignable User project permission for the relevant Project (specified above).
    CC Watchers

    Select this check box if you want JIRA to automatically add JIRA users to the issue created, where those users' email addresses (registered with their JIRA accounts) match addresses encountered in the To:, Cc: or Bcc: fields of the email message received.

    (info) Please note that when an issue is created, new JIRA users created by the Create Users option (above) cannot also be added to the issue's watchers list by this CC Watchers option. JIRA users must already exist in JIRA's userbase, and must have an email address.

  3. Test and save your mail handler (above).

Add a comment from the non quoted email body

This message handler creates a comment, but only uses the 'non quoted' lines of the body of the email message. A quoted line is any line that starts with a '>' or '|' symbol and such lines of text will not be added to the comment. The issue to which the comment is added is chosen from the first issue key found in the email subject. The author of the comment is taken from the address of the email message's From: field.

To configure an 'Add a comment from the non quoted email body' mail handler:

  1. If you have not already done so, begin configuring your mail handler (above).
  2. On the Add a comment from the non quoted email body dialog box, complete the following fields/options:

    Catch Email AddressIf specified, only email messages whose To:, Cc:, Bcc: lines contain the recipient specified in this field will be processed — for example, issues@mycompany.com

    Upon specifying an address here, all email messages whose To:, Cc:, Bcc: lines contain addresses other than the Catch Email Address are ignored. This is useful if you have multiple aliases for the same mail account (e.g. foo-support@example-co.com and bar-support@example-co.com aliases for support@example-co.com) for multiple mail services (e.g. each one to create issues in separate JIRA projects).

    (info) Note: in practice, this option is rarely useful and should not be confused with the more common Default Reporter. You can only specify one catch email address and one issue type per mail handler.

    Bulk

    This option only affects 'bulk' email messages whose header has either its Precedence: field set to bulk or its Auto-Submitted field set to no. Such messages would typically be sent by an automated service. When such an email message is received, the following action will be performed, based on the option you choose:

    1. Ignore the email and do nothing.
    2. Forward the email (i.e. to the address set in the Forward Email text field).
    3. Delete the email permanently.
    Forward Email

    If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.

    Create Users

    Select this check box if you want JIRA to create new user accounts from any received email messages whose From: field contains an address that does not match one associated with an existing JIRA user account. This allows the creator of the email message to be notified of subsequent updates to the issue, which can be achieved by configuring the relevant project's notification scheme to notify the Reporter of updates.

    The username and email address of these newly created JIRA user accounts will be the email address specified in the From: field of the message. The password for the new user is randomly generated, and an email is sent to the new user informing them about their new account in JIRA.

    Users created this way will be added to the 'jira-users' group and given application access to JIRA (and therefore take up a license).

    (info) Note: this option is not compatible with Default Reporter field option below and as such, choosing the Create Users option will hide the Default Reporter option.

    Default Reporter

    Specify the username of a default reporter, which will be used if the email address in the From: field of any received messages does not match the address associated with that of an existing JIRA user — for example, a JIRA username such as emailed-reporter

    (info) Note:

    • This option is not available if the Create Users check box is selected.
    • Please ensure that the user specified in this field has the Create Issues project permission for the relevant Project (specified above) as well as the Create Comments project permission for the other relevant projects to which this mail handler should add comments.
    Notify Users

    Clear this check box if you do not want JIRA to send out an email message notifying users whose accounts have been created by the Create Users option above.

    (info) Note: this option only functions if the Create Users check box has been selected.

  3. Test and save your mail handler (above).

Add a comment with the entire email body

This message handler creates a comment based on the entire body of the email message received. The issue to which the comment is added is chosen from the first issue key found in the email subject. The author of the comment is taken from the address of the email message's From: field.

To configure an 'Add a comment with the email body' mail handler:

  1. If you have not already done so, begin configuring your mail handler (above).
  2. On the Add a comment with the entire email body dialog box, complete the following fields/options:

    Catch Email AddressIf specified, only email messages whose To:, Cc:, Bcc: lines contain the recipient specified in this field will be processed — for example, issues@mycompany.com

    Upon specifying an address here, all email messages whose To:, Cc:, Bcc: lines contain addresses other than the Catch Email Address are ignored. This is useful if you have multiple aliases for the same mail account (e.g. foo-support@example-co.com and bar-support@example-co.com aliases for support@example-co.com) for multiple mail services (e.g. each one to create issues in separate JIRA projects).

    (info) Note: in practice, this option is rarely useful and should not be confused with the more common Default Reporter. You can only specify one catch email address and one issue type per mail handler.

    Bulk

    This option only affects 'bulk' email messages whose header has either its Precedence: field set to bulk or its Auto-Submitted field set to no. Such messages would typically be sent by an automated service. When such an email message is received, the following action will be performed, based on the option you choose:

    1. Ignore the email and do nothing.
    2. Forward the email (i.e. to the address set in the Forward Email text field).
    3. Delete the email permanently.
    Forward Email

    If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.

     

    Create Users

    Select this check box if you want JIRA to create new user accounts from any received email messages whose From: field contains an address that does not match one associated with an existing JIRA user account. This allows the creator of the email message to be notified of subsequent updates to the issue, which can be achieved by configuring the relevant project's notification scheme to notify the Reporter of updates.

    The username and email address of these newly created JIRA user accounts will be the email address specified in the From: field of the message. The password for the new user is randomly generated, and an email is sent to the new user informing them about their new account in JIRA.

    Users created this way will be added to the 'jira-users' group and given application access to JIRA (and therefore take up a license).

    (info) Note: this option is not compatible with Default Reporter field option below and as such, choosing the Create Users option will hide the Default Reporter option.

    Default Reporter

    Specify the username of a default reporter, which will be used if the email address in the From: field of any received messages does not match the address associated with that of an existing JIRA user — for example, a JIRA username such as emailed-reporter

    (info) Note:

    • This option is not available if the Create Users check box is selected.
    • Please ensure that the user specified in this field has the Create Issues project permission for the relevant Project (specified above) as well as the Create Comments project permission for the other relevant projects to which this mail handler should add comments.
    Notify Users

    Clear this check box if you do not want JIRA to send out an email message notifying users whose accounts have been created by the Create Users option above.

    (info) Note: this option only functions if the Create Users check box has been selected.

  3. Test and save your mail handler (above).

Create a new issue from each email message

This message handler creates a new issue for each incoming message.

To configure an 'Create a new issue from each email message' mail handler:

  1. If you have not already done so, begin configuring your mail handler (above).
  2. On the Create a new issue from each email message dialog box, complete the following fields/options:

    Project

    Specify the project key of the default project to which new issues are created by this handler — for example, JRA.

    (info) Note:

    • This field is only relevant for issue creation, not for issue commenting.
    • If an email message contains an issue key in its subject line and that issue key exists in your JIRA installation, the handler will add the email message content as a comment on the issue, regardless of which project the issue is in.
    Issue TypeChoose the default issue type for new issues.
    Catch Email Address

    If specified, only email messages whose To:, Cc:, Bcc: lines contain the recipient specified in this field will be processed — for example, issues@mycompany.com

    Upon specifying an address here, all email messages whose To:, Cc:, Bcc: lines contain addresses other than the Catch Email Address are ignored. This is useful if you have multiple aliases for the same mail account (e.g. foo-support@example-co.com and bar-support@example-co.com aliases for support@example-co.com) for multiple mail services (e.g. each one to create issues in separate JIRA projects).

    (info) Note: in practice, this option is rarely useful and should not be confused with the more common Default Reporter. You can only specify one catch email address and one issue type per mail handler.

    Bulk

    This option only affects 'bulk' email messages whose header has either its Precedence: field set to bulk or its Auto-Submitted field set to no. Such messages would typically be sent by an automated service. When such an email message is received, the following action will be performed, based on the option you choose:

    1. Ignore the email and do nothing.
    2. Forward the email (i.e. to the address set in the Forward Email text field).
    3. Delete the email permanently.
    Forward Email

    If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.

     

    Create Users

    Select this check box if you want JIRA to create new user accounts from any received email messages whose From: field contains an address that does not match one associated with an existing JIRA user account. This allows the creator of the email message to be notified of subsequent updates to the issue, which can be achieved by configuring the relevant project's notification scheme to notify the Reporter of updates.

    The username and email address of these newly created JIRA user accounts will be the email address specified in the From: field of the message. The password for the new user is randomly generated, and an email is sent to the new user informing them about their new account in JIRA.

    Users created this way will be added to the 'jira-users' group and given application access to JIRA (and therefore take up a license).

    (info) Note: this option is not compatible with Default Reporter field option below and as such, choosing the Create Users option will hide the Default Reporter option.

    Default Reporter

    Specify the username of a default reporter, which will be used if the email address in the From: field of any received messages does not match the address associated with that of an existing JIRA user — for example, a JIRA username such as emailed-reporter

    (info) Note:

    • This option is not available if the Create Users check box is selected.
    • Please ensure that the user specified in this field has the Create Issues project permission for the relevant Project (specified above) as well as the Create Comments project permission for the other relevant projects to which this mail handler should add comments.
    • When an issue is created and this option is specified, the email message's From: field address is appended in a brief message at the end of the issue's Description field, so that the sender can be identified.
    Notify Users

    Clear this check box if you do not want JIRA to send out an email message notifying users whose accounts have been created by the Create Users option above.

    (info) Note: this option only functions if the Create Users check box has been selected.

    CC Assignee

    Select this check box if you want JIRA to automatically assign the issue created to a JIRA user:

    • Who's email address (registered with their JIRA account) matches the first matching address encountered in the  To: , then Cc: and then Bcc: field of the email message received.
    • Who also has the Assignable User project permission for the relevant Project (specified above).
    CC Watchers

    Select this check box if you want JIRA to automatically add JIRA users to the issue created, where those users' email addresses (registered with their JIRA accounts) match addresses encountered in the To:, Cc: or Bcc: fields of the email message received.

    (info) Please note that when an issue is created, new JIRA users created by the Create Users option (above) cannot also be added to the issue's watchers list by this CC Watchers option. JIRA users must already exist in JIRA's userbase, and must have an email address.

  3. Test and save your mail handler (above).

Add a comment before a specified marker or separator in the email body

This message handler creates a comment from the body of an email message - but ignores any part of the body past a marker or separator that matches a specified regular expression (regex).

For mail systems like Lotus Notes and Outlook, the core content of an email message is separated from other (e.g. replied or forwarded) content in the body by some predictable text string like '---- Original Message ----' or 'Extranet\n email.address/DOM/REG/CONT/CORP@CORPMAIL'. Hence, use this message handler, which can take any valid regex, to filter core from extraneous content from various different mail systems.

Also note that the issue to which the comment is added is chosen from the first issue key found in the email subject.

The Add a comment before a specified marker or separator in the email body mail handler has the following behavior with respect to received email messages:

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

To configure an 'Add a comment before a specified marker or separator in the email body' mail handler:

  1. If you have not already done so, begin configuring your mail handler (above).
  2. On the Add a comment before a specified marker or separator in the email body dialog box, complete the following fields/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.

    (info) Please Note:

    • 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 is not (as yet) an escape syntax.

    For example:

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

    or

    /_____________*/
    Catch Email AddressIf specified, only email messages whose To:, Cc:, Bcc: lines contain the recipient specified in this field will be processed — for example, issues@mycompany.com

    Upon specifying an address here, all email messages whose To:, Cc:, Bcc: lines contain addresses other than the Catch Email Address are ignored. This is useful if you have multiple aliases for the same mail account (e.g. foo-support@example-co.com and bar-support@example-co.com aliases for support@example-co.com ) for multiple mail services (e.g. each one to create issues in separate JIRA projects).

    (info) Note: In practice, this option is rarely useful and should not be confused with the more common Default Reporter. You can only specify one catch email address and one issue type per mail handler.

    Bulk

    This option only affects 'bulk' email messages whose header has either its Precedence: field set to bulk or its Auto-Submitted field set to no. Such messages would typically be sent by an automated service. When such an email message is received, the following action will be performed, based on the option you choose:

    1. Ignore the email and do nothing.
    2. Forward the email (i.e. to the address set in the Forward Email text field).
    3. Delete the email permanently.
    Forward Email

    If specified, then if this mail service is unable to handle an email message it receives, an email message indicating this problem will be forwarded to the email address specified in this field.

    Create Users

    Select this check box if you want JIRA to create new user accounts from any received email messages whose From: field contains an address that does not match one associated with an existing JIRA user account. This allows the creator of the email message to be notified of subsequent updates to the issue, which can be achieved by configuring the relevant project's notification scheme to notify the Reporter of updates.

    The username and email address of these newly created JIRA user accounts will be the email address specified in the From: field of the message. The password for the new user is randomly generated, and an email is sent to the new user informing them about their new account in JIRA.

    Users created this way will be added to the 'jira-users' group and given application access to JIRA (and therefore take up a license).

    (info) Note: this option is not compatible with Default Reporter field option below and as such, choosing the Create Users option will hide the Default Reporter option.

    Default Reporter

    Specify the username of a default reporter, which will be used if the email address in the From: field of any received messages does not match the address associated with that of an existing JIRA user — for example, a JIRA username such as emailed-reporter

    (info) Note:

    • This option is not available if the Create Users check box is selected.
    • Please ensure that the user specified in this field has the Create Issues project permission for the relevant Project (specified above) as well as the Create Comments   project permission for the other relevant projects to which this mail handler should add comments.
    Notify Users

    Clear this check box if you do not want JIRA to send out an email message notifying users whose accounts have been created by the Create Users option above.

    (info) Note: this option only functions if the Create Users check box has been selected.

  3. Test and save your mail handler (above).

 

Issue/comment creation

The following points describe how JIRA processes each incoming email message and determines how its content gets added as either a comment to an existing issue or a new issue altogether.

  • The subject  of an email message is examined for an existing issue key:
    • If an issue key is found in the subject, the content of the email message's body is processed and added as a comment to the issue with that issue key.
    • If an issue key is NOT found in the subject, the in-reply-to header  is examined:
      • If the email message is found to be a reply to another email message from which an issue was previously created, the body is processed and added as a comment to that issue.
      • If the email message is NOT found to be a reply, a new issue is created.

For example, an email message to a mail account foo@example-co.com on a POP or IMAP mail server configured against a JIRA server will be processed as follows:

  • Issue Creation:
    • The subject of the email message will become the issue summary.
      (warning) Since all issues require a summary, each email message intended for issue creation should include a subject.
    • The body of the email message will be the issue description.
    • A bug will be created for project 'JRA' with the above information. (This is essentially based on the mail handler configuration above).
    • Any attachments to the email message will become attachments to the issue (assuming attachments have been enabled in JIRA).
      (info) To ensure compatibility with various operating systems, any of the following characters in the filename will be replaced with an underscore character: \, /, ", %, :, $, ?, *, <, |, >.
    • 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.
  • Comment Creation:
    • The body of the email will become a comment on the issue.
    • Any attachments to the email will become attachments to the issue (assuming attachments  have been enabled in JIRA).

Handy tips with mail handlers

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

  1. Create an 'anonymous'/'dummy' mail account on your mail server/service (above).
  2. Create an equivalent 'anonymous'/'dummy' JIRA user account, whose Email field matches the mail account you created in the previous step.
  3. When configuring your mail handler(s) (above) to handle messages from this mail account, set the Default Reporter to this 'anonymous'/'dummy' JIRA user account.

Best practices (pre-processing JIRA email messages)

For JIRA production servers, we recommend that setting up the following email message pre-processing:

Back up messages to a folder

  • Since JIRA mail handlers remove successfully processed email messages from your mail server, ensure that your mail is sent to a backup folder so that a record of what mail JIRA processed is available.

Set up filters to avoid mail loops

  • If your mail folder contains replies to JIRA's 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.
    There is no bulletproof way of detecting whether an email is a bounce or autoreply. The following rules (in procmail format) will detect most autoreplies:

    ^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 autoreplies 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 filters for large attachments

  • 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.
    In practice this problem is rarely seen, because most mail servers are configured to not accept email with huge attachments. 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 filters

  • Set up spam filtering rules, so JIRA does not have to process (and possibly create issues from) spam.

Troubleshooting

 

Whenever you create a new (or edit an existing) mail handler (above), a Test button is available to allow you to test your mail handler's configuration to ensure it works as expected.

 

Common problems

 

 

Last modified on Dec 4, 2015

Was this helpful?

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