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

Skip to end of metadata
Go to start of metadata

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

On this page:

Mail Service Configuration

Step One:

To set up issue and comment creation via email, you will need to create a mail account on your server (usually one mail account for each project). For example, for the 'ABC' project, you might establish an account abc-issues@yourcompany.com. This mail box should be accessible via POP, IMAP, or on the local filesystem. JIRA will periodically scan this mail box, and appropriately create issues or comments for any emails it finds, and optionally create new user accounts for senders not previously seen (note that this is not possible if you are using External User Management).

Step Two:

Once you have established a mail account, here is how to configure JIRA to periodically scan it (POP access assumed):

  1. Log in as a user with the 'JIRA Administrators' global permission.
  2. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
  3. On the panel on the left, under the title 'Global Settings', click the link labelled 'Mail Servers'.
  4. Click the 'Configure new POP mail server' link.
  5. This will bring up the "Add POP Mail Server" page.

    Fill in as follows:
    • 'Name:' put a short descriptive name, possibly just the email address that will be collected by this service
    • 'Description:' put a short phrase that describes this service, probably 'Email Issue Creation/Comments for <Project>'.
    • 'Hostname:' put the name of your POP server
    • 'Username' and 'Password:' use the email account details as created in 'Step One' above.
      (info) Note that the use of SSL is specified later in the service, not here in the Mail Server.
      (info) If you need to set a non-standard port, this will need to be done by setting a -Dmail.pop3.port=<port> property (instead of pop3 you can specify pop3s, imap or imaps). See JRA-11037 for more on this.
  6. Click the 'Add' button.
  7. This will bring you back to the 'Email Servers' page, where you should see a new POP server listed. You can edit and delete this server here.
  8. On the panel on the left, under the title 'System', click the link labelled 'Services'.
  9. This will bring up the 'Services' page. It lists the current services running on this system. On a vanilla system there should be one service running — Mail Queue Service. You cannot delete the Mail Queue Service. Additionally, if you have enabled the option to automatically backup JIRA's data, you will also see the 'Backup Service' listed here too.
  10. Fill in the 'Add Service' form as follows:
    • 'Name' — enter a descriptive name, eg "Create Issue/Comment Service for <Project>".
    • Class — select the appropriate option presented in the drop down list, or enter com.atlassian.jira.service.services.pop.PopService,
    • Delay — this is best left as 1 minute.
  11. Click 'Add Service'.
  12. This will bring up the "Edit Service" screen to configure the service.
    • 'Handler'— select "Create Or Comment Handler" from the drop down box. Set Handler parameters to something like:

      Further details on the handler parameters are available below. If you choose to connect over SSL, you will need to import and verify the server's SSL key before JIRA will be able to connect. See Connecting to SSL Services for more information.

    • Forward Email — this parameter specifies an email address to which error notifications and (optionally) unhandled emails can be forwarded (see "bulk" parameter below). Any unhandled mails or failures encountered in this process are logged and forwarded in an email to this address.
  13. Click the 'Update' button and the service will be in effect.

Issue/Comment Creation

JIRA examines the email subject and the in-reply-to message for an existing issue reference to determine whether a new issue or comment should be created. A new issue is created if an existing issue reference is not found — otherwise, a comment is added to the issue referenced in the email. The email to foo@atlassian.com will be processed as follows:

  • Issue Creation:
    • The subject of the email will become the issue summary.
    • The body of the email will be the issue description.
    • A bug (since issue type has been set to 1 in this example) will now be created for project "JRA" with the above information.
    • Any attachments to the email will become attachments to the issue (assuming attachments have been enabled in JIRA). Note that, to ensure compatibility with various operating systems, any of the following characters in the filename will be replaced with an underscore character: \, /, ", %, :, $, ?, *, <, |, >.
  • 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 attachmentshave been enabled in JIRA)

      Icon

      The Subject of the email becomes the issue summary. As all issues require a summary, each email intended for issue creation should include a Subject.

Handler Parameters

project parameter is the project key.

