= Pluggable email handler for Trac =

== Description ==

provides a command line script and extension point that allows email messages to be handled by Trac plugins.  This ticket provides a command-line script, `mail2trac` 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"
}}}

== Why not email2trac? ==

EmailtoTracScript is a more mature solution for converting email to Trac tickets.  When building the GeoTicketPlugin, I was originally  hoping to make use of the EmailtoTracScript to allow emails to specify a location in the subject header (see: source:geoticketplugin/0.11/geoticket/mail.py).  When I realized the architecture would not easily support this, I thought of forking it, then realized that an implementation from scratch would actually better serve my needs.

MailToTracPlugin offers:

 * a real pluggable architecture that allows arbitrary email handlers to be plugged in
 * POSTing to a URL to avoid complicated setuid issues with MTAs
 * outside of configuring postfix and MX records (always fun!) an easy installation

While mail2trac is less mature, to the front-end user there shouldn't be considerable difference for the case of creating and responding to tickets.  From a development point of view, I would recommend mail2trac over email2trac as a point to build on since a pluggable architecture was the point since the beginning.

== Processing mail from a third-party mailserver ==
E-mails are handled by the mail2trac executable.  Normally the mail transfer software would execute this program for each incoming mail.

If your Trac installation is separate from the e-mail infrastructure, you can use use [http://fetchmail.berlios.de/ Fetchmail] to download the e-mails from the external server.

{{{
fetchmail --protocol POP3 --port 110 --user [mailaccount] --mda "mail2trac -p /path/to/trac/environment" mailhost.domain.com
}}}

== 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=k0s 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.11 here] using Subversion, or [source:mailtotracplugin browse the source] with Trac.

== Example ==

[source:mailtotracplugin/0.11/mail2trac/email2ticket.py email2ticket] is an example [source:mailtotracplugin/0.11/mail2trac/interface.py IEmailHandler] plugin to convert an email message to a ticket.

== Recent Changes ==

[[ChangeLog(mailtotracplugin, 3)]]

== Author/Contributors ==

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