Mail Handler

Mail Handler for ScriptRunner allows users to run groovy scripts when a message is received, expanding on Jira’s built-in mail handling capabilities. The Mail Handler processes incoming mail, automating tasks such as creating a new issue from the mail subject, creating users from the recipient list, or triggering workflow actions.

Add an Incoming Mail Handler

  1. Navigate to System→Incoming Mail→Add Incoming Mail Handler from the Administration menu.

  2. Specify a Name for the handler.

  3. In Server, select either a POP3/IMAP mail server or the Local Files option (for an external service that writes messages to the file system).

  4. Specify the Delay (in minutes); this is the frequency at which the mail handler runs.

  5. In Handler, select ScriptRunner Mail Handler.

  6. Select Next to add or write a custom groovy script.

Configuring a Mail Handler

  1. Specify a Catch Email. Mail Handler only processes email messages whose To:, Cc:, or Bcc: lines contain the recipient specified in this field.

  2. Provide a Forward Email address. An email is sent to the given address if an error occurred during Mail Handler execution.

    This functionality is available for IMAP/POP3 configuration only.

  3. Check the Strip Quotes option to remove quoted text from the message body, and populate the context variable nonQuotedMessageBody (use this is exclude content from previous email replies).

  4. Check Create Users to create new Jira users based on the From email address, if the message comes from an unrecognized address.

  5. In Bulk, select the action that occurs for emails with the precedence Bulk, or emails with the Auto-Submitted header.

  6. To enter a script manually, type the script in the Script Console.

    Alternatively, click the File tab on the Script Console to upload a script file. Start typing the name of the file into the Script File field.

    The file must be accessible on the server.

The ScriptRunner Mail Handler provides the following binding variables:

  • message - The email message the handler is going to handle. message is an instance of javax.mail.Message.

  • messageHandlerContext - Jira utility class which helps to create issues, comments, and attachments etc.

  • nonQuotedMessageBody - A non-quoted message body contains lines that do not start with a '>' or '|'.

For help writing mail handler scripts, and details of utility methods, such as retrieving senders, body, and attachments from messages, see Atlassian MailUtils.

On this page