History

Wiki »

Issues created by email

This is information from the Mastering Redmine manual.

Receiving e-mails

While the e-mail invention predates the Internet invention e-mail is still one of the primary electronic ways to communicate. Thus, having a public issue tracker for my projects I still keep getting e-mails from users describing issues. That's why, perhaps, email integration is one of the essential features of modern issue trackers. And Redmine does have it.

If you had a look at the Redmine directory structure you might notice the extra directory containing different scripts and a sample plugin. Despite of what you could think these files are not, in fact, extra tools but one of the most important features of Redmine (well, except the sample plugin). We will review all these tools in this chapter. Right now we start with the rdm-mailhandler.rb. Probably you already guessed from its name that this is the tool that implements e-mail receiving for Redmine.

In addition to the rdm-mailhandler.rb, Redmine comes with two rake tasks which also can be used for receiving emails namely redmine:email:receive_imap and redmine:email:receive_pop3.

The difference between these two primary solutions is in the method by which these tools are invoked. The rdm-mailhandler.rb was designed to be launched on a mail server by for example, Postfix, while rake tasks were designed to fetch e-mails from a mail server remotely. Of course, the tool launched by a mail server on receiving an e-mail is better for several reasons: first, it gets executed only when an email comes, that is, it does not work for nothing and, second, Redmine gets an e-mail immediately after it comes to a mail server, that is, without any delay. But the tool which fetches e-mail from a remote mail server also find its consumer especially if a remote mail server is for example, Gmail, and therefore there is no way to install the former tool there.

For the above reasons, we will review both tools here. But let's start with discussing what exactly Redmine can fetch using e-mail.

Format of incoming emails

In addition to new issues Redmine is able to recognize issue comments and board messages. That is, for example, if you are getting notifications about new issues you can just reply to a received notification and the message you will type will be added as a note to the issue. The same way you can answer someone's note or changes if you watch an issue and receive notifications about changes in it. A similar scenario is also supported for messages in forums.

If you want to receive replies through email you should change the Emission email address to the e-mail address you plan to receive e-mails on. So the notifications come from the same address and users just need to click on Reply in their e-mail clients. Of course, for a new issue to be created Redmine needs some attributes. They are, at least, tracker, subject, status, and priority (these attributes are required). Good news is that they can be specified in the tools which will be used for fetching e-mails. But what if your Redmine requires some custom fields? Besides, if you have hardcoded values of attributes would it not be too limited?

Luckily Redmine supports specifying attributes in the message body and supports many more attributes that just required ones. Let's check a sample e-mail body:

????????????Hi!
I have an issue...

   These are attributes:
   Assigned to: Andriy Lesyuk
   Tracker: Support
   Status: New
   Priority: Urgent
   Category: Email queries
   Target version: 1.0.0
   Start: 2012-07-01
   Due date: 2012-07-18
   Estimated time: 20
   Done ratio: 50
   Custom field: Value

As you see even values for custom fields can be specified.

Besides new issue e-mails the attributes can be specified in replies to existing issues as well. Of course whether changes will be applied to the issue, as well as whether a new issue will be created with the specified attributes values, depends on permissions of the user who sends the e-mail (the user gets identified by the from e-mail address).

To allow specifying project, tracker, status, priority, and category in the e-mail body you need to specify all these attributes in the allow_override or allow-override option at the command line for the appropriate tool (see below).

You probably thought that having all those attributes in the issue description or in the note text is not good. For this reason Redmine allows configuring, after which lines the description should be truncated. Go to Administration | Settings | Incoming emails tab, there can be many lines specified.

So for the preceding sample e-mail, we can specify "These are attributes:" here to remove attributes from issue description or note text. Of course, the delimiters should be negotiated with customers.

I believe the two hyphens line is essential to have here as it is often used to delimit message body from signature.

If one specifies other e-mail addresses in To or CC field and if these e-mails are registered in Redmine (there are accounts with these e-mails) the corresponding users will be added to issue watchers. However, watchers are not added
from replies.

If the e-mail has attachments these attachments will be added to an issue or to a forum message. Of course, the size limit specified in General tab at Administration | Settings is applied to such attachments as well.

Fetching e-mails through web service

Having read the title you, perhaps, asked yourself: What web service? Yes, we need the web service to receive e-mail messages which are sent by the rdm-mailhandler. rb tool. This web service needs to be enabled before we proceed. To do this go to
the Administration area using the link in the top-left menu, then open the Settings section and click on the Incoming emails tab:

Check the Enable WS for incoming emails option and then click on the Generate a key link. After that Redmine will generate a web service key for you. Click on Save.

Now copy the rdm-mailhandler.rb tool to your mail server and place it into /usr/ local/sbin. Please note that you may need to install Ruby on the mail server to be able to run this tool.

Let's now discuss arguments for this tool which should be used on the mail server. The mandatory arguments are url and key:

  • The url argument should be set to Redmine's home page URL, for example, http://redmine.packtpub.com.
  • The key argument should be set to the key we have generated above.

