About Jira modules
Customer portal
Project settings UI locations

Message handler


JIRA 5.0 and later

In JIRA, email messages may be periodically fetched (for example, via POP or IMAP) and processed (for example, create a new issue or create a comment). You can add new ways of processing email messages by implementing the MessageHandler interface in JIRA (or subclassing one if its implementations).

Purpose of this module type

This module type enables developers to build their own custom message handlers for JIRA. JIRA includes a number of prebuilt handlers, as described in Creating Issues and Comments from Email. Developers can create their own handlers using this plugin module, as shown in Plugin Tutorial - Writing a Custom Message (Mail) Handler for JIRA

Administrators can apply the custom message handler in Administration > System > Incoming Mail pages. A message handler plugin can add specialized configuration settings through the add-edit-url module attribute, which specifies the page equivalent to this one:



The root element for the keyboard shortcut plugin module is message-handler. Its attributes are:





The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources.




In the example, appProps is the key for this particular module declaration, for component-import, in this case.

Required: yes


The localisation key for the human-readable name of the plugin module.

Required: -


The Java class of the message handler module. The custom message handler class must implement the com.atlassian.jira.service.util.handler.MessageHandler interface, or extend a class that does.

Required: -


Resource that implements the configuration UI for the handler.

Required: -


Numeric position of this handler in the handler selection list in the handler configuration page. Built-in handlers come with a weight of 1 to 5, with the lower numbers appearing first in the list.

Required: -


Here is an example of message-handler defined in atlassian-plugin.xml:

<message-handler i18n-name-key="demohandler.name" key="demoHandler" class="com.example.plugins.tutorial.jira.mailhandlerdemo.DemoHandler" add-edit-url="/secure/admin/EditHandlerDetailsUsingParams!default.jspa" weight="0"/>

A note about message handlers in JIRA 4.4 and earlier

In JIRA 4.4 and earlier, adding your own custom message handler usually required rebuilding JIRA from source or at least modification of the popservice.xml file.

Also the UI for configuring such handlers was very basic. All handler parameters had to be provided as a comma-delimited list of name-value pairs. There was no easy way to test configuration validity. See the documentation on Message Handler Plugin Module and configuring services.

For information about services in JIRA 4.4 and earlier, including MessageHandlers, links to API documentation and source of the system handlers, see the JIRA product documentation.

After writing your MessageHandler implementation, install it into JIRA as follow:

  1. Compile your handler and add it to the JIRA classpath (either as a JAR in WEB-INF/lib or as a class in WEB-INF/classes). JIRA has an external-source directory whose README describes a quick way to compile source.
  2. Add your handler to the services/com/atlassian/jira/service/services/pop/popservice.xml.
  3. Restart JIRA.

You should now be able to select your own MessageHandler when configuring a POP service.

Rate this page: