Project

General

Profile

RedmineReceivingEmails » History » Version 88

Go MAEDA, 2018-01-21 07:45
Updated redmine:email:receive_imap options

1 40 Etienne Massip
h1. Receiving emails
2 1 Jean-Philippe Lang
3 4 Jean-Philippe Lang
{{>toc}}
4
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
* Forwarding emails from your email server:
12
13
  * 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
  * 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
* Reading emails from standard input:
22
23
  * Pros: fine for testing purpose
24
  * Cons: slow (the environment is reloaded each time an email is read), needs some configuration on your MTA
25 4 Jean-Philippe Lang
26
h3. Forwarding emails from your email server
27
28
A standalone script can be used to forward incoming emails from your mail server.
29 84 Go MAEDA
This script reads a raw email from the standard input and forwards 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
32
In order to use it, you have to enable the API that receive emails:
33
Go to _Application settings_ -> _Incoming emails_, check *Enable WS for incoming emails* and enter or generate a secret key.
34
35 46 Jean-Philippe Lang
36
37
38
39
40
41
42
43 85 Go MAEDA
Copy @rdm-mailhandler.rb@ to your mail server, make sure its permissions allow execution (@chmod +x rdm-mailhandler.rb@), 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 78 Go MAEDA
Usage: rdm-mailhandler.rb [options] --url=<Redmine URL> --key=<API key>
49 1 Jean-Philippe Lang
50 82 Go MAEDA
Required arguments:
51
    -u, --url URL               URL of the Redmine server
52
    -k, --key KEY               Redmine API key
53
54
General options:
55
        --key-file FILE         full path to a file that contains your Redmine
56
                                API key (use this option instead of --key if
57
                                you don't want the key to appear in the command
58
                                line)
59
        --no-check-certificate  do not check server certificate
60
        --certificate-bundle FILE
61 78 Go MAEDA
                                certificate bundle to use
62 76 Jannik Lorenz
    -h, --help                  show this help
63
    -v, --verbose               show extra information
64
    -V, --version               show version information and exit
65 1 Jean-Philippe Lang
66 78 Go MAEDA
User and permissions options:
67 76 Jannik Lorenz
        --unknown-user ACTION   how to handle emails from an unknown user
68 1 Jean-Philippe Lang
                                ACTION can be one of the following values:
69
                                * ignore: email is ignored (default)
70 76 Jannik Lorenz
                                * accept: accept as anonymous user
71
                                * create: create a user account
72 1 Jean-Philippe Lang
        --no-permission-check   disable permission checking when receiving
73 78 Go MAEDA
                                the email
74
        --default-group GROUP   add created user to GROUP (none by default)
75 76 Jannik Lorenz
                                GROUP can be a comma separated list of groups
76
        --no-account-notice     don't send account information to the newly
77
                                created user
78
        --no-notification       disable email notifications for the created
79 1 Jean-Philippe Lang
                                user
80
81
Issue attributes control options:
82 76 Jannik Lorenz
        --project-from-subaddress ADDR
83 81 Go MAEDA
                                select project from subaddress of ADDR found
84 78 Go MAEDA
                                in To, Cc, Bcc headers
85 1 Jean-Philippe Lang
    -p, --project PROJECT       identifier of the target project
86
    -s, --status STATUS         name of the target status
87
    -t, --tracker TRACKER       name of the target tracker
88 76 Jannik Lorenz
        --category CATEGORY     name of the target category
89 1 Jean-Philippe Lang
        --priority PRIORITY     name of the target priority
90 78 Go MAEDA
        --assigned-to ASSIGNEE  assignee (username or group name)
91
        --fixed-version VERSION name of the target version
92
        --private               create new issues as private
93
    -o, --allow-override ATTRS  allow email content to set attributes values
94 76 Jannik Lorenz
                                ATTRS is a comma separated list of attributes
95 78 Go MAEDA
                                or 'all' to allow all attributes to be
96
                                overridable (see below for details)
