openproject/doc/operation_guides/incoming_emails.md

# Incoming E-Mails

OpenProject is able to receive e-mails and create and update work packages and reply in forums
depending on the content of the e-mail.

## Setup

Receiving e-mails is done via a rake task that fetches e-mails from an
e-mail server, parses them and performs actions depending on the content
of the e-mail. This rake task can be executed manually or automatically,
e.g. with the help of a Cron job.

### IMAP

The rake task `redmine:email:receive_imap` fetches e-mails via IMAP and
parses them.
Example:

```bash
bundle exec rake redmine:email:receive_imap host='imap.gmail.com' username='test_user' password='password' port=993 ssl=true allow_override=type,project project=test_project
```

Available arguments for this rake task that specify the e-mail behavior are

|key | description|
|----|------------|
| `host` | address of the e-mail server |
| `username` | the name of the user that is used to connect to the e-mail server|
| `password` | the password of the user|
| `port` | the port that is used to connect to the e-mail server|
| `ssl` | specifies if SSL should be used when connecting to the e-mail server|
| `folder` | the folder to fetch e-mails from (default: INBOX)|
| `move_on_success` | the folder e-mails that were successfully parsed are moved to (instead of deleted)|
| `move_on_failure` | the folder e-mails that were ignored are moved to|

Available arguments that change how the work packages are handled:

| `project` | identifier of the target project|
| `tracker` | name of the target tracker|
| `category` | name of the target category|
| `priority` | name of the target priority|
| `allow\_override` | specifies which attributes may be overwritten though specified by previous options. Comma separated list|


### POP3

The rake task `redmine:email:receive_pop3` fetches e-mails via IMAP and
parses them.
Example:
```bash
bundle exec rake redmine:email:receive_pop3 host='pop.gmail.com' username='test_user' password='password' port=995 allow_override=priority
```

Available options that specifiy the e-mail behavior are:

|key | description|
|----|------------|
|`host` | address of the e-mail server (default: 127.0.0.1)|
| username | name of the user that is used to connect to the e-mail server|
| password | password of the user|
| port| POP3 server port (default: 110)|
| apop | use APOP authentication (default: false)|
| delete_unprocessed | delete messages that were ignored (default: leave them on the server)|

Available arguments that change how the work packages are handled:

|key | description|
|----|------------|
| `project` | identifier of the target project|
| `tracker` | name of the target tracker|
| `category` | name of the target category|
| `priority` | name of the target priority|
| `allow_override` | specifies which attributes may be overwritten though specified by previous options. Comma separated list|

If you set a default value it will be used when creating a work package.
But then no other value is possible (even when you update the work package) unless you specify this with the use
of `allow_override`. Some attributes (like `type, status, priority`) are
only changeable if you specify this via `allow_override`. But notice:
Some attributes have to specified in another format here, e.g. Assignee
can be allowed to be overriden with `allow_override=assigned_to`.


## Format of the Emails

### Work Packages

#### Attributes

The Attributes you can use in your e-mail are the same whether
you create or update a work package. Only the project is a bit special:
If you create a work package and do not specify the project via an environment variable you pass
along to the rake task you have to put it into the e-mail. If you
specify it via an environment variable or you update
a work package you do not need to specify it.

The subject of the work package that shall be created is derived from
the subject of the e-mail. The body of the e-mail gets parsed and all
lines that contain recognized keys are removed. What is left will become
the description.

Other available keys for the e-mail are:

|Key|Description|Example|
|---|---|---|
| Project | sets the project. Use the project identifier | Project:test\_project |
| Assigne | sets the assignee. Use the e-mail or login of the user |
Assignee:test.nutzer@example.org |
| Type | sets the type | type:Milestone |
| Version | sets the version | version:v4.1.0 |
| Start date | sets the start date | start date:2015-02-28 |
| Due date | sets the due date |  |
| Done ratio | sets the done ratio. Use a number | Done ratio:40 |
| Status | sets the status | Status:closed |
| priority | sets the priority | priority:High |

If you want to set a custom field just use the name as it is displayed
in your browser, e.g. `Custom field:new value`

**Notice: The keys are not case-sensitive but the values you want to set
are.**

#### Attachments

If you create or update a work package via e-mail the attachments of the
e-mail will be attached to the relevant work package.

#### Watchers

If you create a work package via e-mail and sent it to another e-mail
(to or bcc) OpenProject will search for a user with this e-mail and add it
as watcher.