RedmineReceivingEmails » History » Version 77

Go MAEDA, 2017-08-22 01:24
Removed mention to very old versions.

1 40 Etienne Massip
h1. Receiving emails
2 1 Jean-Philippe Lang
3 4 Jean-Philippe Lang
{{>toc}}
4 4 Jean-Philippe Lang
5 77 Go MAEDA
Redmine can be configured to allow issue creation or comments via email. It is also able to recognize and incorporate email replies to forum messages.
6 1 Jean-Philippe Lang
7 40 Etienne Massip
h2. Setup
8 1 Jean-Philippe Lang
9 40 Etienne Massip
You can configure Redmine to receive emails in one of the following ways:
10 7 Jean-Philippe Lang
11 7 Jean-Philippe Lang
* Forwarding emails from your email server:
12 7 Jean-Philippe Lang
13 7 Jean-Philippe Lang
  * Pros: works with a remote mail server, email are processed instantly, fast (no environment reloading)
14 10 Jean-Philippe Lang
  * Cons: needs some configuration on your mail transfer agent (eg. Postfix, Sendmail...)
15 7 Jean-Philippe Lang
16 29 Jean-Philippe Lang
* Fetching emails from an IMAP or POP3 server:
17 7 Jean-Philippe Lang
18 7 Jean-Philippe Lang
  * Pros: easy to setup, no need to configure your MTA, works with a remote mail server
19 9 Jean-Philippe Lang
  * Cons: emails are not processed instantly (a cron job needs to be added to read emails periodically)
20 7 Jean-Philippe Lang
21 7 Jean-Philippe Lang
* Reading emails from standard input:
22 7 Jean-Philippe Lang
23 7 Jean-Philippe Lang
  * Pros: fine for testing purpose
24 7 Jean-Philippe Lang
  * Cons: slow (the environment is reloaded each time an email is read), needs some configuration on your MTA
25 4 Jean-Philippe Lang
26 4 Jean-Philippe Lang
h3. Forwarding emails from your email server
27 4 Jean-Philippe Lang
28 4 Jean-Philippe Lang
A standalone script can be used to forward incoming emails from your mail server.
29 4 Jean-Philippe Lang
This script reads a raw email from the standard input and forward it to Redmine via a HTTP request.
30 4 Jean-Philippe Lang
It can be found in your redmine directory: @extra/mail_handler/rdm-mailhandler.rb@.
31 4 Jean-Philippe Lang
32 4 Jean-Philippe Lang
In order to use it, you have to enable the API that receive emails:
33 4 Jean-Philippe Lang
Go to _Application settings_ -> _Incoming emails_, check *Enable WS for incoming emails* and enter or generate a secret key.
34 4 Jean-Philippe Lang
35 46 Jean-Philippe Lang
36 46 Jean-Philippe Lang
37 46 Jean-Philippe Lang
38 46 Jean-Philippe Lang
39 46 Jean-Philippe Lang
40 46 Jean-Philippe Lang
41 46 Jean-Philippe Lang
42 46 Jean-Philippe Lang
43 59 Filou Centrinov
Copy @rdm-mailhandler.rb@ to your mail server, make sure its permissions allow execution, and configure your MTA (Mail Transport Agent).
44 4 Jean-Philippe Lang
45 5 Jean-Philippe Lang
Usage:
46 4 Jean-Philippe Lang
47 1 Jean-Philippe Lang
<pre>
48 5 Jean-Philippe Lang
rdm-mailhandler [options] --url=<Redmine URL> --key=<API key>
49 1 Jean-Philippe Lang
50 76 Jannik Lorenz
Required arguments:
51 76 Jannik Lorenz
    -u, --url URL               URL of the Redmine server
52 76 Jannik Lorenz
    -k, --key KEY               Redmine API key
53 76 Jannik Lorenz
54 1 Jean-Philippe Lang
General options:
55 76 Jannik Lorenz
        --no-permission-check   disable permission checking when receiving
56 76 Jannik Lorenz
                                the email
57 76 Jannik Lorenz
        --key-file FILE         full path to a file that contains your Redmine
58 76 Jannik Lorenz
                                API key (use this option instead of --key if
59 76 Jannik Lorenz
                                you don't want the key to appear in the command
60 76 Jannik Lorenz
                                line)
61 76 Jannik Lorenz
        --no-check-certificate  do not check server certificate
62 76 Jannik Lorenz
    -h, --help                  show this help
