wiki:MailToTracPlugin

Pluggable email handler for Trac

Notice: This plugin is unmaintained and available for adoption.

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 MTA, for example postfix. It will open a Trac environment and run through each enabled IEmailHandler and execute its invoke() method if its match() method returns True.

  • If invoke returns an email message, then subsequent IEmailHandlers 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 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:

[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 (minuscreate :)
      • 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 here.

If you have any issues, create a new ticket.

defect

7 / 12

enhancement

4 / 6

task

1 / 3

Download

Download the zipped source from here.

Source

You can check out MailToTracPlugin from here using Subversion, or browse the source with Trac.

Installation

General instructions on installing Trac plugins can be found on the TracPlugins page.

Recent Changes

16530 by rjollos on 2017-04-16 02:21:26
Fix indentation
14732 by rjollos on 2015-06-22 22:05:09
1.0: Plugin has no package data.
14731 by rjollos on 2015-06-22 22:03:02
1.0: Set version to 1.0.
(more)

Author/Contributors

Author: k0s
Maintainer: none (needsadoption)
Contributors:

Last modified 13 months ago Last modified on Mar 2, 2023, 7:43:20 AM