Icon

The project parameter is only relevant for issue creation, not for issue commenting. If an email contains an issue key in the email subject, and that issue exists in the JIRA instance, the handler will add the email as a comment on the issue, regardless of which project the issue is in.

These are the numbers associated with the default issue types:

  • Bug: issuetype=1
  • New Feature: issuetype=2
  • Task: issuetype=3
  • Improvement: issuetype=4
  • Sub-task: issuetype=5

You can use the method described here to determine what numbers are mapped to your issue types.

Besides project and issuetype, the following parameters are allowed:

  • createusers — if createusers is set to true, people who don't currently have an account in JIRA will have it created for them. This allows the creator to be notified of subsequent updates to the issue, by configuring the notification scheme to notify the 'Reporter' of updates.
  • reporterusername — this sets which user will be the "reporter" of created issues, for emails whose sender does not match that of an existing user. Normally JIRA will ignore emails from addresses not matching an existing user. For instance, to allow anonymous users to create issues via email, you can create an anonymous user or dummy account on JIRA and set the reporterusernameto point to this account. When the "reporterusername" parameter is specified, the following occurs:
    • issue comments — the "from" address of the email is added at the end of the comment of the issue, so you can identify the sender.
    • issues — the "from" e-mail address is appended to the issue description field when the issue is created, so you can identify the sender.
  • notifyusers — this parameter is only used if createusers is set to true. If notifyusers is set to false they will not receive a notification that their account has been created via email. The default value is true to preserve the behaviour before this parameter was added.
  • ccassignee — if the To, Cc, or Bcc field of an email contains the address of a user already present in JIRA, then by default JIRA will assign the issue created from the email to that user. JIRA will attempt to assign the issue to a user from the To field first, then the Cc field and finally the Bcc field, if it cannot find a match in the To or Cc fields. If you do not wish JIRA to automatically assign issues in this way, then set ccassignee to false.
  • bulk— this parameter determines how to handle "bulk" emails (those sent by an automated service, notably JIRA itself), indicated by a "Precedence: bulk" header or an "Auto-Submitted" header that is not set to "no". Possible values are:
    • ignore — Ignore the email and do nothing
    • forward — Forward the email to the address set in the "Forward Email" text field
    • delete — Delete the email permanentlyIt 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).
  • catchemail — this causes JIRA to only process emails sent to the specified email address. All other emails are ignored. This is useful if you have multiple aliases for the same email Inbox, eg. foo-support@example.com and bar-support@example.com aliases for support@example.com, and you want one email service each, eg. to create issues in FOO and BAR projects respectively. Please note that this parameter is rarely useful, and should not be confused with the more common reporterusername.
    You can only specify one catch email address and one issue type per listener.

Other Handlers

For more information on other handlers that are shipped with JIRA please refer to this document.

Email pre-processing

For production use, we recommend that you set up the following email pre-processing:

  • Ensure mail is sent to a backup folder, so there is a record of what JIRA processed.
  • If the POP box contains email replies to JIRA notifications, set up rules filtering out email auto-replies and bounces.
    If you do not do this, there is a strong possibility of mail loops between JIRA and autoresponders like vacation scripts. JIRA sets a 'Precedence:bulk' header (unless you've 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:

    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 (eg. > 50Mb given 512Mb heap). As the unhandled mail isn't 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're sure yours won't 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 is not having to process (and possibly create issues from) spam.

Troubleshooting

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. Additionally, turning up JIRA's log level will show when the service is running and how mails are processed.

Common Problems

  • If JIRA doesn't 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 haven't accidentally started a second copy of JIRA (eg. in a staging environment) which is downloading and deleting mails. See the Restoring Data page for flags you should set to prevent mail being processed.
  • If you receive email with non-ASCII attachment names, particularly from Thunderbird users, you will need to configure JavaMail to support RFC 2231-encoded attachments. See JRA-12525 for details.

Getting Help

If you cannot resolve a problem yourself, please create a support case in the 'JIRA' project and we will assist.