In the config subdirectory of the Redmine root directory, you will find the configuration.yml.example file. Copy (or just rename) it to configuration.yml:

$ cp configuration.yml.example configuration.yml

Now, open this file in your favorite console editor.

As you can see, it is divided into three blocks: default, production, and development. The production and development blocks are for environment-specific configuration and the default block combines the configuration options of all environments. As we are not going to have any specific configurations for the environments, we will use the default block.

The email configuration section starts under the email_delivery keyword. In this section you will find commented sample configurations, one of which you can use for your Redmine installation. The only option that is used in all the samples is delivery_method, which determines the type of delivery.

The delivery_method option accepts the following values: :sendmail, :smtp, :async_sendmail, and :async_smtp. The :async_sendmail and :async_smtp methods deliver emails in separate threads, thus not making users wait for the delivery to complete. Hence, asynchronous methods should be used on installations that involve the delivery of a large number of emails, when a mail (SMTP) server is slow or hardly accessible, or if you are experiencing slow loading of pages that send emails (for example, when you update an issue , when you create a wiki page, and so on).

From the aforementioned delivery methods, I personally recommend the use of :sendmail or :async_sendmail, as these methods will use the sendmail system tool. This tool is a standard part of Mail Transfer Agent (MTA) (software that performs mail delivery); that is, it ships with MTA and uses MTA to send emails. In other words, with the sendmail tool, you use the default delivery configuration of the operating system. So, if a system administrator modifies the email delivery configuration of the system, Redmine will automatically use it without any changes on its side. Additionally, such a configuration is easier to maintain as you don't have to care about separate email settings in Redmine:

default:email_delivery:
    delivery_method: :sendmail

You can also use a local or remote SMTP server by choosing the :smtp or :async_smtp delivery method. In this case, you will additionally need to specify smtp_settings to let Redmine know how to connect to the server.

So, let's review the options that can be specified inside the smtp_settings block:

When you finish editing the configuration.yml file, don't forget to save it and restart Redmine.

Let's check out the Email notifications tab again. Now it should look as shown in the following screenshot:

These settings are very important as email notifications can annoy users and multiple emails from a single source can be treated as spam. So, let's review them in detail.

The value of the Emission email address setting is going to be used as the sender address in email messages, which will be sent from your Redmine. So, its default value, which you can see in the preceding screenshot, should definitely be changed! Normally, people set it to something like [email protected], but I would recommend using a real email address here, for example, the email address of your support staff.

If the Blind carbon copy recipients (bcc) setting is disabled, notification recipients will be able to see who else has been sent a copy of this notification (what could be treated as a disclosure). So, it's normally a good idea to leave this setting enabled.

The Plain text mail (no HTML) setting can be used to make Redmine send all email notifications in the plain text format, that is, without rich text formatting, links, and so on.

However, the most important setting is perhaps the Default notification option. It determines which notification mode will be set for new users. As practice shows, users rarely change this setting in their profiles, so the option you choose here is most likely going to be used for most of your users. Let's review the supported modes in detail (also see Chapter 9, Personalization):

All modes, except No events, will still send notifications to users if they are explicitly watching the object that generates these notifications (for example, an issue).

The Select actions for which email notifications should be sent block contains the list of events about which Redmine will notify users. Only administrators (and only on this tab) can determine which actions will generate notifications. In other words, if you leave, for example, the News added event disabled here, users will never receive emails with any news about any projects (they will need to check it out using the project page or news feeds)! Therefore, I personally recommend that you enable all the available actions here. Otherwise, people may subscribe to some objects assuming that they will get emails on particular events and then get frustrated with the absence of such emails. So, let it be the users who control which notifications they can get.

The next two blocks are self-explanatory. They contain text that will be inserted into the email before and after the notification message. Be sure to change http://hostname/my/account to the actual URL here.

Once you have finished configuring the email notifications, you can click on the Send a test email link to check whether the email delivery works, and how it works. This link will send a test message to the email address that you have specified in your Redmine account.

