[[PageOutline(2-5,Contents,pullout)]]

= Pluggable email handler for Trac

== Description

This plugin handles incoming emails within Trac, by parsing and displaying its contents on a Trac ticket. This is useful for software development teams who communicate via email on a topic and want to automatically create a ticket by sending for example a summary to a specified Trac address without the need to enter Trac and create a new ticket there. Attachments are also included in the ticket. A fully worked out basic example is given below.

Specifically Mail2trac provides:
 * a shell script `mail2tracAdmin` that calls `trac-admin`
 * an extension point that allows email messages to be handled by other Trac plugins.

The shell script `mail2tracAdmin` may be called by an [wikipedia:Mail_transfer_agent MTA], for example [http://www.postfix.org/ postfix]. It will open a Trac environment and run through each enabled [source:mailtotracplugin/0.12/plugin/mail2trac/interface.py IEmailHandler] and execute its `invoke()` method if its `match()` method returns `True`. 
* If `invoke` returns an [http://docs.python.org/library/email email] message, then subsequent `IEmailHandler`s will also process the message. 
* If `None` is returned, then the message is consumed and execution stops.

To enable the plugin for `postfix`, add an appropriate line to the aliases file, usually `/etc/aliases` or `/etc/postfix/aliases` and then refreshing the `aliases` database, see [http://www.postfix.org/aliases.5.html man aliases]. 

The `mail2tracAdmin` script takes the path to the project environment as argument. The incoming email address should be specified in the `trac.ini` file:

{{{#!ini
[notification]
smtp_replyto =
}}}

As an example, if `smtp_replyto` is set to `foo@example.com` and the project is in `/var/trac/bar`, then the `aliases` file on `example.com` should have a line as follows:

{{{
foo: "| /path/to/mail2tracAdmin /var/trac/bar"
}}}

See also: EmailtoTracScript

== Usage

=== Permission

This plugin declares the following permissions:
 * `MAIL2TICKET_COMMENT` : user authorized to comment
 * `MAIL2TICKET_PROPERTIES` : user authorized to change properties, like 'owner', 'cc', etc. 
 * `MAIL2TICKET_CREATE` : user authorized to create a ticket
 * `MAIL2TICKET_ADMIN` : all the above

In order to post a ticket :
 * the Trac address must be correctly configured.
 * the mail address must have been declared in your user preferences.
 * have the correct permissions set and according to what you intend to do.
 * the UNIX user launching `mail2tracAdmin` should have permission on the Trac files, even file creation for attachment.

=== mail parsing

An email is parsed by mail2trac as follows:

 * Header 
   * Subject field : 
      * if it begins by '''create :''' , mail2trac will create a ticket with the subject as summary (minus`create :`)
      * if it contains '''#id_of_ticket''' (#42 for example), mail to trac will comment (and possibly update ticket fields) with the mail
      * else it will be ignored

 * Body :
   * any line beginning with '''#field''' with field one of these: ''type'', ''priority'', ''milestone'', ''component'', ''version'', ''resolution'', ''keywords'', ''cc'', will be treated as request to change the 'field' property; works only with the `MAIL2TICKET_PROPERTIES` permission.
   * mail2trac understand classic actions : resolve, reassign, accept and reopen, as in the classical web UI:
     * '''#reassign : user''' , reassign to user
     * '''#resolve : resolution''', The resolution will be set to resolution. Next status will be 'closed'
     * '''#accept''' :  Next status will be 'accepted' and owner fixe to yourself
     * '''#reopen''' : The resolution will be deleted. Next status will be 'reopened'
   * for usability, few actions have an alias : 
     * '''#fixed''' is interpreted as '''#resolve:fixed''',
     * '''#duplicate''' is interpreted as '''#resolve:duplicate''',
     * '''#wontfix''' is interpreted as '''#resolve:wontfix''',
     * '''#invalid''' is interpreted as '''#resolve:invalid''',
   * parsing will stop at the '''#end''' tag, meaning everything after #end will be ignored by mail2trac
   * any '''#field''' or '''#end''' will be ignored, and what's left is the ticket's description if you create, or the comment if you comment.

'''Rq''' : upon creation you can assign a ticket by setting its owner with '''#owner : jdoe'''. In a response you have to use the action '''#reassign'''.

=== Attachments

Any mail attachments will be included as attachment in the ticket.

=== Example

Creation:

{{{
From: Sender <sender@bearstech.com>
To: marvin_trac
Subject: create : example for mail2trac

This ticket is an example for mail2trac.
(this is in fact the description of the ticket)

we want a cc to jdoe, a component to component2 and a priority to
trivial.

we can do that with #cc:jdoe, #component: component2 and #priority :
trivial .
(note that this instruction are not on the beginning of a line and will
be seen as part of the description)

 #cc:jdoe
#component: component2
  #priority: trivial

#end
the parsing stop here, this sentence will not be in the description
(note that instruction like #cc can have space anywhere)
}}}

Trac answer: 

{{{

#42: example for mail2trac
-------------------------+----------------------
  Reporter:  sender      |      Owner:  somebody
      Type:  defect      |     Status:  new
  Priority:  trivial     |  Milestone:
 Component:  component2  |    Version:
Resolution:              |   Keywords:
-------------------------+----------------------
 This ticket is an example for mail2trac.
 (this is in fact the description of the ticket)

 we want a cc to jdoe, a component to component2 and a priority to
 trivial.

 we can do that with #cc:jdoe, #component: component2 and #priority :
 trivial .
 (note that this instruction are not on the beginning of a line and will
 be seen as part of the description)

}}}

We send:

{{{
From: Sender <sender@bearstech.com>
To: test <marvin_trac>
Subject: Re: [test] #42: example for mail2trac

we reassign it to jdoe and change its cc to nothing

#reassign: jdoe
#cc: ''


#end
On 26/10/2011 15:03, test wrote:
> Date: Wed, 26 Oct 2011 15:03:57 -0000
> From: test <marvin_trac>
> To: undisclosed-recipients: ;
> Subject: [test] #42: example for mail2trac
> X-Mailer: Trac 0.12.2, by Edgewall Software
>
> #42: example for mail2trac
> -------------------------+----------------------
>   Reporter:  sender      |      Owner:  somebody
>       Type:  defect      |     Status:  new
>   Priority:  trivial     |  Milestone:
>  Component:  component2  |    Version:
> Resolution:              |   Keywords:
> -------------------------+----------------------
>  This ticket is an example for mail2trac.
>  (this is in fact the description of the ticket)
>
>  we want a cc to jdoe, a component to component2 and a priority to
>  trivial.
>
>  we can do that with #cc:jdoe, #component: component2 and #priority :
>  trivial .
>  (note that this instruction are not on the beginning of a line and will
>  be seen as part of the description)
>
}}}

Answer:

{{{


#42: example for mail2trac
-------------------------+----------------------
  Reporter:  sender      |      Owner:  jdoe
      Type:  defect      |     Status:  assigned
  Priority:  trivial     |  Milestone:
 Component:  component2  |    Version:
Resolution:              |   Keywords:
-------------------------+----------------------
Changes (by sender):

 * cc: jdoe (removed)
 * cc: '' (added)
 * owner:  somebody => jdoe
 * status:  new => assigned


Comment:

 we reassign it to jdoe and change its cc to nothing

}}}

We accept the ticket:

{{{
From: Sender <sender@bearstech.com>
To: test <marvin_trac>
Subject: Re: [test] #42: example for mail2trac

in fact we want the ticket
#accept

}}}

Note that the end end part is not mandatory.

Answer:

{{{
#42: example for mail2trac
-------------------------+----------------------
  Reporter:  sender      |      Owner:  sender
      Type:  defect      |     Status:  accepted
  Priority:  trivial     |  Milestone:
 Component:  component2  |    Version:
Resolution:              |   Keywords:
-------------------------+----------------------
Changes (by sender):

 * status:  assigned => accepted
 * owner:  jdoe => sender


Comment:

 in fact we want the ticket

}}}

We close it:

{{{
From: Sender <sender@bearstech.com>
To: test <marvin_trac>
Subject: Re: [test] #42: example for mail2trac

we close as fixed
#resolve: fixed

#end
On 26/10/2011 15:14, test wrote:
> Date: Wed, 26 Oct 2011 15:14:31 -0000
> From: test <marvin_trac>
> To: undisclosed-recipients: ;
> Subject: Re: [test] #42: example for mail2trac
> X-Mailer: Trac 0.12.2, by Edgewall Software

}}}

Trac says:

{{{
#42: example for mail2trac
-------------------------+--------------------
  Reporter:  sender      |      Owner:  sender
      Type:  defect      |     Status:  closed
  Priority:  trivial     |  Milestone:
 Component:  component2  |    Version:
Resolution:              |   Keywords:
-------------------------+--------------------
Changes (by sender):

 * status:  accepted => closed


Comment:

 we close as fixed
}}}

We reopen:

{{{
From: Sender <sender@bearstech.com>
To: test <marvin_trac>
Subject: Re: [test] #42: example for mail2trac

Arf, no it's not done, i reopen
#reopen

}}}

We get:

{{{
#42: example for mail2trac
-------------------------+----------------------
  Reporter:  sender      |      Owner:  sender
      Type:  defect      |     Status:  reopened
  Priority:  trivial     |  Milestone:
 Component:  component2  |    Version:
Resolution:              |   Keywords:
-------------------------+----------------------
Changes (by sender):

 * status:  closed => reopened


Comment:

 Arf, no it's not done, i reopen

}}}

We close it again:

{{{
From: Sender <sender@bearstech.com>
To: test <marvin_trac>
Subject: Re: [test] #42: example for mail2trac

resolve as invalid, but instead of #resolve: invalid we use the alias #invalid
#invalid
}}}

And finally this ticket is closed:

{{{
#42: example for mail2trac
-------------------------+--------------------
  Reporter:  sender      |      Owner:  sender
      Type:  defect      |     Status:  closed
  Priority:  trivial     |  Milestone:
 Component:  component2  |    Version:
Resolution:              |   Keywords:
-------------------------+--------------------
Changes (by sender):

 * status:  reopened => closed


Comment:

 resolve as invalid, but instead of #resolve: invalid we use the alias
 #invalid

}}}

== Bugs/Feature Requests

Existing bugs and feature requests for MailToTracPlugin are 
[report:9?COMPONENT=MailToTracPlugin here].

If you have any issues, create a 
[/newticket?component=MailToTracPlugin new ticket].

[[TicketQuery(component=MailToTracPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:mailtotracplugin here].

== Source

You can check out MailToTracPlugin from [/svn/mailtotracplugin/0.12 here] using Subversion, or [source:mailtotracplugin browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Recent Changes

[[ChangeLog(mailtotracplugin, 3)]]

== Author/Contributors

'''Author:'''  [wiki:k0s] [[BR]]
'''Maintainer''': [[Maintainer]] [[BR]]
'''Contributors:''' [[BR]]