63 76 Jannik Lorenz
    -v, --verbose               show extra information
64 76 Jannik Lorenz
    -V, --version               show version information and exit
65 1 Jean-Philippe Lang
66 76 Jannik Lorenz
User creation options:
67 76 Jannik Lorenz
        --unknown-user ACTION   how to handle emails from an unknown user
68 76 Jannik Lorenz
                                ACTION can be one of the following values:
69 76 Jannik Lorenz
                                * ignore: email is ignored (default)
70 76 Jannik Lorenz
                                * accept: accept as anonymous user
71 76 Jannik Lorenz
                                * create: create a user account
72 76 Jannik Lorenz
        --default-group GROUP   add created user to GROUP (none by default)
73 76 Jannik Lorenz
                                GROUP can be a comma separated list of groups
74 76 Jannik Lorenz
        --no-account-notice     don't send account information to the newly
75 76 Jannik Lorenz
                                created user
76 76 Jannik Lorenz
        --no-notification       disable email notifications for the created
77 76 Jannik Lorenz
                                user
78 76 Jannik Lorenz
79 5 Jean-Philippe Lang
Issue attributes control options:
80 76 Jannik Lorenz
    -p, --project PROJECT       identifier of the target project
81 76 Jannik Lorenz
    -s, --status STATUS         name of the target status
82 76 Jannik Lorenz
    -t, --tracker TRACKER       name of the target tracker
83 76 Jannik Lorenz
        --category CATEGORY     name of the target category
84 76 Jannik Lorenz
        --priority PRIORITY     name of the target priority
85 76 Jannik Lorenz
    -o, --allow-override ATTRS  allow email content to override attributes
86 76 Jannik Lorenz
                                specified by previous options
87 76 Jannik Lorenz
                                ATTRS is a comma separated list of attributes
