iGmail :: An IMAPv4 gateway to Gmail

The folk at Gmail have yet to provide an IMAP interface to their email service. While POP access is nice, there is no folder support and the messages are stateless (cannot be marked read, unread, important, etc.). iGmail is an IMAP server that runs between you and Gmail. You can use any IMAP client (outlook, outlook express, thunderbird, etc.) to connect to your gateway. iGmail is open source, and has been released under the GNU GPL v2.

Note (6/15/2007): The bug preventing msg importing has been fixed. Use version 0.2 from the releases page. The Windows binary version has *not* been updated yet.

iGmail will run on all platforms that python will run on (Windows, Linux, Unix, Mac OS X, OS/2, etc.). First, install python. Then, install Twisted. Then get the iGmail code. There are two ways to do this; if you have subversion installed you can do a svn co https://svn.butterfat.net/public/igmail/trunk iGmail. If not, you can download the package from here.

After uncompressing the files, edit the config.xml file. The datadir attribute at the top should contain the full path to an empty directory on your machine. This directory will contain the state information about your messages. If you would like to restrict access to your server to only certain named accounts, you can add user elements as shown in the comments in the config.xml file.

It's then recommended that you run the importmail.py script which will create the initial cache for the IMAP server. This may take a while. You run the script with python ./importmail.py username@gmail.com password. Running this initial import script is not necessary, but if you have a lot of messages in Gmail it is a good idea (this prevents your mail client from having to wait after it's first request to your server). Then you can start up the server with the twistd command (in Windows you may have to add C:\Python24\Scripts to your PATH environment variable). To start the server with logging to your current window, use twistd -noy igmail.tac.

You can now connect to your server using any IMAP mail client. Just set up a new IMAP account in your client, using a location of localhost for your incoming server location. The username you send to the server is the same username you use when you check your Gmail on Google.

Additional option for Windows:
You can download and run a binary distribution. There is no installation or need to have python, just set up your config.xml with the location of an empty data directory, then run the importmail program (from the command line):
C:\igmail> importmail.exe user@gmail.com mypassword
Then run igmail.exe. A command window will be open while igmail is running. You can stop the program by either closing the window or pressing ctrl-c. A nasty interface, I know; if anyone cares, I can make a prettier GUI version.

This part assumes you can connect to your server and see your folders. You can use your IMAP mail client now just as you would for any other IMAP account, with a few exceptions.

What does work
All of your labels show up as folders. When you delete a message in your client, it is placed in your trash on Gmail. When you flag a message in your client, it is starred on Gmail. When you mark a message read/unread, that state information is replicated on Gmail. When you get new mail, your filters on Gmail will label your message as you requested (this may include skipping your inbox). You can create new folders (within your labels folder) which will create new labels on Gmail. You can also delete and rename these labels/folders. Generally, what you seen in your client (read/unread/flagged/etc) will be the same as what you see when you log into Gmail.

What sort of works
You can copy/move messages between folders that are based on labels, but not to/from your inbox, trash, starred folder, or sent folder. Because Gmail uses "threads" rather than "messages" for read/unread state, you cannot have separate read/unread states for messages. If you mark a message "unread", the entire thread will be marked "unread", which means that in your client all other message from that thread will show up as "unread".

What does not work
You cannot delete messages from your trash folder. To permanently delete messages, you will need to log into Gmail.

Q. Why aren't all of my folders/labels showing up?
A. You probably just need to subscribe to them first. Consult your client's documentation on folder subscriptions.

Q. Can I run importmail while the server is running?
A. Yes.

Q. Do I have to run importmail or can I just start the server?
A. It is recommended, though not required, that you run importmail for each account that will be logging into the gateway. This process could take a while, depending on the amount of mail you have. If you have a lot of mail, your mail client may timeout while the gateway is fetching all your mail (message ids, to be exact), so it's often better to just import it all beforehand.

Q. How many people can log into the gateway at the same time?
A. This is dependant upon your bandwidth, memory, etc. The software has no limitations.

Q. What is the air speed velocity of an unladen swallow?
A. Already answered here.

Q. Why do I have to run this gateway instead of you running a general service for everyone?
A. Bandwidth. Also, it was important that everyone be able to download and use the code. Anyone can set up a server for themselves and their friends.

Q. What information is cached in files by the gateway?
A. Every user that logs in will have all message ids (long alpha numeric unique IDs for messages) and flags (read/unread/etc) from their Gmail account cached. Passwords are cached as well, but are run through a SHA-1 hash first before being stored. No message subjects, bodies, attachments, dates, etc. are cached.

Q. Does iGmail send mail too?
A. No. IMAP is used only to receive mail. SMTP is used to send mail. Follow the directions found at Gmail's Help Center to set up your client to send mail (just follow the directions relating to SMTP). The Thunderbird instructions can be found here.

Q. Who wrote this code and why is it shoddy?
A. bmuller@butterfat.net wrote it over Labor Day weekend. It is shoddy because it was written over Labor Day weekend.

iGmail uses a modified version of libgmail to "talk" to Gmail's http interface. When you first log in to the iGmail gateway all of your message threads in all of your folders have to be "visited" (pulled via HTTP) to extract their message ids and create a message list to send to your mail client. Then, by implementing some interfaces with Twisted's IMAP server, you've got a working IMAP gateway. Every time your client asks for new messages, the gateway passes that request along to Google. When you get new mail, the message ids are added to the cache as well as their state ("Unread", etc), and then the message information is sent back to your mail client. The message ids and states are cached to provide instant responses to mail client queries for whole mailboxes. Note that when you have an attachment in a message, the attachment must first be downloaded by the gateway (it's actually a part of the message) before it can be sent to your client. This may cause a lengthy delay when downloading large attachments.

According to the Program Policies for Gmail, users may not Modify, adapt, translate, or reverse engineer any portion of the Gmail Service. Violation of the program policies could result in termination of service. Due to this policy, the iGmail software should not be used by anyone at any time for any purpose. I have released the code merely as an academic exercise; all references to actual usage should be considered purely hypothetical and disregarded.