JIRA Advanced Mail Handler
5.0 (23 Avr 2015)
Brice Copy, CERN / Montserrat Gonzalez Corral, CERN
Plugin JAR advanced-mail-handler-4.0.jar
Description and Features
The JIRA Advanced Mail Handler is an extension of the standard JIRA email handler; it allows users to define many fields of the newly created issue (reporter, project key, type, priority, affected components, etc.) directly in the body of the email message. Hence, one of its notable features is that you do not need to repeat the whole process (opening a mail account on your mailserver, creating a mail account in JIRA, associate a handler service to the mail account and configure it) for each project you have in your JIRA installation; you just do the process once, setting a global mail account and handler service that will receive messages for all projects.
This tool was developed exclusively for CERN needs, and was not intended to be used by anyone else. In the best open source spirit, knowing it might be useful for others, I made it available to the community. Hence it is available "as is" under BSD license, with no guarantees whatsoever; you are welcome to download and use it, however, neither CERN nor the author (I) guarantees any support.
This software is not under active development, so no bugfix or new feature are planned for release. But if you are interested in helping out with the whole project feel free to contact me.
You don't need to compile the source code yourself unless of course you want to customize it. The code has been written for the JDK 1.6 and utilizes Maven for the build: use the command
mvn clean package to generate (in the
target directory) the file
Simply upload the JAR to your production instance (Administration > Manage add-ons > Upload add-on).
Configuration is performed through the included OSGI configuration text files.
To comment an already existing issue, the usage is the same as the default handler: just mention the issue number in the
Subject: of the email message. The body of the email will become the comment on the issue. You can also send attachments with your email, which will become attachments on the issue (if attachments have been enabled in JIRA).
On the other hand, the Advanced Mail Handler allows you to define several fields when creating an issue. This is done by adding one or more tags in the text of the
Subject: header, in the format #TAG-NAME=tag-value or #TAG-NAME=tag-value1,tag-value2,tag-value3....
Some user reported problems when sending HTML email messages. I recommend that you use plaintext format whenever possible (which is also recommended by the Netiquette).
You can specify the project in two ways:
- by addressing the message to project-key <email@example.com>. This address can be put in the
Bcc:header at your choice.
- by adding the tag #PROJECT=project-key at the end of the
Subject:header. This overrides the project key in the address.
- by adding the tag #PROJECT=project-key at the top of your email body.
You always send the email to firstname.lastname@example.org (or the address defined in the
jiraalias parameter as well); what changes is that in the first way you add the project key as the Full Name part of the address.
For your comfort, you can create an entry in your address book for each project you're working on, with the project key as the Full Name and email@example.com (which will be the same for all projects) as the Email Address.
If you do not specify a valid project, the issue is created in the default project defined as the
jiraalias parameters have the purpose to ensure that a message was addressed to JIRA, so that spam does not go processed or, worse, ends up as an issue to the default project. If you see an
ERROR [cern.jira.emailhandler.MessageParser] Jira email address not found amongst recipients in the logs, you specified these parameters incorrectly or you are sending the email message to the wrong address.
As with the standard handler, you write the Summary of the issue in the
Subject: of the email.
If you do not write any summary, the issue will be created with a summary text "(no summary)". However, it is recommended that you put a meaningful summary so all JIRA users can identify the issue.
Subject: header can also contain several tags (explained further), which will not be included in the summary. These tags must be separated by spaces, and may be in any order.
You should not use special characters (letters with acute/grave accents, diaeresis, tilde, etc.) in the subject line. Please use only ASCII-7 characters.
As with the standard handler, you write the full Description of the issue in the body of the email.
You can also send attachments with your email, which will become attachments on the issue (if attachments have been enabled in JIRA).
As with the standard handler, the Reporter of the issue is identified as the sender of the email (you).
However, you might have more than one JIRA account associated with your email address, you might want to indicate another person as reporter, or you might be sending the email from another email account. In this case, you can explicitly specify the reporter by adding the tag #REPORTER=username at the end of the
As with the standard handler, the first Cc'ed person that is also a valid Jira user and a valid assignee for the concerned project becomes the Assignee.
As one person can have multiple JIRA usernames associated with his email account, you can explicitly set the assignee's username by adding the tag #ASSIGNEE=username in the
Subject: header. This overrides the Cc'ed assignee.
If you do not specify any valid assignee, the issue is assigned to the Default Assignee.
You can specify the issue Type by adding one of the following tags to the
Subject: #BUG, #NEWFEATURE, #IMPROVEMENT, #TASK, or #SUBTASK.
If you do not specify it, the issue will be of the type specified in the
You can specify the Priority of the issue by adding one of the following tags to the
Subject: #BLOCKER, #CRITICAL, #MAJOR, #MINOR, or #TRIVIAL.
This option was managed by the default handler by looking at the
X-Priority: header of the email, but I implemented it as such because many mailclients do not permit to set custom headers easily.
You can associate an issue to one or more Components of the project by adding the tag #COMPONENT=component-name to the
Subject:. To specify multiple components, separate the components by a comma, as in #COMPONENT=first-component-name,second-component-name,third-component-name. Note that there is no space inside the whole tag.
If you specify no or invalid component, the issue gets associated by default to No Component.
To set a time Estimate to the issue, add the tag #EST=time-estimate. For instance, #EST=1h.
To set a Due Date to the issue, add the tag #DUE=YYYY-MM-DD.
List of Supported tags
|Tag Name||Description||Example values|
|#COMPONENTS||Set the issue component(s)||#COMPONENTS=component1,component2|
|#ASSIGNEE||Set the issue assignee, by JIRA user id||#ASSIGNEE=bcopy|
|#REPORTER||Set the issue reporter, by JIRA user id||#REPORTER=jsimpson|
|#WATCHERS||List of watchers to be added to the issue||#WATCHERS=bcopy,jsimpson|
|#PROJECT||Create the issue in the given project (by project key)||#PROJECT=ENS|
|#VERSIONS||Set the "affected versions" field||#VERSIONS=1.2.0,2.1.1|
|#FIXVERSIONS||Set the "fix versions" field||#FIXVERSIONS=1.2.1,2.1.2|
|#DUEDATE||Set the issue DUE DATE using ISO date format (YYYY-MM-DD)||#DUEDATE=2017-08-20|
|#ESTIMATE||Set the estimated issue duration (in JIRA duration units)||#ESTIMATE=5h|
|#SUMMARY||Overrides the email subject to use this ISSUE SUMMARY instead||#SUMMARY=My replacement issue summary|
|Set the issue type.||#ISSUETYPE=BUG|
|Set the issue priority.||N/A|
|#RESOLVE||Mark the issue as RESOLVED.|
If you cannot get the Advanced Mail Handler to work, try the following:
- Read again this instruction page and the comments; it is easy to miss something the first time.
- Examine the JIRA logs to see what is going wrong.
- Check the incoming email in the mail server account (where the Advanced Mail Handler fetches the mail from).
- Try to uninstall the Advanced Mail Handler and to use the default mail handler instead. If it fails too, chances are that some of your JIRA components (email server, services, project keys...) are misconfigured. In this case, escalate the problem and ask the general JIRA support for help.
- Using the Advanced Mail Handler, see if the problem persists when sending an email message in plaintext and with no attachments, as MIME parts may confuse the handler.
Tips and Tricks
If you prefer to have one email address for each project, like the standard email handler, just proceed as follows.
Create a mail server account for the first project, add a new mail handler and associate the Advanced Create or Comment Handler to it, as explained in the Configuration section above. Specify the email address as the
jiraemail parameter and the project as the
project parameter. Repeat the process for each project.
You can find the old version of the Advanced Mail Handler, which also contains the old wiki as documentation.
The zip file contains also a patch for the Estimate and Due Date tags. You'll have to apply the patch on the source code, then recompile it. Note that the Advanced Mail Handler 2.3 was written for Java 1.4.2_12 for compatibility issues with Tomcat. You can find a Windows version of the
patch tool as a part of the GnuWin32 package. (These instructions are given here for your convenience; I haven't tried them.)
Notes and changelog
|4.0||September 23, 2013||6.1.7|
Compiled and tested by Vladimir Vasilyev (CERN).
February 12, 2012
Compiled and tested by Rafal Piotr Niesler (CERN).
August 17, 2010
Compiled and tested by Rafal Piotr Niesler (CERN).
March 30, 2010
Compiled and tested by Brice Copy.
March 19, 2009
June 4, 2007
First public release by Daniele Raffo.