88 6 Jean-Philippe Lang
</pre>
89 5 Jean-Philippe Lang
90 5 Jean-Philippe Lang
See [[RedmineReceivingEmails#Issue-attributes|Issue-attributes]] for a list of values that can be used for the @--allow-override@ option.
91 5 Jean-Philippe Lang
92 5 Jean-Philippe Lang
Examples:
93 5 Jean-Philippe Lang
94 5 Jean-Philippe Lang
<pre>
95 5 Jean-Philippe Lang
  # No project specified. Emails MUST contain the 'Project' keyword:
96 5 Jean-Philippe Lang
  rdm-mailhandler --url http://redmine.domain.foo --key secret
97 5 Jean-Philippe Lang
  
98 5 Jean-Philippe Lang
  # Fixed project and default tracker specified, but emails can override
99 5 Jean-Philippe Lang
  # both tracker and priority attributes:
100 54 Art Kuo
  rdm-mailhandler --url https://domain.foo/redmine --key secret \\
101 5 Jean-Philippe Lang
                  --project foo \\
102 5 Jean-Philippe Lang
                  --tracker bug \\
103 1 Jean-Philippe Lang
                  --allow-override tracker,priority
104 1 Jean-Philippe Lang
</pre>
105 54 Art Kuo
106 55 Art Kuo
Here is an example for a Postfix local alias entry:
107 35 Justin Clarke
108 35 Justin Clarke
<pre>
109 35 Justin Clarke
foo: "|/path/to/rdm-mailhandler.rb --url http://redmine.domain --key secret --project foo"
110 36 Justin Clarke
</pre>
111 35 Justin Clarke
112 36 Justin Clarke
This line should go in the aliases file, which is usually specified in @/etc/aliases@. If the location is unknown, use the command @postconf alias_maps@ to find out. After updating the aliases file, be sure to run @newaliases@ to alert Postfix of the new entry.
113 35 Justin Clarke
114 35 Justin Clarke
If your domain is setup as a virtual mailbox map (so that you use /etc/postfix/virtual_mailbox_maps to do mappings in the form @ user@example.com /path/example.com/user@) you should:
115 1 Jean-Philippe Lang
116 75 Baz T.Miner
* create a mapping in @/etc/virtual@ like: @ foo@example.org foo@
117 34 Thomas Guyot-Sionnest
* modify @/etc/postfix/main.cf@ to specify a transport file: @transport_maps = hash:/etc/postfix/transport@
118 1 Jean-Philippe Lang
* within the transport file add a line like: @ foo@example.org local:@
119 1 Jean-Philippe Lang
120 20 Kurt Miebach
*Explanation:* - When you define virtual_mailbox_maps for a domain the default transport is virtual, which means specifying a local alias in @/etc/postfix/virtual@ will fail (with "unknown user"). To fix this, we override the default transport by specifying a local transport for the email address in question, which means the local alias will resolve correctly, and your script will be executed.
121 1 Jean-Philippe Lang
122 68 Denis Savitskiy
For versions before 3.2, a front-end to rdm-mailhandler.rb has been written to allow specifying projects trough sub-addresses (name+project@example.com). See [[MailhandlerSubAddress]]. This feature is now available for all email sources (ie @RAW@, @IMAP@ and @POP@) using the @project_from_subaddress@ feature see [[RedmineReceivingEmails#Target-Project-from-Email-Sub-Address|Target Project from Email Sub-Address]] below.
123 21 Kurt Miebach
124 68 Denis Savitskiy
h3. Fetching emails from an IMAP server
125 20 Kurt Miebach
126 33 Jürgen Hörmann
A rake task (@redmine:email:receive_imap@) can be used to fetch incoming emails from an IMAP server. When you run the rake command from a cron job you can include the switch @-f /path/to/redmine/appdir/Rakefile@ on the rake command, because otherwise the rakefile is not found. This is an example line for a cron file that fetches mails every 30 minutes:
127 33 Jürgen Hörmann
128 68 Denis Savitskiy
<pre>
129 33 Jürgen Hörmann
*/30 * * * * redmineuser rake -f /path/to/redmine/appdir/Rakefile redmine:email:receive_imap RAILS_ENV="production" host=imap.foo.bar username=redmine@somenet.foo password=xxx 
130 68 Denis Savitskiy
</pre>
131 33 Jürgen Hörmann
132 22 Kurt Miebach
If your setup is working, but you receive mails from the cron daemon, you can suppress the output from the rake command by adding the --silent switch. That should stop cron sending mails on every execution of the command.
133 20 Kurt Miebach
134 25 Roland ...
<pre>
135 20 Kurt Miebach
*/30 * * * * redmineuser rake -f /path/to/redmine/appdir/Rakefile --silent redmine:email:receive_imap RAILS_ENV="production" host=imap.foo.bar username=redmine@somenet.foo password=xxx 
136 6 Jean-Philippe Lang
</pre>
137 1 Jean-Philippe Lang
138 6 Jean-Philippe Lang
The command has to go on a single line in your cronfile. Also see the other examples below, which only show the rake commands without the @-f@ option and without the cron part. 
139 20 Kurt Miebach
140 6 Jean-Philippe Lang
For Windows as server "pycron":http://www.kalab.com/freeware/pycron/pycron.htm can be used to schedule a fetch task.
141 6 Jean-Philippe Lang
142 6 Jean-Philippe Lang
It can be necessary that you open the firewall on the machine for outgoing TCP connections to IMAP port 143.
143 72 Sebastian Paluch
144 1 Jean-Philippe Lang
Available IMAP options:
145 6 Jean-Philippe Lang
<pre>
146 1 Jean-Philippe Lang
  host=HOST                IMAP server host (default: 127.0.0.1)
147 29 Jean-Philippe Lang
  port=PORT                IMAP server port (default: 143)
148 29 Jean-Philippe Lang
  ssl=SSL                  Use SSL? (default: false)
149 29 Jean-Philippe Lang
  starttls=STARTTLS        Use STARTTLS? (default: false)
150 1 Jean-Philippe Lang
  username=USERNAME        IMAP account
151 29 Jean-Philippe Lang
  password=PASSWORD        IMAP password
152 1 Jean-Philippe Lang
  folder=FOLDER            IMAP folder to read (default: INBOX)
153 20 Kurt Miebach
  move_on_success=MAILBOX  move emails that were successfully received
154 6 Jean-Philippe Lang
                           to MAILBOX instead of deleting them
155 6 Jean-Philippe Lang
  move_on_failure=MAILBOX  move emails that were ignored to MAILBOX
156 6 Jean-Philippe Lang
</pre>
157 6 Jean-Philippe Lang
158 18 Eric Davis
Issue attributes control options:
159 1 Jean-Philippe Lang
<pre>
160 18 Eric Davis
  project=PROJECT          identifier of the target project
161 18 Eric Davis
  tracker=TRACKER          name of the target tracker
162 18 Eric Davis
  category=CATEGORY        name of the target category
163 53 Jean-Philippe Lang
  priority=PRIORITY        name of the target priority
164 51 Jean-Philippe Lang
  allow_override=ATTRS     allow email content to override attributes
165 20 Kurt Miebach
                           specified by previous options
166 1 Jean-Philippe Lang
                           ATTRS is a comma separated list of attributes
167 6 Jean-Philippe Lang
</pre>
168 6 Jean-Philippe Lang
169 6 Jean-Philippe Lang
See [[RedmineReceivingEmails#Issue-attributes|Issue-attributes]] for a list of values that can be used for the @allow-override@ option.
170 11 Thomas Lecavelier
171 6 Jean-Philippe Lang
Examples for the rake command:
172 1 Jean-Philippe Lang
173 1 Jean-Philippe Lang
<pre>
174 6 Jean-Philippe Lang
  # No project specified. Emails MUST contain the 'Project' keyword:
175 6 Jean-Philippe Lang
  
176 6 Jean-Philippe Lang
  rake redmine:email:receive_imap RAILS_ENV="production" \\
177 11 Thomas Lecavelier
    host=imap.foo.bar username=redmine@somenet.foo password=xxx
178 6 Jean-Philippe Lang
179 6 Jean-Philippe Lang
180 6 Jean-Philippe Lang
  # Fixed project and default tracker specified, but emails can override
181 6 Jean-Philippe Lang
  # both tracker and priority attributes:
182 18 Eric Davis
  
183 18 Eric Davis
  rake redmine:email:receive_imap RAILS_ENV="production" \\
184 18 Eric Davis
    host=imap.foo.bar username=redmine@somenet.foo password=xxx ssl=1 \\
185 18 Eric Davis
    project=foo \\
186 1 Jean-Philippe Lang
    tracker=bug \\
187 1 Jean-Philippe Lang
    allow_override=tracker,priority
188 1 Jean-Philippe Lang
189 1 Jean-Philippe Lang
  # Move successful emails to the 'read' mailbox and failed emails to
190 1 Jean-Philippe Lang
  # the 'failed' mailbox
191 1 Jean-Philippe Lang
  
192 1 Jean-Philippe Lang
  rake redmine:email:receive_imap RAILS_ENV="production" \\
193 37 Benjamin Haskell
    host=imap.foo.bar username=redmine@somenet.foo password=xxx \\
194 1 Jean-Philippe Lang
    move_on_success=read move_on_failure=failed
195 45 Mischa The Evil
196 29 Jean-Philippe Lang
</pre>
197 29 Jean-Philippe Lang
198 29 Jean-Philippe Lang
199 29 Jean-Philippe Lang
Ignored emails are marked as 'Seen' but are not deleted from the IMAP server--these include unknown user, unknown project and emails from the redmine emission account.
200 29 Jean-Philippe Lang
201 29 Jean-Philippe Lang
The option _allow_override_ is not only for overriding default values given to rake, but for every attribute in a mail. If you want to override the tracker in your mail you have to add _allow_override=tracker_ as a parameter.
202 29 Jean-Philippe Lang
203 29 Jean-Philippe Lang
h3. Fetching emails from a POP3 server
204 29 Jean-Philippe Lang
205 29 Jean-Philippe Lang
A rake task (@redmine:email:receive_pop3@) can be used to fetch incoming emails from a POP3 server.
206 29 Jean-Philippe Lang
207 29 Jean-Philippe Lang
Available POP3 options:
208 29 Jean-Philippe Lang
<pre>
209 29 Jean-Philippe Lang
  host=HOST                POP3 server host (default: 127.0.0.1)
210 29 Jean-Philippe Lang
  port=PORT                POP3 server port (default: 110)
211 29 Jean-Philippe Lang
  username=USERNAME        POP3 account
212 29 Jean-Philippe Lang
  password=PASSWORD        POP3 password
213 29 Jean-Philippe Lang
  apop=1                   use APOP authentication (default: false)
214 23 Roland ...
  delete_unprocessed=1     delete messages that could not be processed
215 1 Jean-Philippe Lang
                           successfully from the server (default
216 1 Jean-Philippe Lang
                           behaviour is to leave them on the server)
217 1 Jean-Philippe Lang
</pre>
218 1 Jean-Philippe Lang
219 6 Jean-Philippe Lang
See the IMAP rake task above for issue attributes control options.
220 6 Jean-Philippe Lang
221 6 Jean-Philippe Lang
h3. Reading emails from standard input
222 6 Jean-Philippe Lang
223 6 Jean-Philippe Lang
A rake task (@redmine:email:receive@) can be used to read a single raw email from the standard input.
224 6 Jean-Philippe Lang
225 6 Jean-Philippe Lang
<pre>
226 6 Jean-Philippe Lang
Issue attributes control options:
227 6 Jean-Philippe Lang
  project=PROJECT          identifier of the target project
228 6 Jean-Philippe Lang
  tracker=TRACKER          name of the target tracker
229 1 Jean-Philippe Lang
  category=CATEGORY        name of the target category
230 52 Jean-Philippe Lang
  priority=PRIORITY        name of the target priority
231 52 Jean-Philippe Lang
  allow_override=ATTRS     allow email content to override attributes
232 6 Jean-Philippe Lang
                           specified by previous options
233 1 Jean-Philippe Lang
                           ATTRS is a comma separated list of attributes
234 6 Jean-Philippe Lang
</pre>
235 6 Jean-Philippe Lang
236 6 Jean-Philippe Lang
See [[RedmineReceivingEmails#Issue-attributes|Issue-attributes]] for a list of values that can be used for the @allow-override@ option.
237 1 Jean-Philippe Lang
238 6 Jean-Philippe Lang
Examples:
239 6 Jean-Philippe Lang
240 6 Jean-Philippe Lang
<pre>
241 6 Jean-Philippe Lang
  # No project specified. Emails MUST contain the 'Project' keyword:
242 6 Jean-Philippe Lang
  rake redmine:email:read RAILS_ENV="production" < raw_email
243 6 Jean-Philippe Lang
244 6 Jean-Philippe Lang
  # Fixed project and default tracker specified, but emails can override
245 23 Roland ...
  # both tracker and priority attributes:
246 45 Mischa The Evil
  rake redmine:email:read RAILS_ENV="production" \\
247 1 Jean-Philippe Lang
                  project=foo \\
248 44 Mischa The Evil
                  tracker=bug \\
249 1 Jean-Philippe Lang
                  allow_override=tracker,priority < raw_email
250 44 Mischa The Evil
</pre>
251 1 Jean-Philippe Lang
252 61 Jean-Baptiste Barth
The option _allow_override_ is not only for overriding default values given to rake, but for every attribute in a mail. If you want to override the tracker in your mail you have to add _allow_override=tracker_ as a parameter.
253 44 Mischa The Evil
254 44 Mischa The Evil
h3. Enabling unknown users to create issues by email
255 44 Mischa The Evil
256 44 Mischa The Evil
Redmine has a feature that provides the ability to accept incoming emails from unknown users. In order to use this feature, an extra parameter has to be included:
257 1 Jean-Philippe Lang
<pre>
258 44 Mischa The Evil
unknown_user=ACTION     how to handle emails from an unknown user where ACTION can be one of the following values:
259 44 Mischa The Evil
                        ignore: the email is ignored (default)
260 60 Philipp erpel
                        accept: the sender is considered as an anonymous user and the email is accepted
261 60 Philipp erpel
                        create: a user account is created for the sender (username/password are sent back to the user) and the email is accepted
262 60 Philipp erpel
</pre>
263 60 Philipp erpel
264 60 Philipp erpel
Permissions have to be consistent with the chosen option. E.g. if you choose 'create', the 'Non member' role must have the 'Add issues' permission so that an issue can be created by an unknown user via email. If you choose 'accept', the 'Anonymous' role must have this permission.
265 45 Mischa The Evil
266 44 Mischa The Evil
If you receive emails via the rake task, the unknown-user option has to be written as:
267 1 Jean-Philippe Lang
<pre>
268 1 Jean-Philippe Lang
 unknown_user=[ignore|accept|create]
269 1 Jean-Philippe Lang
</pre>
270 57 Antoine Beaupré
271 44 Mischa The Evil
You can disable permission checking using the 'no_permission_check' option:
272 57 Antoine Beaupré
<pre>
273 44 Mischa The Evil
no_permission_check=1   disable permission checking when receiving the email
274 44 Mischa The Evil
</pre>
275 44 Mischa The Evil
276 44 Mischa The Evil
This, together with the 'unknown-user', provides the ability to let anyone submit emails to a private project. For example:
277 45 Mischa The Evil
<pre>
278 47 Brett Zamir
rdm-mailhandler --unknown-user accept --no-permission-check --project=foo
279 1 Jean-Philippe Lang
</pre>
280 58 Terence Mill
281 58 Terence Mill
will let anyone submit emails to a private project 'foo'.
282 58 Terence Mill
283 58 Terence Mill
TODO: Is this true and is this related to the @no_permission_check@ option?:
284 58 Terence Mill
> Since Redmine 0.9 the project doesn't have to be public, but authentication required in the Administration-> Settings->Authentication tab has to be unchecked.
285 70 Pierre Maigne
286 70 Pierre Maigne
If you do not want an "new account notification email" sent to every newly created user by rdm-mailhandler you must add the option "--no-account-notice". Is implemneted with version#60 in issue #11498. Now an example:
287 70 Pierre Maigne
<pre>
288 70 Pierre Maigne
rdm-mailhandler --unknown-user accept --no-permission-check --project=foo --no-account-notice
289 70 Pierre Maigne
</pre>
290 70 Pierre Maigne
291 70 Pierre Maigne
h3. Schedule email receiving with Rufus Scheduler
292 70 Pierre Maigne
293 70 Pierre Maigne
Instead of using a cron to trigger the Rake task to retrieve incoming email, you can use Rufus Scheduler which will run the Rake task in the same process as Redmine.
294 70 Pierre Maigne
This is using less ressources and faster than calling the Rake task from a cron (or from the Task Scheduler on Windows).
295 70 Pierre Maigne
296 70 Pierre Maigne
To do that, install rufus-scheduler gem:
297 70 Pierre Maigne
<pre>gem install rufus-scheduler</pre>
298 70 Pierre Maigne
299 70 Pierre Maigne
Create a what_you_want.rb file in /config/initializers/ and put the following content in your file. (Here for a POP3 account. Change it with your own parameters and own task.)
300 70 Pierre Maigne
<pre>
301 70 Pierre Maigne
require 'rubygems'
302 70 Pierre Maigne
require 'rake'
303 70 Pierre Maigne
require 'rufus-scheduler'
304 70 Pierre Maigne
305 70 Pierre Maigne
load File.join(Rails.root, 'Rakefile')
306 70 Pierre Maigne
307 70 Pierre Maigne
ENV['host']='pop.toto.com'
308 70 Pierre Maigne
ENV['port']='110'
309 70 Pierre Maigne
ENV['ssl']='SSL'
310 70 Pierre Maigne
ENV['username']='redmine@toto.com'
311 70 Pierre Maigne
ENV['password']='azerty123456'
312 70 Pierre Maigne
313 70 Pierre Maigne
scheduler = Rufus::Scheduler.new
314 70 Pierre Maigne
# Check emails every 10 mins
315 70 Pierre Maigne
scheduler.interval '10m' do
316 70 Pierre Maigne
  task = Rake.application['redmine:email:receive_pop3']
317 70 Pierre Maigne
  task.reenable
318 70 Pierre Maigne
  task.invoke 
319 70 Pierre Maigne
end
320 1 Jean-Philippe Lang
</pre>
321 1 Jean-Philippe Lang
322 12 Eric Davis
Restart your Redmine instance and your incoming emails will be retrieved on schedule.
323 1 Jean-Philippe Lang
324 1 Jean-Philippe Lang
You can check "Rufus-Scheduler":https://github.com/jmettraux/rufus-scheduler for scheduling syntax.
325 3 Jean-Philippe Lang
326 43 Mischa The Evil
h2. How it works
327 38 Dave Thomas
328 15 Jean-Philippe Lang
When receiving an email, Redmine uses the From address of the email to find the corresponding user. Emails received from unknown or locked users are ignored.
329 15 Jean-Philippe Lang
330 27 Eric Davis
If the email subject contains something like "Re: *[xxxxxxx !#123]*", the email is processed as a reply and a note is added to issue !#123. Otherwise, a new issue is created.
331 1 Jean-Philippe Lang
332 16 Jean-Philippe Lang
Note that, in order to create an issue, all required custom fields must be provided. Without them, issue creation will fail. As an alternative you can ensure that every custom field has a default value which is then used during issue creation.
333 16 Jean-Philippe Lang
334 1 Jean-Philippe Lang
h3. Target project
335 1 Jean-Philippe Lang
336 1 Jean-Philippe Lang
The target project can be specified using the @project@ option when receiving emails.  This should be the identifier of the project and *not* the name.  You can easily find the identifier in the url.
337 28 Ethan Fremen
338 28 Ethan Fremen
If you don't use this option, users have to specify in the email body which project the issue should be added to. This can be done by inserting a line in the email body like this: @"Project: foo"@.
339 1 Jean-Philippe Lang
340 1 Jean-Philippe Lang
Example (email body):
341 1 Jean-Philippe Lang
342 1 Jean-Philippe Lang
<pre>
343 1 Jean-Philippe Lang
This is a new issue that will be added to project foo.
344 16 Jean-Philippe Lang
Here we have the issue description
345 16 Jean-Philippe Lang
[...]
346 16 Jean-Philippe Lang
347 16 Jean-Philippe Lang
Project: foo
348 16 Jean-Philippe Lang
</pre>
349 16 Jean-Philippe Lang
350 16 Jean-Philippe Lang
You can set a default project using the @project@ option and let users override this default project by using the @allow-override@ option when receiving emails.
351 16 Jean-Philippe Lang
Example:
352 14 Jean-Philippe Lang
353 1 Jean-Philippe Lang
<pre>
354 75 Baz T.Miner
  # Create issues on project foo by default
355 75 Baz T.Miner
  rake redmine:email:receive_imap [...] project=foo allow_override=project
356 75 Baz T.Miner
</pre>
357 75 Baz T.Miner
358 75 Baz T.Miner
Of course, user permissions are checked and this email would be ignored if the user who sent this email is not allowed to add issues to project foo.
359 75 Baz T.Miner
Make sure that the target project doesn't use *required* custom fields with no default value for its issues, otherwise the creation of the issue will fail.
360 75 Baz T.Miner
361 75 Baz T.Miner
h3. Target Project from Email Sub-Address
362 75 Baz T.Miner
363 75 Baz T.Miner
This feature was introduced in ver 3.2.0 (SVN rev r14687). It may be preferable to have one mailbox for all incoming emails to a Redmine instance, instead of one per project. For some history of this feature see [[MailhandlerSubAddress]]. When receiving emails at redmine@somenet.foo, an email sent to redmine+foo@somenet.foo will cause the issue to be added to project with identifier foo.
364 75 Baz T.Miner
365 75 Baz T.Miner
To enable this feature add the @project_from_subaddress=redmine@somenet.foo@ to the command e.g.
366 75 Baz T.Miner
367 75 Baz T.Miner
<pre>
368 75 Baz T.Miner
    rake redmine:email:receive_imap [...] project_from_subaddress=redmine@somenet.foo
369 75 Baz T.Miner
</pre> 
370 75 Baz T.Miner
371 75 Baz T.Miner
If a project is included in the command-line then it becomes the default project that will be used for emails sent to @redmine@somenet.foo@. So with the command:
372 75 Baz T.Miner
373 75 Baz T.Miner
<pre>
374 15 Jean-Philippe Lang
    rake redmine:email:receive_imap [...] project=bar project_from_subaddress=redmine@somenet.foo
375 15 Jean-Philippe Lang
</pre> 
376 8 Jean-Philippe Lang
377 74 Deoren Moor
emails to @redmine@somenet.foo@ or @redmine+bar@somenet.foo@ will raise issues in project bar; emails to @redmine+foo@somenet.foo@ will go into project foo.
378 74 Deoren Moor
379 74 Deoren Moor
Some email providers include support for sub-addresses, as per RFCs 3598, 5233. Where this is not supported, forwarding mail addresses to the 'central' address, may work (it does in my case), ie set up an email address forwarding all mails to @redmine@somenet.foo@ from @redmine+foo@somenet.foo@, @redmine+bar@somenet.foo@ etc. This is easy to administer and does not require fetching emails from multiple accounts, each with its own account credentials.
380 74 Deoren Moor
381 74 Deoren Moor
h3. Issue attributes
382 1 Jean-Philippe Lang
383 66 Deoren Moor
Based on the options you use when receiving emails (see @allow-override@ option), users may be able to override some attributes when submitting an issue. 
384 66 Deoren Moor
385 66 Deoren Moor
Note: prior to Redmine version:"3.2.0" (#20543) some attributes were _always_ overridable, but this was not documented. This behavior has been changed and all attributes have to be explicitly listed with the @allow_override@ option to be overridable. For those who want all attributes to be overridable, @allow_override=all@ can now be used (#20543).
386 66 Deoren Moor
387 66 Deoren Moor
Once @allow_override@ has been configured, you can override those attributes by using the appropriate keywords in the email body.
388 1 Jean-Philippe Lang
389 1 Jean-Philippe Lang
Example keyword list:
390 69 Denis Savitskiy
391 69 Denis Savitskiy
* @Project@
392 69 Denis Savitskiy
* @Tracker@
393 73 Mathieu Janson
* @Category@
394 69 Denis Savitskiy
* @Priority@
395 69 Denis Savitskiy
* @Status@
396 66 Deoren Moor
* @Start date@
397 71 Toshi MARUYAMA
* @Due date@
398 66 Deoren Moor
* @Target version@
399 8 Jean-Philippe Lang
* @Estimated hours@
400 8 Jean-Philippe Lang
* @Done ratio@
401 28 Ethan Fremen
* @<Custom field name>@
402 8 Jean-Philippe Lang
403 8 Jean-Philippe Lang
The values available are the ones of the context. E.g. @Status@ available (for this Tracker and this Project) are labels in the localized language, exactly as displayed in the user interface or system default language (even with spaces, without quoting).
404 8 Jean-Philippe Lang
405 1 Jean-Philippe Lang
Example (email body):
406 8 Jean-Philippe Lang
407 1 Jean-Philippe Lang
<pre>
408 1 Jean-Philippe Lang
This is a new issue that overrides a few attributes
409 1 Jean-Philippe Lang
[...]
410 1 Jean-Philippe Lang
411 66 Deoren Moor
Project: foo
412 66 Deoren Moor
Tracker: Bug
413 66 Deoren Moor
Priority: Urgent
414 66 Deoren Moor
Status: Resolved
415 66 Deoren Moor
</pre>
416 66 Deoren Moor
417 66 Deoren Moor
The format for keywords differs from the allowed attribute values for the @allow_override@ option:
418 66 Deoren Moor
419 66 Deoren Moor
* @project@
420 66 Deoren Moor
* @tracker@
421 66 Deoren Moor
* @status@
422 66 Deoren Moor
* @priority@
423 66 Deoren Moor
* @category@
424 66 Deoren Moor
* @assigned_to@
425 66 Deoren Moor
* @fixed_version@ (aka. Target version)
426 66 Deoren Moor
* @start_date@
427 66 Deoren Moor
* @due_date@
428 66 Deoren Moor
* @estimated_hours@
429 66 Deoren Moor
* @done_ratio@
430 66 Deoren Moor
431 66 Deoren Moor
Multiple attribute values can be specified in order to allow only certain keywords to be used.
432 66 Deoren Moor
433 49 Jean-Philippe Lang
Example:
434 1 Jean-Philippe Lang
435 1 Jean-Philippe Lang
<pre>
436 1 Jean-Philippe Lang
  # Allow overriding project, tracker, status & priority
437 16 Jean-Philippe Lang
  rake redmine:email:receive_imap [...] allow_override=project,tracker,status,priority
438 42 Mischa The Evil
</pre>
439 41 Miguel Filho
440 16 Jean-Philippe Lang
h3. Watchers
441 16 Jean-Philippe Lang
442 16 Jean-Philippe Lang
If the user who sends the email has the 'Add issue watchers' permission, users that are in To or Cc field of the email are automatically added as watchers of the created issue.
443 16 Jean-Philippe Lang
444 1 Jean-Philippe Lang
Watchers are added only when the issue is created. To or Cc fields are ignored on replies. See #7017 and #8009.
445 55 Art Kuo
446 55 Art Kuo
h3. Email format and attachments
447 55 Art Kuo
448 1 Jean-Philippe Lang
Redmine tries to use the plain text part of the email to fill the description of the issue.
449 65 Toshi MARUYAMA
If a HTML-only email is received, HTML tags are removed from its body.
450 1 Jean-Philippe Lang
451 1 Jean-Philippe Lang
Email attachments are automatically attached to the issue, unless their size exceeds the [[RedmineSettings#Attachment-max-size|maximum attachment size]] defined in the application settings.
452 1 Jean-Philippe Lang
453 1 Jean-Philippe Lang
h3. Truncate emails
454 1 Jean-Philippe Lang
455 1 Jean-Philippe Lang
The Administrator's settings may be used to automatically truncate emails, for example to eliminate quoted messages in forum replies. To do this, set the outgoing email header to something like @--Reply above this line--@ in the Email notifications settings. Then in the Incoming emails settings, enter the same line into the box "Truncate emails after one of these lines." (It is also possible to allow regex to be truncated, using the patch attached to #5864)