Documentation for JIRA 5.2. Documentation for other versions of JIRA is available too.

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

Issues and comments in JIRA can be generated either from:

  • email messages sent to an account on a POP or IMAP mail server, or
  • messages written to the file system generated by an external mail service.

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. (warning) Note that this is not possible if you are using External User Management.

Once you have created a mail account on a POP or IMAP mail server, configure JIRA to receive email from that mail server account.

(tick) Tip: You can configure JIRA's mail servers so that recipients of email notifications can simply reply to these messages and have the body of their replies added as comments to the relevant issue. To do this, simply set the From address in JIRA's SMTP mail server to match that of the POP or IMAP mail server's account being monitored. In most cases, this means having JIRA's SMTP and POP or IMAP mail servers use the same mail account. Details on how to configure JIRA to handle these emailed replies is mentioned below.

File system messages

To set up issue and comment creation from messages written to the file system by an external mail service, your external mail service must be able to write these messages within the import/mail subdirectory of the JIRA Home Directory.

External mail services are very much like the POP or IMAP services above, except that instead of email messages being read from a mail account, they are read from a directory on the disk. External mail services are useful because they overcome the potential security risks associated with anonymous mail accounts. Instead you can simply configure your external mail service to dump incoming email messages within the JIRA Home Directory's import/mail subdirectory, which is scanned periodically.

Please also be aware that JIRA expects only one message per file, so your external mail service should be configured to generate such output.

(info) Please 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.

On this page:

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 Administration at the top right of your screen. Then choose System > Mail > Incoming Mail to open the 'Incoming Mail' page.
    (tick) Keyboard shortcut: g + g + start typing incoming mail
  3. Click the Configure new 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.
  11. Click the Add / Save button to save your mail handler.

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

  • A JIRA mail handler is part of a JIRA service. Hence, when you create a mail handler, its service will appear as an entry on the Services page.
  • Be aware that editing mail handlers can only be performed through the Mail Handlers page (described above).
  • On the Mail Handlers page, clicking the Delete link associated with a mail handler removes that handler. Since a mail handler is part of a service, then if you delete a mail handler's service on the Services page, its associated handler will also be removed from the Mail Handlers page.

Mail handlers

 JIRA provides the following default mail handlers:

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) Please 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 QuotesSelect 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.
    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) Please 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.

    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.

    (info) Please Note: An SMTP mail server must be configured for this option to function correctly.

    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.

    (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) Please 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 Create a new issue or add a comment to an existing issue 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) Please 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.

    (info) Please Note: An SMTP mail server must be configured for this option to function correctly.

    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.

    (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) Please 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 Create a new issue or add a comment to an existing issue 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) Please 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.

    (info) Please Note: An SMTP mail server must be configured for this option to function correctly.

    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.

    (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) Please 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 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) Please 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) Please 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.

    (info) Please Note: An SMTP mail server must be configured for this option to function correctly.

    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.

    (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) Please 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 behaviour 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 Create a new issue or add a comment to an existing issue 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) Please 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.

    (info)  Please Note: An SMTP mail server must be configured for this option to function correctly.

    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.

    (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)  Please 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).

Custom mail handlers

You can design your own message handlers to better integrate your own processes into JIRA. Such custom mail handlers configured using the standard procedure above.

For more information about creating custom mail handlers, see Adding your own email handling classes.

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

Allowing JIRA to handle email messages from people without a JIRA user account

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:

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

  • 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 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 filtering rules, so JIRA does not have to process (and possibly create issues from) spam.

Troubleshooting

JIRA's Logging & Profiling page has configuration options for Outgoing and Incoming mail.

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.

A useful tip for debugging mail-related problems in JIRA is to set the -Dmail.debug=true property on startup. This will cause protocol-level details of JIRA's email interactions to be logged in catalina.out (or standard output).

Common problems

  • If JIRA does not appear to be creating sending emails or creating issues and comments from email, your JIRA instance could be experiencing OutOfMemory errors. Please check your log files for OutOfMemory errors. If there are OutOfMemory errors, please restart JIRA and investigate the errors.
  • If you find some incoming emails simply disappear, check that you have not accidentally started a second copy of JIRA (e.g. in a staging environment) which is downloading and deleting mails. See the Disable email sending/receiving section of the Restoring Data page for flags you should set to prevent mail being processed.
  • If replies by email of JIRA's notifications list JIRA's SMTP server rather than the configured handler POP account (ie, in Outlooks' 'Reply-to' functionality), the project needs to be configured to add a 'reply-to' header in outgoing notifications. This can be configured in the project view for that particular project in JIRA's Administration.
  • If HTML/Rich Text formatting is not being process correctly by JIRA, this is an expected behaviour. The email comment handler was designed to do plain text conversion.

Getting help

If you cannot resolve a problem yourself, please refer to the Getting Help page.



See our Getting Help page for details.



Raise an issue for our developers.



See answers from the community.



Tweet, blog and update our documentation.

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.