Redmine issues have an optional Due date attribute. So what about being notified of the issue due date in advance? Let's do it?

Redmine ships with so-called rake tasks—small Ruby tools intended for different specific tasks that can or should be performed from the console. It also comes with a rake task that can be used to generate notifications about upcoming issue due dates. The name of this task is redmine:send_reminders, and it accepts the following options:

The syntax of the command that runs the redmine:send_reminders task is as follows:

$ rake redmine:send_reminders days=7 tracker=1 project=book users=1,5 versions=1.0.0 RAILS_ENV=production

Now, let's configure our Redmine to remind all users about the issue due dates a day before they are due, but not on weekends. So, open crontab (the file that specifies commands that should be run periodically) using the following command:

$ crontab -e

$ sudo crontab -u www-data -e

The preceding command will open an editor. Add the following two lines there:

0 10 * * 1-4 /usr/local/bin/rake -f /usr/share/redmine/Rakefile redmine:send_reminders days=1 RAILS_ENV=production
0 10 * * 5 /usr/local/bin/rake -f /usr/share/redmine/Rakefile redmine:send_reminders days=3 RAILS_ENV=production

Run which rake to determine the path to the rake tool on your server. Be sure to also replace /usr/share/redmine/ with the correct path to Redmine if you are not using the Redmine package. When you're done, save the changes and exit the editor.

So what do these lines mean? The first line will be executed at 10:00 a.m. on Mondays, Tuesdays, Wednesdays, and Thursdays, and the second line will be executed at 10:00 a.m. on Fridays.

Also note that this rake task will generate reminder emails for issues, the due dates of which are within the specified number of days. So, if you choose 7 days, users will get notifications about issues that are due in 6 days and in 1 day. Running such a task (with days=7) every day can really annoy your users. That's why we chose one day in the preceding example. In other words, you should execute this task once in the specified number of days; that is, if you use days=7, execute it only, for example, on Mondays.

In incoming emails Redmine expects to see mainly new issues. In addition to issues, Redmine can import issue comments and forum board messages from emails. So, when you receive a notification about a new issue, you can just reply to it and the message that you'll send will be added as a note to this issue. In the same way, you can answer someone's note or other changes in an issue, or someone's message in forums.

To create a new issue, Redmine needs to know values of several required attributes, that is, the tracker, status, and priority. Luckily, the default values for these attributes can be specified in the tools that are going to be used to process incoming emails. But what if your Redmine also requires some custom fields? Besides, will it not be too limiting to have hardcoded values of such attributes for all issues created via email?

To mitigate the issues that were just mentioned, Redmine can recognize attributes in the message body and supports many more attributes than just the required ones. Check out the sample email 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: 2016-01-01
Due date: 2016-01-18
Estimated time: 20
Done ratio: 50
Custom field: Value

Additionally, values for the issue attributes can be specified in the replies to existing issues. Certainly, whether changes will be applied to the issue, as well as whether a new issue with the specified attribute values will be created, depends on the permissions of the user who authors the email (the user is identified by the from email address). Also, to allow changes to the project, tracker, status, priority, and issue category in the email body, you need to list all of these attributes in the allow_override or --allow-override argument for the appropriate tool (see Forwarding emails from mail server and Fetching emails from IMAP/POP3 subsections).

To prevent attributes and their values from appearing in issue descriptions, issue notes, and forum messages, Redmine allows you to configure which lines the message text should be truncated after. The corresponding lines should be specified under the Incoming emails tab of the Settings page, that is shown in the following screenshot:

Thus, for our preceding example, we could specify These are attributes: here to remove attributes from the issue description or issue note. Of course, such delimiters are to be negotiated with users.

Also, if the incoming email includes To and/or CC addresses that are registered in Redmine (that is, there exist user accounts with such emails), the corresponding users will automatically be added to the watchers list of the issue. However, this does not happen for replies.

