Email2Trac on Windows

See the official Email2Trac documentation for an up to date version of these instructions.

---

If you're not familiar with Trac: Trac is an integrated issue tracking system, wiki, and SVN repository browser. It is open source software (under the very liberal BSD licence), and is popular as a public bug tracker for many open source projects. Email2Trac is a plugin (actually, more of a script) for Trac that enables users to submit bugs via email.

Email2Trac was clearly created by *nix users, but since it is written in Python, can be made to work in Windows without too much hassle. This post is a summary of a couple messages I posted to the Trac Users Group detailing our Email2Trac setup.

---

Platform: Windows Server 2003, Python 2.4, Trac 0.10.3, email2trac 0.10 (year+ old install)

There are 3 pieces you need to effectively turn emails into Trac tickets:

1. A way to receive emails on your Trac server
2. A way to process or convert emails into Trac tickets (this would be the email2trac python script)
3. A way to automate part 2

Here's what we use on Windows:

Receiving Emails via SMTP

We use Windows' built-in SMTP server to deliver mail to our Trac server. When I setup email2trac, I thought that this step was going to be the most difficult (mostly because I have no experience with email servers/services). Surprisingly, it is actually the easiest step. The trick is to install the SMTP server, but not the POP server, so that emails are received and left as files in the "drop" folder. (This is the way an email server hands off email between the two services) In a way, email2trac performs the distribution functions normally handled by POP.

Install the SMTP service via Windows Components.

1. Open Add/Remove Programs (Start > Control Panel > Add or Remove Programs)
2. Click "Add/Remove Windows Components" in the left-hand bar.
3. Use the "Details..." button to drill-in to Application Server > Internet Information Services (IIS) > SMTP Service. In Windows XP, it's just Internet Information Services (IIS) > SMTP Service.
4. Check the box next to SMTP Service, click "OK", "OK", "Next", "Finish".

