Description
===========

GetLive is a perl script that interfaces with your Hotmail Live account to retrieve your emails. It has 2 operating modes that I call "Classic" and "FreePops".

In "Classic" mode it fetches mail from your Hotmail Live account. The mail is then presented to any filter (typically procmail) for further processing or dropping in a local mailbox. The downloading can be limited to unread mail or to message-ids that were not yet downloaded before. For the latter GetLive keeps track of all downloaded message-ids.  Messages can be marked read or moved to a folder after being downloaded.

In "FreePops" mode, GetLive starts up as a POP3 server listening on a port. Your email client would connect to it as it does to any POP3 server. Requests are however translated such that you effectively get your mails from your hotmail account. Special constructs are possible to interact with more than Inbox. Also in this case messages can be marked read on the hotmail account after being read.

Usage in "Classic" mode
=======================

./GetLive --config-file ConfigFile [--verbosity N]

  - ConfigFile : Name or full path to a configuration file, with contents
    described hereafter.

  - verbosity : Optional argument, defining the verbosity of the diagnostic
    messages and taking following values :
      0   : Silent
      1   : Normal output (default value)
      2   : Extensive output
      10  : Debugging mode
      100 : Heavy debugging mode

The configuration file takes arguments of the form  
option = value. Empty lines or lines commented with # are possible.
Following are the possible options :

      UserName        = YourHotmailUserName (without @something)
      Password        = YourHotmailPassword (so restrict the access rights to
                        this configuration file.
      Domain          = YourHotmailDomain (default 'hotmail.com', basically
                        what's after the @ in your address)
      Proxy           = ProxyServer if you're behind one.
      ProxyAuth       = ProxyPassword if you're behind one with password. 
      Downloaded      = SomeFileName (it keeps track of all id's of messages
                        that were fetched already) 
      FetchOnlyUnread = Yes or No (default)
                        If Yes only messages that are marked unread are
                        fetched.
                        Downloaded and FetchOnlyUnread are mutual exclusive.
      RetryLimit      = N (default 2) : how many times to retry fetching a
                        web page via curl (the webpage fetcher behind the 
                        scenes)
      CurlBin         = CommandForCurl ('curl -k' by default).
      Processor       = FilterCommand ('/usr/local/bin/procmail' by default). Any
                        filtercommand taking the message in mbox format on its
                        stdin and doing something with it.
                        
                          *) '/bin/cat - >> FetchedMail' might be another 
                             interesting one to drop directly in a mbox file.

                          *) The distribution contains also SmtpForward.pl and
                             SmtpAuthForward.pl. Those can be used as 
                             'Processor' to forward the mails to an SMTP server.

      Folder          = FolderName. Folders that need to be fetched. 
                        This option must be repeated for each folder you want 
                        to fetch. If this option is not present then all 
                        folders will be fetched.
      MarkRead        = Yes or No (default) : whether the message will be 
                        marked read after being downloaded. By the way : 
                        it never gets marked in any way when not downloaded 
                        due to it being already in the 
                        Downloaded = SomeFileName (see higer) file.
      Delete          = Yes or No (default) : whether the message will be 
                        deleted after being downloaded. By the way : 
                        it never gets deleted in any way when not downloaded 
                        due to it being already in the 
                        Downloaded = SomeFileName (see higer) file.
      MoveToFolder    = FolderName or @FileName
                        FolderName is the folder to which the message must be
                        moved after being downloaded. By the way : it never 
                        gets moved in any way when not downloaded due to it 
                        being already in the Downloaded = SomeFileName 
                        (see higer) file.
                        If this argument takes the form @FileName then the
                        FolderName is taken from the contents of the file 
                        FileName.
                        The idea is that f.i. a spamfilter can decide to what
                        folder it must be moved. That spamfilter would be part
                        of Processor    = FilterCommand (see higher) and write a
                        FolderName (for instance Junk if considered junk) to
                        the file FileName.
      SkipTrash       = Yes or No (default) : whether the message Trash folder
                        will be handled (default) or not.
      BreakOnAlreadyDownloaded = Number
                        Stop scanning a folder when detecting a sequence of
                        Number messages that is already downloaded.
                        0 means disabling this feature and is default.
                        Meant to reduce folder scanning.


Usage in "FreePops" mode
=======================

./GetLive --port PortNumber [--verbosity N]

  - verbosity : Optional argument, defining the verbosity of the diagnostic
    messages and taking following values :
      0   : Silent
      1   : Normal output (default value)
      2   : Extensive output
      10  : Debugging mode
      100 : Heavy debugging mode

  - PortNumber : The port on which GetLive will listen to incoming connections
                 (and that you thus should use in your client).

Your email client should be configured as follows (one account per folder) :

      Server : localhost and port as defined in PortNumber above.
      User   : username@hotmail.com[?Option=Value][&Option=Value][&Option=Value] ...
               with Option=Value pairs from :
               - folder="FolderName" : The folder as displayed in hotmail for
                 the folder you want to interact with. Default : "Inbox".
               - folderid=N : the folderid you want to interact with :
                   1 : Inbox
                   2 : Trash
                   3 : Sent
                   5 : Junk
               - markread=1  : It will mark mails read on your
                 hotmail account if you read them via the the Pop3 Server.
               - keepmsgstatus=1  : Dummy for FreePops compatibility. Does nothing.
                 (remark GetLive doesn't touch statuses unless asked for)
      !Attention ! : "Leave on server" option does work. So if you choose in your
                 email client not to leave messages on the server, they 
                 will be deleted in your hotmail account.

Requirements
============

* UNIX/LINUX
	* Perl - Mine is v5.8.8, feedback on other working versions welcome.
	* curl - Mine is v7.15.5 feedback on other working versions welcome.
         - v7.15.4 reported working.
	* curl-ssl 	

* Windows (WIN32)
  * Combination reported working :
    * ActiveState Perl v5.8.8
    * curl.exe v7.10.3 from http://curl.haxx.se/
    * openssl binaries libeay32.dll and libssl.dll version 0.9.7.d 
      from http://curl.haxx.se/

* Cygwin under Windows 
	* Probably as UNIX/LINUX - feedback welcome.

Bugs, Questions, ...
====================

https://sourceforge.net/projects/getlive