Also the following optional arguments are available:

  • The unknown-user option accepts values such as, ignore (the default), accept, and create. With the default ignore value, all e-mail messages which come from an e-mail that is not listed in Redmine (if it is not specified as an e-mail in any account) will be ignored. If the accept value is set, issues created from such e-mail messages will be authored by Anonymous user. And, finally, if the create value was specified new user accounts will
    be created.
  • The project option can be set to the identifier of the project in which issues will be created. If this option is not set, the project identifier should be explicitly set in the e-mail message body.
  • The tracker option can be set to the name of the tracker, which will be used for newly created issues.
  • The status option can be specified to set a different initial status for issues created from received e-mails.
  • The category option can be used to set the category for issues, which will be created from e-mails.
  • The priority option can be used to set a different priority for issues, which are created from incoming e-mails.
  • And, finally, the allow-override option can be used to limit which issue attributes can be specified in the e-mail message body. Here, the issue attributes are actually the previously listed five options: project, tracker, status, category, and priority.

So the tool should be executed in the following way:

/usr/local/sbin/rdm-mailhandler.rb --unknown-user create --project
mastering-redmine --url http://redmine.packtpub.com --key
mvF868NBavZZVWinIejC

The rest depends on what mail server you are using. As we just can't review all the available mail servers in this book let's assume you use Postfix and it is configured to use a plain text file for aliases, for example /etc/aliases. If you don't use it, please consult your system administrator on how to do this for your configuration (we need to forward messages intended for a particular email to the standard input of the rdm-mailhandler.rb).

Open the /etc/aliases file and add the following line:

   issues: "|/usr/local/sbin/rdm-mailhandler.rb --unknown-user
   create --allow-override=project,tracker,status,category,priority
   --project mastering-redmine --url http://redmine.packtpub.com --key
   mvF868NBavZZVWinIejC"

Here issues is the username part of the e-mail address (full address can be for example, ).

Getting project from e-mail address

Thomas Guyot-Sionnest developed a frontend for rdm-mailhandler.rb which supports subaddresses such as issues+mastering-redmine-@ packtpub.com. This way a project can be specified in the e-mail address, then this project is passed to rdm-mailhandler.rb with the project option. http://www.redmine.org/projects/redmine/wiki/MailhandlerSubAddress

Now you should be able to receive issues and forum messages by e-mail.

Fetching e-mails using IMAP/POP3

In some cases you may be unable to register the rdm-mailhandler.rb tool on your mail server, for example, if you use Google Apps. In these cases you can still fetch issues and forum messages from e-mails using special rake tasks. Such tasks are available for IMAP and for POP3. Which one to use depends on your mail server's capabilities but, generally, IMAP protocol is more powerful than POP3, so the IMAP rake task allows more than the POP3 one as well. Gmail supports both.

The command for fetching e-mails from IMAP looks like:

$ rake redmine:email:receive_imap host=imap.gmail.com port=993
ssl=1 username=issues@packtpub.com password=LIIWLmedev6M9yAJ
RAILS_ENV=production

Let's review options available for the IMAP and POP3 rake tasks:

  • The unknown_user option like the unknown-user option for rdm- mailhandler.rb supports values such as ignore, accept, and create. Meanings of these values are the same as for rdm-mailhandler.rb.
  • Options project, status, tracker, category, priority, and allow_ override also accept the same values and have the same meanings as the corresponding options of rdm-mailhandler.rb.
  • The host option should hold IP or hostname of the mail server. Default value is localhost.
  • The port option should contain the port number of the mail server. For IMAP the default value is 143 and for POP3 it is 110.
  • The ssl option is available only for IMAP and should be set to 1 if the IMAP server supports SSL.
  • The username and password options define credentials which should be used for connecting to IMAP or POP3 server.
  • The folder option, which can be specified for IMAP, holds the name of the folder to process. The default name is INBOX.
  • The apop option can be used to select APOP authentication for the POP3 server.

The IMAP protocol allows moving e-mail messages between server folders. Therefore these two additional options are available for IMAP:

  • The move_on_success option specifies the name of the folder where the successfully processed e-mails should be moved.
  • The move_on_failure option specifies the name of the folder where the ignored e-mail messages should be moved.

Now, when we know what options we can use, let's put the rake task into the cron to check the IMAP server once in an hour (do this under the user, which runs Redmine, or specify the username for crontab with -u option):

$ crontab -e

This command will open the editor. Add the following line there:

   45 * * * * /usr/bin/rake -f /usr/share/redmine/Rakefile --silent
   redmine:email:receive_imap host=imap.gmail.com port=993 ssl=1
   username=issues@packtpub.com password= LIIWLmedev6M9yAJ unknown_
   user=create allow_override=project,tracker,status,category,priority
   RAILS_ENV=production

This tells cron to run the rake task on 45th minute of every hour. /usr/bin/rake is the full path to the rake tool which can be obtained using which rake. /usr/share/ redmine which is the root directory of Redmine installation.

Also available in: PDF HTML TXT