At this point, you should ensure that the SMTP Service is running (on my workstation it didn't start after installation; this may be a policy issue).

1. Open up the Services dialog at Start > Control Panel > Admistrative Tools >Services.
2. Scroll down to "Simple Mail Transfer Protocol (SMTP).
3. If startup type is not "Automatic", double-click the service. Change "Startup Type" to "Automatic". Click "OK".
4. If status is not "started", click play button in services dialog toolbar to start the service.

The SMTP service should be configured and ready to receive emails out of the box. You can find SMTP settings at Start > Control Panel > Admistrative Tools >Internet Information Services (IIS) Manager. The installation automatically creates the default domain "Local (Default)" and the corresponding drop folder at C:\Inetpub\mailroot\Drop. You can see that my email2trac batch script picks up .eml files from that location.

To actually receive emails on the server, you have to send to an address of the form "anything@trac-server.domain.com". Your Exchange or other mail server should automatically forward the emails to your Trac server. If you want to use a different address, you will likely have to configure your mail server to forward the mail. The name before the @ can be anything; POP service usually uses this to distribute mail to inboxes, SMTP and email2trac ignore it. A possible enhancement to email2trac would be to use the local-part of the address to identify the destination environment for the ticket. You will probably want to give out a single address, just to keep things consistent; since it is our Help Desk's Trac, we use "helpdesk@trac-server.domain.com".

Alternative Way to Receive Emails

If the server that hosts Trac already handles emails (thus the SMTP domain "trac-server.domain.com" is taken), you will need a different method to receive emails. Instead of using SMTP, you can setup an email box/address for Trac on your existing email system, and use a POP client to retrieve and save emails to a folder. Said POP client could be run in the same batch file used to automate Email2Trac as described below (or replace the Email2Trac call If the POP client can run scripts directly).

Fetchmail is an email client that can be setup in this way with Exchange. See this post for details (Thanks, Nicole). This article details installing Cygwin/Fetchmail on Windows.

Setting Up Email2Trac

The Email2Trac script isn't very Windows-friendly out of the box. I didn't so much install it, as I ripped the main Python files out of the source tarball. Python code doesn't need to be compiled, so this works fine.

1. Extract email2trac.tar.gz (I use 7zip)
2. Navigate into the resulting email2trac-0.x folder and rename:
   email2trac.py.in   to email2trac.py   and
   delete_spam.py.in to delete_spam.py
3. Copy email2trac.py, delete_spam.py, and email2trac.conf to the location where you want to run the script (I put mine in C:\python24\scripts)

For Email2Trac 0.10, I had to alter the script slightly to run. Edit email2trac.py with your favorite editor (I use IDLE, which comes with the Windows Python package).

Comment out the syslog import (line 95 in 0.10); change:

import syslog

to

#import syslog

Note: It looks like this is fixed in Email2Trac 0.13

Next change the name of the default config file (line 984 in 0.10); change:

configfile = '@email2trac_conf@'

to

configfile = 'email2trac.conf'

Depending on how you call the Email2Trac script, you might need to specify a fully-qualified path to your config file. (Thanks Nicole) Use something like this instead:

configfile = 'C:\python24\scripts\email2trac.conf'

Note: You can also specify the config file when calling the script using this switch: -f [config file] or --file=[config file] This may be an easier/cleaner solution than changing the default in the script. I haven't tested this option.

Next, you'll want to edit email2trac.conf. Be sure to configure your environment with Windows-style paths, and specify the temp directory, which is used to extract attachments. Also, make sure the temp directory exists. The top of mine looks like this:

[DEFAULT]
project: C:\trac\project1
tmpdir: C:\temp
...

Note: We only use email2trac with one environment on our server (despite the fact we run several). There is no easy way (that I know of) to use multiple environments with the current version of the Email2Trac script in this setup.

If you are running Trac 0.11, you will also need to add the following under your [DEFAULT] section: (Thanks Nicole)

trac_version: 0.11

You will likely want to make more changes to the config file to suit your needs. See the Email2Trac documentation for details.

At this point, you should be able to push a single email into a ticket from the command-line. Type:

cd C:\python24\Scripts
python email2trac.py < C:\path\to\email.eml

Note: Change paths above based where you saved email2trac and where your emails are dropped. Also depends on Python being in your PATH; add C:\python24 (or your python root) to your PATH, or replace python with C:\python24\python.exe in the above.

Automating Email2Trac

We use Windows' Scheduled Tasks to automate email2trac. This works in two parts: a batch file to run the script on a set of emails and a scheduled task to run said batch file at regular intervals.

Create a new batch file in the same folder as your email2trac.py, something like C:\python24\Scripts\trac-email.bat. Edit it with notepad and insert the following:

@echo off

for %%f in (C:\Inetpub\mailroot\Drop\*.eml) do python email2trac.py < %%f
del C:\Inetpub\mailroot\Drop\*.eml

Note: Change the path C:\Inetpub\mailroot\Drop\ to the location where your emails are dropped, and change *.eml, if they have different extensions. Same PATH caveats as above.

Now create the Scheduled Task:

1. Start the Scheduled Task Wizard(Start > Control Panel > Scheduled Tasks > Add Scheduled Task). Click "Next >".
2. Use "Browse..." to select the batch file you just created as the program you wish to run.
3. Give the task a name, select "Daily". Click "Next >".
4. Set "Start time:" to 12:00 AM, "Perform this task:" to "Every Day", "Start date:" to current date. Click "Next >".
5. Enter a user. I had problems running the task as the unprivileged user that runs tracd, so I set myself as the user (definitely not as secure, but our Trac is on our local intranet). Click "Next >".
6. Check "Open advanced properties..." and click "Finish". The edit task dialog will pop up.
7. Click "Schedule" tab, then "Advanced...".
8. Check "Repeat task", set "Every:" to 10 minutes (or your desired interval). Set "Duration:" to 24 hours.
9. Click "OK", "OK" to close the dialogs.

You can now test your task by right-clicking it and selecting "Run". You should see a command-line window briefly appear. Check that the emails are gone and new tickets have been created in your Trac.

---

Disclaimer: I am not an expert on email, nor do I have much Python experience. This documentation was written up months after I setup Email2Trac, but should be fairly complete.