Configuring Email SmartHandlers

To automate email handling in JIRA and JIRA Service Desk, install the add-on, and then configure your first SmartHandler.


  • Obtain administrator access to JIRA.
  • Configure JIRA to receive email requests.
  • Know what types of emails you will receive and the type of data they will contain.

Installing the Add-On

  1. Log in to your JIRA instance as an admin.
  2. Click the gear icon, and then click Add-ons.
  3. Search the Marketplace for SmartHandler - Email logic for Jira.
  4. Follow the on-screen instructions to buy the add-on or start the free trial for 30 days.

Creating New SmartHandlers

  1. SmartHandler should be now located as one of the standard Jira Menu options.

  2. Click SmartHandler.
  3. OPTIONAL Upload lookup tables of information that you want to use to populate Jira tickets.
  4. Click New Handler.
  5. Configure the Mail Handler settings.

    Handler SettingsProvide a unique name and a description, identify the incoming mail server, and select the format of the email body.
    Match CriteriaConfigure the rules that determine which emails this handler applies to.
    In Case of ErrorDetermine what action to take if an error prevents the handler from being applied to an incoming email.
    Turn on Score Ranges or Activity Logs?

    OPTIONAL Enable additional features for this SmartHandler.

    For more information, see Configuring Mail Handler Settings.

  6. Click Save.
  7. Click the Data Points tab, and configure the settings to extract information from an incoming email that matches this handler.
    You configure data points differently depending on the format of the incoming email message—as key-value pairs, if the message is structured, or as regular expressions, if the message is free-form text. For more information, see Configuring Data Points for Email.
  8. Click Save.
  9. Click the Actions tab, and configure the settings for what actions to take when an incoming email matches this handler.
    For more information, see Configuring Actions for Email.
  10. Click Save.

Managing SmartHandlers

  1.  Click SmartHandler from the top menu bar
    The list shows a summary of all the existing handlers, including the whether it is currently applied to incoming emails (status), whether data points are configured, and whether actions are configured.

  2. Review the configuration summary and perform any of the following options.
    • To reorder the handlers, drag the handlers to the desired order. Email handlers are applied in the order they are listed.
    • To edit a handler, click it in the list. The configuration details open, and you can review or modify them as necessary.
    • To pause a handler (stop applying it to incoming emails and keep the configuration details stored on the system), click it in the list. On the Mail Handler tab, click the running man icon  beside the handler name. The pause icon appears.

    • To start a handler (start applying it to incoming emails), click it in the list. On the Mail Handler tab, click the pause icon  beside the handler name. The running man icon appears.

    • To duplicate a handler, click it in the list. On the Mail Handler tab, click the duplicate icon . Enter a name for the new handler, and click Duplicate. You can then edit the new handler as necessary.

    • To export a handler, click it in the list. On the Mail Handler tab, click the export icon . The configuration settings are downloaded as a JSON file. You can then import these settings into another instance. See Importing SmartHandlers.

    • To delete a handler (stop applying it to incoming emails and remove the configuration details from the system), click the trash icon  beside it. Then, click Remove to confirm the deletion.

      If you delete a handler, you must recreate it if you want to start applying it again. If you may want to restore the handler in the future, consider pausing it, instead.

Importing SmartHandlers

You can import SmartHandlers to move the configuration settings between instances (for example, to promote a SmartHandler from your test instance to your production instance).

If you want to reuse similar configuration settings on the same JIRA instance, you can duplicate the handler, instead. See Managing SmartHandlers.

  1. Create, configure, and test the SmartHandler.
  2. On the Mail Handler tab, click the export icon  to download the settings as a JSON file.
  3. Use a text editing program to open the downloaded file, and copy all of the contents to your clipboard.
  4. Log in to the instance where you want to import the SmartHandler.
  5. Click the gear icon, and then click Applications.

  6. Under Integrations, click SmartHandler.

  7. If a handler with the same name already exists on the instance, do one of the following:
    • To replace the existing handler settings with the imported handler settings, click the trash icon  beside the existing handler. Then, click Remove to confirm the deletion.
    • To keep the existing handler settings and add the imported settings as a new handler, click the existing handler. Then, change the handler name, and click Save.
  8. Click Import Handler.
  9. Paste the JSON that you copied in step 3, and then click OK.

Granting Access to Edit SmartHandlers

Only JIRA system administrators can create, modify, or delete SmartHandlers.

Next Steps

  • Configure and manage additional email handlers, as necessary.
  • RECOMMENDED Monitor the activity logs and adjust handlers, as necessary.