Finally, if the email includes attachments, they will be attached to the corresponding issue or forum message. Of course, the attachment size limit that is specified on the General tab of the Settings page is applied to such attachments as well. Additionally, on the Incoming emails tab, which was discussed earlier, you can specify the list of wildcarded filenames to skip while importing attachments from emails.

The majority of popular Mail Transfer Agents (MTAs) can forward incoming email to a third-party script as soon as it arrives in the inbox. And the rdm-mailhandler.rb tool, which I have mentioned before, is a script that should be used in this way. When the MTA forwards the email to this tool, rdm-mailhandler.rb builds a special HTTP request containing the email message and transmits it to a special web service (WS) of Redmine. Then, this web service processes the message and performs the appropriate action (for example, creates an issue).

So first, we need to enable the mentioned web service in Redmine. This can be done on the Incoming emails tab of the Settings page, that is shown in the preceding screenshot. There, you should check the Enable WS for incoming emails checkbox and then click on the Generate a key link. This will make Redmine generate a special key that will be needed to access the web service.

When ready, copy the rdm-mailhandler.rb tool to your mail server and put it into /usr/local/sbin. If it's a different server (that is, not the one that Redmine runs on), make sure that you have everything needed to run a Ruby script. If not, install whatever is missing.

But before we proceed, we will check out what arguments are supported by this tool. Let's start with the mandatory ones:

Now, let's see what optional arguments are available:

The rdm-mailhandler.rb script is intended to be executed in the shell, that is, it's just a console script. So here is a sample of the command:

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

The rest of configuration depends on which mail transfer agent are you using. As we can't review all the available MTAs here, let's assume that you are using Postfix, which is configured to use a plain-text file for aliases, such as /etc/aliases.

So, 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 book --url http://mastering-redmine.com --key mvF868NBavZZVWinIejC"

Here, issues is the username part of the email address (the full address can look like [email protected]). The string that starts with the pipe (|) instructs Postfix to forward messages that come to this email address to the standard input of the rdm-mailhandler.rb tool.

After this, your Redmine should be able to receive issues, notes, and forum messages via email.

Nowadays, many companies host their email on external mail servers that they do not own (for example, on Google). So, it's impossible for them to integrate the rdm-mailhandler.rb tool with the server's MTA. Especially for such cases, Redmine provides two additional rake tasks that can fetch emails from remote IMAP and POP3 servers. As the IMAP protocol is more advanced, the IMAP rake task has more features than the POP3 one, but which one to use depends on what protocol is supported by your mail server. Many servers (including Gmail) support both.

So let's see what the command for fetching emails from IMAP looks like:

$ rake redmine:email:receive_imap host=imap.gmail.com port=993 ssl=1 [email protected] password=LIIWLmedev6M9yAJ RAILS_ENV=production

Now, let's review the options that are available for the IMAP and POP3 rake tasks. Here they are:

The IMAP protocol allows moving email messages between server folders. To use this feature, the IMAP rake task supports the following additional options:

Now that we know what options we can use, let's make the rake task check the IMAP server for new emails once in an hour. To do this we'll add it into cron using the command:

$ crontab -e

This command will open the editor. Add there a line that looks like this:

45 * * * * /usr/local/bin/rake -f /opt/redmine/redmine-3.2.0/Rakefile --silent redmine:email:receive_imap host=imap.gmail.com port=993 ssl=1 [email protected] password=LIIWLmedev6M9yAJ unknown_user=create allow_override=project,tracker,status,category,priority RAILS_ENV=production

This line tells cron to run the redmine:email:receive_imap rake task on the 45th minute of every hour. Here, /usr/local/bin/rake is the full path to the rake tool, which can be obtained using the which rake command, and /opt/redmine/redmine-3.2.0 is the root directory of the Redmine installation. Also, make sure you replace the credentials with your own ones.

The redmine:email:receive_pop3 rake task can be run in a very similar way.