E-Mail Integration

OpenProject can check an e-mail account for specially formatted mail that will perform tasks within the system. This is described in https://docs.openproject.org/installation-and-operations/configuration/incoming-emails/, though some of the stuff is not quite clear, so I'm adding notes here.

First, create an e-mail account someplace. I create two folders on the mail account, one named Processed and one named Failed.

Now OpenProject to check that account by running a cron job. It was easier for me to just create a bash script to do it since the command is fairly long. It also allows me to test the system easily.

openProject

#! /bin/bash
 
openproject run bundle exec rake --trace redmine:email:receive_imap \
   host='mail.example.org'\
   username='projects@example.org' \
   password='reallyG00D_Password?' \
   port=993 \
   ssl=true \
   allow_override=type,project \
   project=test_project \
   folder=INBOX \
   move_on_success=Processed \
   move_on_failure=Failed

What this code does is logs into mail.example.org with username projects@example.org and the password, and checks for e-mail. If no project is defined in the e-mail, it assigns the ticket to the project test_project.

If the e-mail is successfully parsed, the actions are taken and the e-mail is moved to the Processed folder on the mail server. If not, it is put in the Failed folder.

Run the script one time to verify you get no errors. You may get a warning that the hook was registered, but that is normal. Note that the script takes several seconds to run, so don't get impatient.

If you get no errors, you can either put it someplace and set up the crontab, or (on Debian based systems), put it in /etc/cron.hourly. I only wanted it to run once an hour, so I did the latter.

The format of the e-mail is very important. One thing that messed me up was the Project: field. It is not the name of the project, but is the project ID.

Some special things in the e-mail are used:

1. From: The address the e-mail comes from must match an existing user in OpenProject. This becomes the creator of the ticket.
2. Subject: The subject of the e-mail becomes the title of the ticket
3. CC: Anyone CC'd on the e-mail becomes a watcher on the task, assuming they are in the OpenProject instance
4. Attachments: If you create or update a work package via e-mail, and it has an attachment, those attachments are attached to the work package.

I'm not going to describe all of the keys (see Format of the emails in the docs link above), just the ones I care about. These will be put in the body of the e-mail,, one to a line, with a colon separating the keyword and the value. Anything not parsed this way becomes the body of the ticket.

* You can find a project ID by opening a project in OpenProject and looking at the URL. It is the last section of the URL after the word projects, ie https://project.example.com/projects/keyword-here/. You can also see it by going into Project Settings | Information, where it is listed as Identifier.