[[PageOutline(2-5,Contents,pullout)]] = Pluggable email handler for Trac == Description Mail2trac provides : * a Trac-admin command, a bash script (mail2tracAdmin) calling trac-admin * an extension point that allows email messages to be handled by Trac plugins other than mail2trac. The bash script, `mail2tracAdmin` may be called by an [http://en.wikipedia.org/wiki/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 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 `mail2tracAdmin` script takes as argument the path to the project environment. 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`, the `aliases` file on `example.com` should have a line as follows: {{{ foo: "| /path/to/mail2tracAdmin /var/trac/bar" }}} See also: EmailtoTracScript == Usage === Permission mail2trac declares 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 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 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; 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''' : at the 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 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 begining 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 begining of a line and will be seen as part of the description) }}} We send: {{{ From: Sender To: test Subject: Re: [test] #42: example 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: 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 begining 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 it's cc to nothing }}} We accept the ticket: {{{ From: Sender To: test 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 To: test 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 > 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 To: test 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 To: test 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 [http://trac-hacks.org/newticket?component=MailToTracPlugin&owner=zitune new ticket]. [[TicketQuery(component=MailToTracPlugin&group=type,format=progress)]] == 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] ( was [wiki:k0s] the initial author (thanks a lot)) [[BR]] '''Maintainer''': [[Maintainer]] [[BR]] '''Contributors:''' [[BR]]