97 6 Jean-Philippe Lang
</pre>
98 5 Jean-Philippe Lang
99
See [[RedmineReceivingEmails#Issue-attributes|Issue-attributes]] for a list of values that can be used for the @--allow-override@ option.
100
101
Examples:
102
103
<pre>
104
  # No project specified. Emails MUST contain the 'Project' keyword:
105 86 Go MAEDA
  rdm-mailhandler.rb --url http://redmine.domain.foo --key secret
106 5 Jean-Philippe Lang
  
107
  # Fixed project and default tracker specified, but emails can override
108
  # both tracker and priority attributes:
109 86 Go MAEDA
  rdm-mailhandler.rb --url https://domain.foo/redmine --key secret \\
110
                     --project foo \\
111
                     --tracker bug \\
112
                     --allow-override tracker,priority
113 1 Jean-Philippe Lang
</pre>
114 54 Art Kuo
115 55 Art Kuo
Here is an example for a Postfix local alias entry:
116 35 Justin Clarke
117
<pre>
118
foo: "|/path/to/rdm-mailhandler.rb --url http://redmine.domain --key secret --project foo"
119 36 Justin Clarke
</pre>
120 35 Justin Clarke
121 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.
122 35 Justin Clarke
123
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:
124 1 Jean-Philippe Lang
125 75 Baz T.Miner
* create a mapping in @/etc/virtual@ like: @ foo@example.org foo@
126 34 Thomas Guyot-Sionnest
* modify @/etc/postfix/main.cf@ to specify a transport file: @transport_maps = hash:/etc/postfix/transport@
127 1 Jean-Philippe Lang
* within the transport file add a line like: @ foo@example.org local:@
128
129 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.
130 1 Jean-Philippe Lang
131 68 Denis Savitskiy
h3. Fetching emails from an IMAP server
132 20 Kurt Miebach
133 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:
134
135 68 Denis Savitskiy
<pre>
136 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 
137 68 Denis Savitskiy
</pre>
138 33 Jürgen Hörmann
139 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.
140 20 Kurt Miebach
141 25 Roland ...
<pre>
142 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 
143 6 Jean-Philippe Lang
</pre>
144 1 Jean-Philippe Lang
145 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. 
146 20 Kurt Miebach
147 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.
148
149
It can be necessary that you open the firewall on the machine for outgoing TCP connections to IMAP port 143.
150 72 Sebastian Paluch
151 1 Jean-Philippe Lang
Available IMAP options:
152 6 Jean-Philippe Lang
<pre>
153 1 Jean-Philippe Lang
  host=HOST                IMAP server host (default: 127.0.0.1)
154 29 Jean-Philippe Lang
  port=PORT                IMAP server port (default: 143)
155
  ssl=SSL                  Use SSL? (default: false)
156
  starttls=STARTTLS        Use STARTTLS? (default: false)
157 1 Jean-Philippe Lang
  username=USERNAME        IMAP account
158 29 Jean-Philippe Lang
  password=PASSWORD        IMAP password
159 1 Jean-Philippe Lang
  folder=FOLDER            IMAP folder to read (default: INBOX)
160 20 Kurt Miebach
  move_on_success=MAILBOX  move emails that were successfully received
161 6 Jean-Philippe Lang
                           to MAILBOX instead of deleting them
162
  move_on_failure=MAILBOX  move emails that were ignored to MAILBOX
163
</pre>
164
165 88 Go MAEDA
User and permissions options:
166
<pre>
167
  unknown_user=ACTION      how to handle emails from an unknown user
168
                           ACTION can be one of the following values:
169
                           ignore: email is ignored (default)
170
                           accept: accept as anonymous user
171
                           create: create a user account
172
  no_permission_check=1    disable permission checking when receiving
173
                           the email
174
  no_account_notice=1      disable new user account notification
175
  default_group=foo,bar    adds created user to foo and bar groups
176
</pre>
177
178 18 Eric Davis
Issue attributes control options:
179
<pre>
180
  project=PROJECT          identifier of the target project
181 88 Go MAEDA
  project_from_subaddress=ADDR
182
                           select project from subaddress of ADDR found
183
                           in To, Cc, Bcc headers
184
  status=STATUS            name of the target status
185 53 Jean-Philippe Lang
  tracker=TRACKER          name of the target tracker
186 1 Jean-Philippe Lang
  category=CATEGORY        name of the target category
187
  priority=PRIORITY        name of the target priority
188 88 Go MAEDA
  assigned_to=ASSIGNEE     assignee (username or group name)
189
  fixed_version=VERSION    name of the target version
190
  private                  create new issues as private
191
  allow_override=ATTRS     allow email content to set attributes values
192 20 Kurt Miebach
                           ATTRS is a comma separated list of attributes
193 88 Go MAEDA
                           or 'all' to allow all attributes to be overridable
194 6 Jean-Philippe Lang
</pre>
195
196
See [[RedmineReceivingEmails#Issue-attributes|Issue-attributes]] for a list of values that can be used for the @allow-override@ option.
197 11 Thomas Lecavelier
198 6 Jean-Philippe Lang
Examples for the rake command:
199 1 Jean-Philippe Lang
200
<pre>
201 6 Jean-Philippe Lang
  # No project specified. Emails MUST contain the 'Project' keyword:
202
  
203
  rake redmine:email:receive_imap RAILS_ENV="production" \\
204 11 Thomas Lecavelier
    host=imap.foo.bar username=redmine@somenet.foo password=xxx
205 6 Jean-Philippe Lang
206
207
  # Fixed project and default tracker specified, but emails can override
208
  # both tracker and priority attributes:
209 18 Eric Davis
  
210
  rake redmine:email:receive_imap RAILS_ENV="production" \\
211
    host=imap.foo.bar username=redmine@somenet.foo password=xxx ssl=1 \\
212
    project=foo \\
213 1 Jean-Philippe Lang
    tracker=bug \\
214
    allow_override=tracker,priority
215
216
  # Move successful emails to the 'read' mailbox and failed emails to
217
  # the 'failed' mailbox
218
  
219
  rake redmine:email:receive_imap RAILS_ENV="production" \\
220 37 Benjamin Haskell
    host=imap.foo.bar username=redmine@somenet.foo password=xxx \\
221 1 Jean-Philippe Lang
    move_on_success=read move_on_failure=failed
222 45 Mischa The Evil
223 29 Jean-Philippe Lang
</pre>
224
225
226
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.
227
228
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.
229
230
h3. Fetching emails from a POP3 server
231
232
A rake task (@redmine:email:receive_pop3@) can be used to fetch incoming emails from a POP3 server.
233
234
Available POP3 options:
235
<pre>
236
  host=HOST                POP3 server host (default: 127.0.0.1)
237
  port=PORT                POP3 server port (default: 110)
238
  username=USERNAME        POP3 account
239
  password=PASSWORD        POP3 password
240
  apop=1                   use APOP authentication (default: false)
241 23 Roland ...
  delete_unprocessed=1     delete messages that could not be processed
242 1 Jean-Philippe Lang
                           successfully from the server (default
243
                           behaviour is to leave them on the server)
244
</pre>
245
246 6 Jean-Philippe Lang
See the IMAP rake task above for issue attributes control options.
247
248
h3. Reading emails from standard input
249
250
A rake task (@redmine:email:receive@) can be used to read a single raw email from the standard input.
251
252
<pre>
253
Issue attributes control options:
254
  project=PROJECT          identifier of the target project
255
  tracker=TRACKER          name of the target tracker
256 1 Jean-Philippe Lang
  category=CATEGORY        name of the target category
257 52 Jean-Philippe Lang
  priority=PRIORITY        name of the target priority
258
  allow_override=ATTRS     allow email content to override attributes
259 6 Jean-Philippe Lang
                           specified by previous options
260 1 Jean-Philippe Lang
                           ATTRS is a comma separated list of attributes
261 6 Jean-Philippe Lang
</pre>
262
263
See [[RedmineReceivingEmails#Issue-attributes|Issue-attributes]] for a list of values that can be used for the @allow-override@ option.
264 1 Jean-Philippe Lang
265 6 Jean-Philippe Lang
Examples:
266
267
<pre>
268
  # No project specified. Emails MUST contain the 'Project' keyword:
269
  rake redmine:email:read RAILS_ENV="production" < raw_email
270
271
  # Fixed project and default tracker specified, but emails can override
272 23 Roland ...
  # both tracker and priority attributes:
273 45 Mischa The Evil
  rake redmine:email:read RAILS_ENV="production" \\
274 1 Jean-Philippe Lang
                  project=foo \\
275 44 Mischa The Evil
                  tracker=bug \\
276 1 Jean-Philippe Lang
                  allow_override=tracker,priority < raw_email
277 44 Mischa The Evil
</pre>
278 1 Jean-Philippe Lang
279 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.
280 44 Mischa The Evil
281
h3. Enabling unknown users to create issues by email
282
283
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:
284 1 Jean-Philippe Lang
<pre>
285 44 Mischa The Evil
unknown_user=ACTION     how to handle emails from an unknown user where ACTION can be one of the following values:
286
                        ignore: the email is ignored (default)
287 60 Philipp erpel
                        accept: the sender is considered as an anonymous user and the email is accepted
288
                        create: a user account is created for the sender (username/password are sent back to the user) and the email is accepted
289
</pre>
290
291
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.
292 45 Mischa The Evil
293 44 Mischa The Evil
If you receive emails via the rake task, the unknown-user option has to be written as:
294 1 Jean-Philippe Lang
<pre>
295
 unknown_user=[ignore|accept|create]
296
</pre>
297 57 Antoine Beaupré
298 44 Mischa The Evil
You can disable permission checking using the 'no_permission_check' option:
299 57 Antoine Beaupré
<pre>
300 44 Mischa The Evil
no_permission_check=1   disable permission checking when receiving the email
301
</pre>
302
303
This, together with the 'unknown-user', provides the ability to let anyone submit emails to a private project. For example:
304 45 Mischa The Evil
<pre>
305 86 Go MAEDA
rdm-mailhandler.rb --unknown-user accept --no-permission-check --project=foo
306 1 Jean-Philippe Lang
</pre>
307 58 Terence Mill
308
will let anyone submit emails to a private project 'foo'.
309
310
TODO: Is this true and is this related to the @no_permission_check@ option?:
311
> 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.
312 70 Pierre Maigne
313
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:
314
<pre>
315 86 Go MAEDA
rdm-mailhandler.rb --unknown-user accept --no-permission-check --project=foo --no-account-notice
316 70 Pierre Maigne
</pre>
317
318
h3. Schedule email receiving with Rufus Scheduler
319
320
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.
321 84 Go MAEDA
This is using less resources and faster than calling the Rake task from a cron (or from the Task Scheduler on Windows).
322 70 Pierre Maigne
323
To do that, install rufus-scheduler gem:
324
<pre>gem install rufus-scheduler</pre>
325
326
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.)
327
<pre>
328
require 'rubygems'
329
require 'rake'
330
require 'rufus-scheduler'
331
332
load File.join(Rails.root, 'Rakefile')
333
334
ENV['host']='pop.toto.com'
335
ENV['port']='110'
336
ENV['ssl']='SSL'
337
ENV['username']='redmine@toto.com'
338
ENV['password']='azerty123456'
339
340
scheduler = Rufus::Scheduler.new
341
# Check emails every 10 mins
342
scheduler.interval '10m' do
343
  task = Rake.application['redmine:email:receive_pop3']
344
  task.reenable
345
  task.invoke 
346
end
347 1 Jean-Philippe Lang
</pre>
348
349 12 Eric Davis
Restart your Redmine instance and your incoming emails will be retrieved on schedule.
350 1 Jean-Philippe Lang
351
You can check "Rufus-Scheduler":https://github.com/jmettraux/rufus-scheduler for scheduling syntax.
352 3 Jean-Philippe Lang
353 43 Mischa The Evil
h2. How it works
354 38 Dave Thomas
355 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.
356
357 79 Go MAEDA
If the email subject contains something like "Re: *[xxxxxxx !#123]*" or "[!#123]", the email is processed as a reply and a note is added to issue !#123. Otherwise, a new issue is created.
358 1 Jean-Philippe Lang
359 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.
360
361 1 Jean-Philippe Lang
h3. Target project
362
363 84 Go MAEDA
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.
364 28 Ethan Fremen
365
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"@.
366 1 Jean-Philippe Lang
367
Example (email body):
368
369
<pre>
370
This is a new issue that will be added to project foo.
371 16 Jean-Philippe Lang
Here we have the issue description
372
[...]
373
374
Project: foo
375
</pre>
376
377
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.
378
Example:
379 14 Jean-Philippe Lang
380 1 Jean-Philippe Lang
<pre>
381 75 Baz T.Miner
  # Create issues on project foo by default
382
  rake redmine:email:receive_imap [...] project=foo allow_override=project
383
</pre>
384
385
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.
386
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.
387
388 1 Jean-Philippe Lang
h3. Target Project from Email Sub-Address
389 75 Baz T.Miner
390 87 Go MAEDA
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. 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.
391 75 Baz T.Miner
392
To enable this feature add the @project_from_subaddress=redmine@somenet.foo@ to the command e.g.
393
394
<pre>
395
    rake redmine:email:receive_imap [...] project_from_subaddress=redmine@somenet.foo
396
</pre> 
397
398
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:
399
400
<pre>
401 15 Jean-Philippe Lang
    rake redmine:email:receive_imap [...] project=bar project_from_subaddress=redmine@somenet.foo
402
</pre> 
403 8 Jean-Philippe Lang
404 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.
405
406
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.
407
408
h3. Issue attributes
409 1 Jean-Philippe Lang
410 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. 
411
412
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).
413
414
Once @allow_override@ has been configured, you can override those attributes by using the appropriate keywords in the email body.
415 1 Jean-Philippe Lang
416
Example keyword list:
417 69 Denis Savitskiy
418
* @Project@
419
* @Tracker@
420 80 Sören Weber
* @Status@
421 73 Mathieu Janson
* @Category@
422 1 Jean-Philippe Lang
* @Priority@
423 80 Sören Weber
* @Assigned to@
424 66 Deoren Moor
* @Start date@
425 71 Toshi MARUYAMA
* @Due date@
426 66 Deoren Moor
* @Target version@
427 8 Jean-Philippe Lang
* @Estimated hours@
428
* @Done ratio@
429 28 Ethan Fremen
* @<Custom field name>@
430 8 Jean-Philippe Lang
431
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).
432
433 1 Jean-Philippe Lang
Example (email body):
434 8 Jean-Philippe Lang
435 1 Jean-Philippe Lang
<pre>
436
This is a new issue that overrides a few attributes
437
[...]
438
439 66 Deoren Moor
Project: foo
440
Tracker: Bug
441
Priority: Urgent
442
Status: Resolved
443
</pre>
444
445
The format for keywords differs from the allowed attribute values for the @allow_override@ option:
446
447
* @project@
448
* @tracker@
449 1 Jean-Philippe Lang
* @status@
450 66 Deoren Moor
* @category@
451 80 Sören Weber
* @priority@
452 1 Jean-Philippe Lang
* @assigned_to@
453 66 Deoren Moor
* @start_date@
454
* @due_date@
455 80 Sören Weber
* @fixed_version@ (aka. Target version)
456 66 Deoren Moor
* @estimated_hours@
457
* @done_ratio@
458 80 Sören Weber
* @<custom_field_name>@
459 66 Deoren Moor
460
Multiple attribute values can be specified in order to allow only certain keywords to be used.
461
462 49 Jean-Philippe Lang
Example:
463 1 Jean-Philippe Lang
464
<pre>
465
  # Allow overriding project, tracker, status & priority
466 16 Jean-Philippe Lang
  rake redmine:email:receive_imap [...] allow_override=project,tracker,status,priority
467 42 Mischa The Evil
</pre>
468 41 Miguel Filho
469 16 Jean-Philippe Lang
h3. Watchers
470
471
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.
472
473 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.
474 55 Art Kuo
475
h3. Email format and attachments
476
477 1 Jean-Philippe Lang
Redmine tries to use the plain text part of the email to fill the description of the issue.
478 65 Toshi MARUYAMA
If a HTML-only email is received, HTML tags are removed from its body.
479 1 Jean-Philippe Lang
480
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.
481
482
h3. Truncate emails
483
484
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)
485 87 Go MAEDA
486
h2. See also
487
488
* [[MailhandlerSubAddress|Mailhandler Frontend for SubAddressing]]: How to implement sub-addressing in Redmine <3.2