NAME
    WWW::GMail - Perl extension for accessing Google Mail (gmail)

SYNOPSIS
      use WWW::GMail;
  
      my $obj = WWW::GMail->new(
            username => "USERNAME",
            password => "PASSWORD",
            cookies => {
                    autosave => 1,
                    file => "./gmail.cookie",
            },
      );
  
      my $ret = $obj->login();
      if ($ret == -1) {
            print "password incorrect\n";
      } elsif ($ret == 0) {
            print "unable to login $obj->{error}\n";
            exit;
      }
  
      my @list = $obj->get_message_list('inbox');
  
      # count the new messages in the inbox
      my $new_msgs = 0;
      for my $i ( 0 .. $#list ) {
            $new_msgs += $list[$i]->[1]; # count the unread flags
      }
  
      print "you have $new_msgs new messages in your inbox\n";
  
      my @contacts = $obj->get_contact_list();
      print "you have ".(@contacts)." contacts\n";
  
      my $gmail = 0;
      for my $i ( 0 .. $#contacts ) {
            $gmail += ($contacts[$i]->[3] =~ m/gmail\.com$/i);
      }
  
      print "$gmail of them are gmail addresses\n";
  
      $obj->logout();

ABSTRACT
    This module simplifies access to gmail.

DESCRIPTION
    Currently this module allows retrieval of message lists, raw messages,
    and the contact list. All requests to gmail are secured using ssl.

  Methods
    There are currently 5 methods

    "new"
        This will setup the object, useragent and cookie jar.

        The HTTP::Cookies object is stored as $obj->{jar} The LWP::UserAgent
        object is stored as $obj->{ua}

        The new method accepts a hash of options:

        "username"
            GMail username, stored as $obj->{username}

        "password"
            GMail password, stored as $obj->{password}

        "cookies"
            A hash ref of options passed to HTTP::Cookies Specify {} to make
            the session temporary.

        "agent"
            * Optional! A useragent string passed to LWP::UserAgent

    "login"
        Logs into GMail, DO THIS FIRST, duh...

        Return values are: 1 login correct 0 some error happend, check
        $obj->{error} for reason -1 incorrect password and/or username

    "get_message_list"
        This method returns an array of arrays Each array has an array ref
        of info about the message Currenly, WWW::GMail doesn't strip the
        html entities, do that yourself for now. A future version will have
        an option passed to new() to adjust this.

        The array

              0     message id (pass this to get_message_raw)
              1     unread = 1,read = 0
              2     starred = 1,not = 0
              3     date
              4     from
              5     indicator
              6     subj
              7     sent
              8     labels
              9     attachments
              10    message id (again?)
              11    ? unknown
              12    full date

        See the SYNOPSIS

        Also available after calling get_message_list is:

          Used space    $self->{used}
          Total space   $self->{total}
          Percent used  $self->{percent_used}
          Per page      $self->{per_page}
          List total    $self->{list_total}
          List folder   $self->{list_folder}

          Labels        $self->{labels} (an array of arrays)
  
          The array
                 0      label
                 1      number of new

    "get_message_raw"
        Pass it a message id from a message list (see get_message_list)
        Retrieves the raw message as a scalar, headers and all. Returns
        undef if there was an error or invalid id Check $obj->{error} for
        messages

    "get_contact_list"
        Returns all contacts in an array of arrayrefs. Contact id is not
        strictly a number. I have ids such as 11b, be, 1b, d2, 117, 11f

        Each array ref has

              0     Contact id
              1     Name
              2     Name or blank (not sure what this is)
              3     Email
              4     Notes

    "logout"
        Logs out the current logged in account.

EXPORT
    Nothing. Its all Object Orientated.

SEE ALSO
    LWP::UserAgent, HTTP::Cookies

TODO
    Contact management, label management, and better docs. Also, what
    happends when the js_version changes? Enable persistant cookie?

AUTHOR
    David Davis <xantus@cpan.org>

NOTICE
    **Use this module at your own risk, and read your Gmail terms of use**

COPYRIGHT AND LICENSE
    Copyright 2004-2005 by David Davis and Teknikill Software

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.