===============================================
GotMail v0.6.5
===============================================
Author: Peter Hawkins <peter@hawkins.emu.id.au>

Description:
============
This is GotMail, a perl script to fetch mail out of your hotmail account. This is especially useful if you want to move from hotmail into one of the other free mail services - one command can do it all. GotMail also supports getting any new mail only from your Hotmail account - perfect for using a HotMail account as a redirect address into another account.

Requirements:
=============
* Perl 5
* curl-ssl 6.5.2 or later (ssl is _required_ to use hotmail... )
	README: VERSION 6.5.2 IS **REQUIRED**! YES REALLY! 6.0, at least WILL NOT WORK (it will segfault).
	It's debian package "curl-ssl" for those enlightened people who are running debian... You can get it from http://curl.haxx.nu/ if you aren't cool enough to run debian... 
* The URI cpan module (liburi-perl debian package, or http://www.cpan.org/)


Usage:
======
If your perl interpreter is not in /usr/bin, you will need to edit the first line of the script to make it point to the correct place, or start the script using /path/to/perl gotmail.

gotmail [OPTIONS...]

  -?, --help, --usage         Display the help screen
  -u, --username              Specify your hotmail username (REQUIRED)
  -p, --password              Specify your hotmail password (REQUIRED)
  --proxy host:port           Specify an HTTP proxy to use. Format is
                              host:port - eg: localhost:3128
  -f, --forwarding-email      Specify an email address to forward to. If a
                              forwarding address is not given, messages will
                              be saved to disk
  --folders "my folders"      Only download certain folders (see below)
  --folder-directory /my/dir  Download messages into this directory
  --only-new-messages         Only unread messages will be retrieved
  --mark-messages-as-read     Messages will be marked as read once downloaded
  --delete-messages           Messages will be deleted after download
  --speed-limit               Throttle back message forwarding to stop sendmail
			      from being overloadd.
  --retry-limit		      Maximum number of retries allowed when downloading
  			      a page.
  -v, --verbose               Be verbose in output messages.
  --debug                     Print some misc debugging output.


If a forwarding email address is given, all mail will be forwarded using sendmail to the address specified. If no forwarding address is given, mail will be saved in files with the same names as your hotmail folders.

The delete messages option only deletes the messages that are downloaded. So if used in combination with the --only-new-messages option, only the newly received mail will be downloaded and then deleted.

The --folders option only downloads messages from folders that are in the list given. eg. ./gotmail.pl --folders "bulk mail, inbox" will get the bulk mail and inbox folders only. The list separator is not important.

So, an example command line which gets all the mail from the account of "microsoft_sux" with password "sEcReT" and forwards it to "billgates@microsoft.com" might be:
./gotmail -u microsoft_sux -p sEcReT -f billgates@microsoft.com

You can also create a ~/.gotmailrc file with options in it. A sample gotmailrc is included (rename it ~/.gotmailrc and edit it).
eg:
# This is a comment!
login=my_login
password=ultrasecret

A sample rc file is included called "gotmailrc". Options from the command line will override those from the rc file.

Notes:
======
* Mail in the Sent Messages or Drafts folders cannot be saved at the moment. Please tell me if this is a huge problem. It's a little harder to get email messages from these two folders.
* Mail in the Trash Can will not be downloaded. This is to avoid downloading two times any mail which is deleted by the script. Again, does this trouble you?
* A work around has to be enabled for certain Hotmail mail servers which have problems with the raw message display which Gotmail uses. If Gotmail doesn't work for you, or if you are getting nothing but blank messages from the script, please contact me with full debugging logs and I'll fix it up for you.
* If the page structure of HotMail is changed, this script may stop working. If that happens, annoy me for a new version...





Bugs:
=====
* None known, I'm somewhat a perl newbie, so this code may not be as elegant as possible or as robust as possible.
* Your bug could be here =)

How to report a bug:
====================
* I need these things:
 - A brief description of your problem.
 - Run the script with --debug and send me the "/tmp/gotmail_log" file generated by the script. (This will reveal your password to me, so you may wish to change your password to something different temporarily, and change it back after you have done this step.
 - Your ~/.gotmailrc file, if you use one.
* Send a message containing these things to me at peter@hawkins.emu.id.au

Thanks:
=======
To all who contributed by sending patches, feedback, comments, etc.

Thanks to:
Leigh Purdie
"Sh" (whatever your name is =)
Patrick Froede
Herman Mereles
Kamal Kantawala
Andrei Popov
Kamal Mahyuddin
Hindu
Joel Mejeur
Wesley Hosking
Max Hales
Brian Almeida
