Configuring Mail Handler Settings

Mail Handler settings determine the general properties of an email handler, including which emails the handler applies to, the expected format of the emails, and what to do if an error occurs. You configure these settings when creating a new handler or when editing an existing handler.


  • Obtain administrator access to JIRA.
  • Install the Smarthandler for Email add-on.
  • Configure JIRA to receive email requests.

  • Know what types of emails you will receive and the type of data they will contain.


  1. In JIRA, click the gear icon, and then click Applications.

  2. Under Integrations, click SmartHandler, and then do one of the following:

    • To create a new handler, click New Handler.
    • To edit an existing handler, click the row in the list.
  3. In the Handler Settings section, configure the following information.

    NameUnique identifier for the handler.
    Mail ServerWhich email inbox to monitor. The list shows all the incoming mail servers you've configured on JIRA. To monitor a different mail server, click Add and then configure it in JIRA.
    Email Parser Type

    Message format of the incoming email:

    • Key-value pairs, for structured data. For example, data from a form or auto-generated emails from an integrated system.
    • Regular expressions for free-form text.

    Brief summary of what the handler does.

  4. Click the Match Criteria section, and configure the rules that determine which emails this handler applies to.

    • Define each condition with the following information.
      • Email field to check (subject, body, email from, or email to).
      • Operator
      • Value—keyword, phrase or regular expression to match in the email field.
    • To add a condition, click the plus sign beside it. To remove a condition, click the trash icon beside it. You must have at least one condition for a handler.
    • An incoming email to the selected inbox must match at least one condition for this handler to be applied.

      Use cases for match criteria

      Match criteria allow you to handle different emails to the same inbox in different ways. For example:

      • Create a handler that creates new tickets when the email subject starts with New. Then, create a different handler that updates tickets when the email subject starts with Update.
      • Create conditions to identify emails from VIP users so that you can automatically assign a higher priority to these tickets.

      Email handlers are applied in the order they are listed.

  5. Click the In Case of Error section, and configure what to do if an error prevents the handler from being applied to an incoming email.
    • To create a ticket, select Error Ticket. Then, specify a project, reporter, issue type, and assignee for the error ticket.
    • To send an error notification email, select Forward Email. Then, specify the email address.

      The description (for a ticket) or the email body includes a description of the error along with the subject, sender, and body of the original email.

  6. (Optional) Click the Turn on Score Ranges or Activity Logs, and enable or disable the following additional features.
    • Using Score Range—enable this feature to assign a weight to each potential action. When an incoming email matches the criteria for an action, the weight is added to the total score. You can then use the cumulative score to take additional actions, as desired. For more information, see Configuring Actions for Email.
    • Show Activity Log—enable this feature to track how often the handler is applied to incoming email.

Next Steps