= Pluggable email handler for Trac = == Description == provides a trac-admin command, a bash script (mail2tracAdmin) calling trac-admin and extension point that allows email messages to be handled by Trac plugins. The bash script, `mail2tracAdmin` which may be called by an [http://en.wikipedia.org/wiki/Mail_transfer_agent MTA] (e.g. [http://www.postfix.org/ postfix]) to open a Trac environment and run through each enabled [source:mailtotracplugin/0.11/mail2trac/interface.py IEmailHandler] and executes 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 `mail2trac` script takes a `-p` command line argument for the path to the project environment. The incoming email address should equal {{{ [notification] smtp_replyto = }}} in the [http://trac.edgewall.org/wiki/TracIni trac.ini] file. As an example, if `smtp_replyto` is set to `foo@example.com` and the project is in `/var/trac/bar`, the `aliases` file on `example.com` should have a line like {{{ foo: "| /path/to/mail2trac -p /var/trac/bar" }}} == Use == === Permission === mail2trac declare 4 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 ticket : * the trac address must be correctly configured (Mr Obvious) * you must have declared your mail address in your user preferences. * have the correct permission according what you intend to do. * the unix user launching the mail2tracAdmin should have permission on the trac files (even file création for attachment) === mail parsing === An email is parsed by mail2trac as following : * 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 begining 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 (work 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 ignore by mail2trac) * any '''#field''' or '''#end''' will be ignore, and what's left is the ticket's description if you create, or the comment if you comment. === Attachments === Any mail's attachments will be include as attachement in the ticket. === An exemple === Creation : {{{ From: Sender To: marvin_trac Subject: create : exemple for mail2trac This ticket is an exemple for mail2trac. (this is in fact the description of the ticket) we want a cc to jblondon, a component to component2 and a priority to trivial. we can do that with #cc:jblondon, #component: component2 and #priority : trivial . (note that this instruction are not on the begining of a line and will be seen as part of the description) #cc:jblondon #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: exemple for mail2trac -------------------------+---------------------- Reporter: sender | Owner: somebody Type: defect | Status: new Priority: trivial | Milestone: Component: component2 | Version: Resolution: | Keywords: -------------------------+---------------------- This ticket is an exemple 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 begining of a line and will be seen as part of the description) }}} we send : {{{ From: Sender To: test Subject: Re: [test] #42: exemple for mail2trac we reassign it to jdoe and change it's 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 > To: undisclosed-recipients: ; > Subject: [test] #42: exemple for mail2trac > X-Mailer: Trac 0.12.2, by Edgewall Software > > #42: exemple for mail2trac > -------------------------+---------------------- > Reporter: sender | Owner: somebody > Type: defect | Status: new > Priority: trivial | Milestone: > Component: component2 | Version: > Resolution: | Keywords: > -------------------------+---------------------- > This ticket is an exemple 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 begining of a line and will > be seen as part of the description) > }}} answer : {{{ #42: exemple 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 it's cc to nothing }}} we accept the ticket : {{{ From: Sender To: test Subject: Re: [test] #42: exemple for mail2trac in fact we want the ticket #accept }}} (note that end is not mandatory) answer : {{{ #42: exemple 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 To: test Subject: Re: [test] #42: exemple 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 > To: undisclosed-recipients: ; > Subject: Re: [test] #42: exemple for mail2trac > X-Mailer: Trac 0.12.2, by Edgewall Software }}} trac say : {{{ #42: exemple 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 To: test Subject: Re: [test] #42: exemple for mail2trac Arf, no it's not done, i reopen #reopen }}} we get : {{{ #42: exemple 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 To: test Subject: Re: [test] #42: exemple for mail2trac resolve as invalid, but instead of #resolve: invalid we use the alias #invalid #invalid }}} and finally this very usefull ticket is closed : {{{ #42: exemple 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 [http://trac-hacks.org/newticket?component=MailToTracPlugin&owner=zitune new ticket]. == Download == Download the zipped source from [download:mailtotracplugin here]. == Source == You can check out MailToTracPlugin from [http://trac-hacks.org/svn/mailtotracplugin/0.12 here] using Subversion, or [source:mailtotracplugin browse the source] with Trac. == Recent Changes == [[ChangeLog(mailtotracplugin, 3)]] == Author/Contributors == '''Author:''' [wiki:zitune] and [wiki:k0s] the initial author (thanks a lot) [[BR]] '''Contributors:''' [[BR]]