Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
Heliotrope is a personal email server. It provides all the functionality you want in a modern email client: - proper message threading - labels - fast, full-text search over all messages with a complete query language - support for signed and encrypted email - an extensible JSON-over-HTTP API Heliotrope is a backend service against which email clients / MUAs can be written. To use it, you must use a client. For an example client, see Turnsole: http://github.com/wmorgan/turnsole. WHY ANOTHER PROTOCOL? WHY NOT JUST USE IMAP? Because IMAP is terrible and you want all those features listed above. REQUIREMENTS Heliotrope is written in a mixture of Ruby and C. You will need a working C compiler, and a modern Ruby. 1.8.7 or 1.9.2 are good choices. Ruby 1.9.2 will give you better performance and better i18n support. Heliotrope uses html2text to generate text from HTML attachments. You will need this or some reasonable alternative. PREPARING YOURSELF 0. Find your happy place. 1. Install html2text. On Debian-based Linux distros, it's `sudo apt-get install html2text`. 2. Install a modern Ruby. I recommend 1.9.2. On Debian-based Linux distros, you can try the ruby1.9.1 package. You can download and compile it from http://www.ruby-lang.org/en/downloads/ if you are feeling crazy. 3. Run `gem install trollop whistlepig rest-client sinatra rmail leveldb-ruby` GETTING IT Once Heliotrope is more stable, you will be able to install it via rubygems. For you, you should run this: git clone https://github.com/wmorgan/heliotrope.git RUNNING IT Decide where you want to store everything. Call this directory <dir>. Now run `ruby -Ilib bin/heliotrope-server -d <dir>`. Heliotrope exposes a simple debugging HTML interface. If you point your browser to http://localhost:8042/, you should see your empty mailstore. Congrats! You're running Heliotrope. IMPORTING SOME MAIL Heliotrope only returns email in the order it was added to the system. For normal operation, in which email is added as it arrives, this is fine. For bulk imports, you must take care to add the email in the order you want it returned. To add email, first kill your server. You can add email to the server one at a time when it's running (see ADDING EMAIL below), but for bulk imports, it's much faster to avoid the HTTP overhead. To add a pre-existing mbox: ruby -Ilib bin/heliotrope-add -m <mbox> -d <mailstore> To add a pre-existing maildir: ruby -Ilib bin/heliotrope-add -a <maildir> -d <mailstore> To add a pre-existing Gmail account: ruby -Ilib bin/heliotrope-add -g <gmail username> -d <mailstore> To add a pre-existing, non-Gmail IMAP account: ruby -Ilib bin/heliotrope-add -i <imap server> -d <mailstore> For testing purposes, you may want to limit the number of emails added by using the --num-messages option. After import, start the server again. You should see stuff at http://localhost:8042/. For a full client, see https://github.com/wmorgan/turnsole/. ADDING EMAIL Once the server is running, you can use heliotrope-add to add individual emails as they arrive. To add a single email: cat email.txt | ruby -Ilib bin/heliotrope-add Once Heliotrope is production-ready, I'll add some documentation about procmailrc or whatever. JSON API SPEC ------------- Coming soon! For now, you can reverse engineer lib/heliotrope-client.rb.