Creating Issues and Comments from Email

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. Select 'Administration' > 'System' > 'Mail' > 'Mail Servers'.
   Keyboard shortcut: 'g' + 'g' + type 'ma'
3. Click the 'Configure new POP / IMAP mail server' link. This will bring up the 'Add POP / IMAP Mail Server' page (see Configuring JIRA to Receive POP or IMAP Mail).
4. Fill in as follows:
   • 'Name:' enter a short descriptive name, possibly just the email address that will be collected by this service
   • 'Description:' enter a short phrase that describes this service, probably 'Email Issue Creation/Comments for <Project>'.
   • 'Host Name:' enter the name of your POP or IMAP mail server
   • 'Username' and 'Password:' use the email account details as created in 'Step One' above.
     Note that the use of SSL is specified later in the service, not here in the Mail Server.
     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.
5. Click the 'Add' button.
6. This will bring you back to the 'Mail Servers' page, where you should see a new POP or IMAP server listed towards the end of the page. You can edit and delete this server here.
7. From the top menu, select 'System' > 'Advanced' > 'Services'.
8. This will bring up the 'Services' page (see Services). It lists the current services running on this system. On a vanilla system there should be one service running — 'Mail Queue Service', which cannot be deleted. Additionally, if you have enabled the option to automatically backup JIRA's data, you will also see the 'Backup Service' listed here too.
9. 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.
10. Click the 'Add Service' button.
11. This will bring up the 'Edit Service' screen to configure the service.
    

    • 'Handler' — select "Create Or Comment Handler" from the drop down box. In the 'Handler parameters' field, set Handler parameters to something like:

      project=JRA, issuetype=1, catchemail=foo@example-co.com, createusers=true, bulk=forward

      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.
12. Click the 'Update' button and the service will be in effect.

Issue/Comment Creation

JIRA scans each incoming email to determine whether to create a new issue or to add a comment to an existing issue.

• The email subject is examined for an existing issue key.
• If an issue key is found in the subject, the email is added as a comment to the existing issue.
• If an issue key is NOT found in the subject, the in-reply-to header is examined.
  If this email is found to be a reply to another email from which an issue was previously created, a comment is added to the existing issue.
• If not, a new issue is created.

For example, the email to foo@example-co.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: \, /, ", %, :, $, ?, *, <, |, >.
  • 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 attachmentshave been enabled in JIRA)

    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.

This is how JIRA determines whether an email should

Handler Parameters

project parameter is the project key.

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 reporterusername to point to this account. When the "reporterusername" parameter is specified, the "from" e-mail address is appended to the issue description field when the issue is created, so you can identify the sender.
  Please make sure the specified user has permission to create issues or comments in the project in question. See Managing Project Permissions.
• 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 or Cc 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, if it cannot find a match in the To field. 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 email address specified in this field. Upon specifying an address here, all other email addresses are ignored. This is useful if you have multiple aliases for the same email Inbox, eg. foo-support@example-co.com and bar-support@example-co.com aliases for support@example-co.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.
• stripquotes --- This option enables the use of the NonQuotedCommentHandler to strip previous messages from replies.

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:

  ^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 (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 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 behavior. The email comment handler was designed to do plain text conversion.

Getting Help

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

Additional Resources

• JIRA Extendable Mail Plugin.