Set up incoming Redmine email using mail server forwards

Redmine Incoming Email

By configuring Redmine to receive emails, you’ll be able to create issues and comments by email. There are two main methods: forwarding messages from your mail server or fetching them from a your POP3/IMAP.

Forwarding Messages from Mail Server

In order to forward messages directly to Redmine from your mail server, you’ll need to be able to add new email aliases and you’ll need to enable the API that processes incoming messages.

To enable the API go to the incoming emails settings under the administrative menu. The URL should be http://<yourserver>/settings?tab=mail_handler. On this screen, check Enable WS for incoming emails, click Generate a key, and then save. You’ll need this API key later.


Redmine came with a standalone script, extra/mail_handler/rdm-mailhandler.rb, that can be used to forward incoming emails via HTTP. A copy of this script should be placed on your mail server and made executable.

Take a loook at rdm-mailhandler’s help documentation.

chmod +x redmine/extra/mail_handler/rdm-mailhandler.rb
./extra/mail_handler/rdm-mailhandler.rb --help

It’s long, but it’s important to see all of the available options.

Usage: rdm-mailhandler.rb [options] --url=<redmine url> --key=<api key>

Reads an email from standard input and forwards it to a Redmine server through a HTTP request.

Required arguments:
    -u, --url URL               URL of the Redmine server
    -k, --key KEY               Redmine API key
Issue attributes control options:
    -p, --project PROJECT       identifier of the target project
    -s, --status STATUS         name of the target status
    -t, --tracker TRACKER       name of the target tracker
        --category CATEGORY     name of the target category
        --priority PRIORITY     name of the target priority
    -o, --allow-override ATTRS  allow email content to override attributes
                                specified by previous options
                                ATTRS is a comma separated list of attributes

The help also includes a couple examples:

No project specified, emails MUST contain the 'Project' keyword:
rdm-mailhandler.rb --url --key secret

Fixed project and default tracker specified, but emails can override both tracker and priority attributes using keywords:
rdm-mailhandler.rb --url --key secret 
  --project foo 
  --tracker bug 
  --allow-override tracker,priority

When submitting emails, users can define various attributes that Redmine will parse and handle appropriately to create their issue or comment.

Project: Sample
Tracker: Feature
Priority: Low

If attributes such as project are missing, Redmine will not know what to do with the message. To avoid this, attributes can be locked in at the time of configuration. If you want to define values for these attributes but still allow user email content to be used when available, –allow-override can be used to identify the attributes that may be overridden.

rdm-mailhandler.rb --url http://<yourserver> --key <yourkey> 
    --project defaultproject --tracker bug --priority normal 
    –-allow-override tracker,priority

With this configuration all emails are assigned defaultproject as their project, bug as their tracker, and are given a normal priority. With allow-override here, the user could set their own tracker or priority but they cannot change the project.

To begin using this mail handler, add it as an alias in /etc/aliases.

redmine: "|/home/redmine/rdm-mailhandler.rb --url http://<yourserver> --key <yourkey> --project defaultproject --tracker bug --priority normal –-allow-override tracker,priority"

Rebuild the alias database.


Messages to redmine are now creating bug issues for defaultproject.

If you have multiple projects, can help you avoid the need for constant project overrides in your email. This script scans email headers looking for sub-addresses ( and when found, passes on the message with the project.

curl -o /home/redmine/
chmod +x /home/redmine/
Usage: -h | -e <email> [ -p <project> ] -- <command-line>

The <command-line> portion is the full rdm-mailhandler.rb command that would
normally be executed as the mail handler. The full path to the executable is
required. This command should not include a project; use the build-in
--project argument instead.

  -h, --help            show this help message and exit
  -e EMAIL, --email=EMAIL
                        Known email to look for (i.e. redmine recipient)
  -p PROJECT, --project=PROJECT
                        Default project to pass to rdm-mailhandler.rb if there
                        is no subaddress

This script goes in front of rdm-mailhander.rb in your alias. You’ll have to add the recipient’s email and the project argument moves to

redmine: "|/home/redmine/ --email redmine@<yourserver> --project defaultproject -- /home/redmine/rdm-mailhandler.rb --url http://<yourserver> --tracker bug --allow-override tracker,priority --key <yourkey>"

With this configuration, any email sent to redmine@<yourserver> will use defaultproject. If you wish to send to a particular project, you can still do so by emailing redmine+projectname@<yourserver>.

SMTP Error

With my initial configuration, I kept getting my emails bounced back.

  ----- Transcript of session follows -----
553 5.1.0 "|/home/redmine/redmine/extra/mail_handler/ --email <mydomain> --p... --tracker bug --allow-override tracker,priority,project --key <mykey>"... prescan: token too long
554 5.4.6 aliasing/forwarding loop broken

Final-Recipient: RFC822; redmine@<mydomain>
Action: failed

I was able to fix this by moving both of the scripts up a few directories so they weren’t so nested. In my case, putting them in the user’s home directory was sufficient to get Redmine email working. Just creating a symbolic link would have worked as well.

You may also want to check out:

3 responses to “Set up incoming Redmine email using mail server forwards”

Leave a Reply

Your email address will not be published. Required fields are marked *