NAME

Mail::Webmail::Gmail - An interface to Google's webmail service

SYNOPSIS

# Perl script that logs in to Gmail, retrieves the user defined labels
# Then prints out all new messages under the first label

use Mail::Webmail::Gmail;

my $gmail = Mail::Webmail::Gmail->new( 
            username => 'username', password => 'password',
        );

my @labels = $gmail->get_labels();

my $messages = $gmail->get_messages( label => $labels[0] );

foreach ( @{ $messages } ) {
    if ( $_->{ 'new' } ) {
        print "Subject: " . $_->{ 'subject' } . " / Blurb: " . $_->{ 'blurb' } . "\n";
    }
}

ABSTRACT

This perl module uses objects to make it easy to interface with Gmail. I eventually hope to implement all of the functionality of the Gmail website, plus additional features.

DESCRIPTION

Because Gmail is currently in Beta testing, expect this module to break as they make updates to thier interface. I will attempt to keep this module in line with the changes they make, but, if after updating to the newest version of this module, the feature that you require still doesn't work, please contact me with the issue.

STARTING A NEW GMAIL SESSION

The standard call for starting a new Gmail session is simply

my $gmail = Mail::Webmail::Gmail->new( username => 'username', password => 'password', );

This module does support the use of a proxy server

my $gmail = Mail::Webmail::Gmail->new( username => 'username', password => 'password', 
            proxy_username => 'proxy_username',
            proxy_password => 'proxy_password',
            proxy_name => 'proxy_server' );

By default, this module only encrypts the logon process. To encrypt the entire session, use the argument encrypt_session

my $gmail = Mail::Webmail::Gmail->new( username => 'username', password => 'password', encrypt_session => 1 );

After that, you are free to start making requests for data.

RETRIEVING LABELS

Returns an array of all user defined labels.

my @labels = $gmail->get_labels();

EDITING LABELS

There are five actions that can currently be preformed on labels. As a note, this module enforces Gmail's limits on label creation. A label cannot be over 40 characters, and a label cannot contain the character '^'. On failure, error and error_msg are set.

#creating new labels.
$gmail->edit_labels( label => 'label_name', action => 'create' );

#renaming existing labels.
$gmail->edit_labels( label => 'label_name', action => 'rename', new_name => 'renamed_label' );

#deleting labels.
$gmail->edit_labels( label => 'label_name', action => 'delete' );

#adding a label to a message.
$gmail->edit_labels( label => 'label_name', action => 'add', msgid => $message_id );

#removing a label from a message.
$gmail->edit_labels( label => 'label_name', action => 'remove', msgid => $message_id );

UPDATING PREFERENCES

The following are the seven preferences and the allowed values that can currently be changed through Mail::Webmail::Gmail

keyboard_shortcuts = ( 0, 1 )
indicators         = ( 0, 1 )
snippets           = ( 0, 1 )
max_page_size      = ( 25, 50, 100 )
display_name       = ( '', string value up to 96 Characters )
reply_to           = ( '', string value up to 320 Characters )
signature          = ( '', string value up to 1000 Characters )

Changing preferences can be accomplished by simply sending the preference(s) that you want to change, and the new value.

$gmail->update_prefs( indicators => 0, reply_to => 'test@test.com' );

To delete display_name, reply_to, or signature simply send a blank string as in the following example.

$gmail->update_prefs( signature => '' );

STARRING A MESSAGE

To star or unstar a message use these examples

#star
$gmail->edit_star( action => 'add', 'msgid' => $msgid );

#unstar
$gmail->edit_star( action => 'remove', 'msgid' => $msgid );

ARCHIVING

To archive or unarchive a message use these examples

#archive
$gmail->edit_archive( action => 'archive', 'msgid' => $msgid );

#unarchive
$gmail->edit_archive( action => 'unarchive', 'msgid' => $msgid );

RETRIEVING MESSAGE LISTS

By default, get_messages returns a reference to an AoH with the messages from the 'all' folder. To change this behavior you can either send a label

my $messages = $gmail->get_messages( label => 'work' );

Or request a Gmail provided folder using one of the provided variables

'INBOX'
'STARRED'
'SPAM'
'TRASH'

Ex.

my $messages = $gmail->get_messages( label => $Mail::Webmail::Gmail::FOLDERS{ 'INBOX' } );

The Array of hashes is in the following format

$indv_email{ 'id' }
$indv_email{ 'new' }
$indv_email{ 'starred' }
$indv_email{ 'date_received' }
$indv_email{ 'sender_email' }
$indv_email{ 'subject' }
$indv_email{ 'blurb' }
@{ $indv_email{ 'labels' } }
@{ $indv_email{ 'attachments' } }

SPACE REMAINING

Returns a scalar with the amount of MB remaining in you account.

my $remaining = $gmail->size_usage();

If called in list context, returns an array as follows. [ Used, Total, Percent Used ] [ "0 MB", "1000 MB", "0%" ]

INDIVIDUAL MESSAGES

There are two ways to get an individual message:

By sending a reference to a specific message returned by get_messages

#prints out the message body for all messages in the starred folder
my $messages = $gmail->get_messages( label => $Mail::Webmail::Gmail::FOLDERS{ 'STARRED' } );
foreach ( @{ $messages } ) {
    my $message = $gmail->get_indv_email( msg => $_ );
    print "$message->{ $_->{ 'id' } }->{ 'body' }\n";
}

Or by sending a message ID and Label that the message resides in

#retrieve specific email message for review
my $msgid = 'F000000000';
my $message = $gmail->get_indv_email( id => $msgid, label => 'label01' );
print "$message->{ $msgid }->{ 'body' }\n";

returns a Hash of Hashes containing the data from an individual message in the following format:

Hash of messages in thread by ID

$indv_email{ 'id' }
$indv_email{ 'sender_email' }
$indv_email{ 'sent' }
$indv_email{ 'to' }
$indv_email{ 'read' }
$indv_email{ 'subject' }
@{ $indv_email{ 'attachments' } }

#If it is the main message in the thread
$indv_email{ 'body' }
%{ $indv_email{ 'ads' } } = (
    title       => '',
    body        => '',
    vendor_link => '',
    link        => '', );

MIME MESSAGES

This will return an individual message in MIME format.

The parameters to this function are the same as get_indv_email.

#prints out the MIME format for all messages in the inbox
my $messages = $gmail->get_messages( label => $Mail::Webmail::Gmail::FOLDERS{ 'INBOX' } );
foreach ( @{ $messages } ) {
    my $message = $gmail->get_mime_email( msg => $_ );
    print $message
}

returns a string that contains the MIME formatted email.

RETRIEVING CONTACTS

The get_contacts method returns a reference to an AoH with all of the Contacts. This can be limited to the 'Frequently Mailed' contacts with a flag:

my $contacts = $gmail->get_contacts( frequent => 1 );

The Array of hashes is in the following format

$indv_contact{ 'id' }
$indv_contact{ 'name1' }
$indv_contact{ 'name2' }
$indv_contact{ 'email' }
$indv_contact{ 'note' }

SENDING MAIL

The basic format of sending a message is

$gmail->send_message( to => 'user@domain.com', subject => 'Test Message', msgbody => 'This is a test.' );

To send to multiple users, send an arrayref containing all of the users

my $email_addrs = [
    'user1@domain.com',
    'user2@domain.com',
    'user3@domain.com', ];
$gmail->send_message( to => $email_addrs, subject => 'Test Message', msgbody => 'This is a test.' );

You may also send mail using cc and bcc.

To attach files to a message

$gmail->send_message( to => 'user@domain.com', subject => 'Test Message', msgbody => 'This is a test.', file0 => ["/tmp/foo"], file1 => ["/tmp/bar"] );

DELETE MESSAGES

Use the following to move a message to the trash bin

$gmail->delete_message( msgid => $msgid, del_message => 0 );

To permanently delete a message, just send a msgid

$gmail->delete_message( msgid => $msgid );

ACTING ON MULTIPLE MESSAGES

To act on multiple messages at once send an array ref containing all of the message IDs you with to act on. This is useful because Gmail may temporarily ban you if you send too much traffic in a short amount of time (for instance deleting all of the messaging in your SPAM folder one at a time).

### Delete Many Messages at once ###
$gmail->delete_message( msgid => \@msgids, search => 'spam', del_message => 1 );

### Applying a label to multiple messages at once ###
$gmail->edit_labels( label => 'label_name', action => 'add', msgid => \@msgids );

GETTING ATTACHMENTS

There are two ways to get an attachment:

By sending a reference to a specific attachment returned by get_indv_email

#creates an array of references to every attachment in your account
my $messages = $gmail->get_messages();
my @attachments;

foreach ( @{ $messages } ) {
    my $email = $gmail->get_indv_email( msg => $_ );
    if ( defined( $email->{ $_->{ 'id' } }->{ 'attachments' } ) ) {
        foreach ( @{ $email->{ $_->{ 'id' } }->{ 'attachments' } } ) {
            push( @attachments, $gmail->get_attachment( attachment => $_ ) );
            if ( $gmail->error() ) {
                print $gmail->error_msg();
            }
        }
    }
}

Or by sending the attachment ID and message ID

#retrieve specific attachment
my $msgid = 'F000000000';
my $attachid = '0.1';
my $attach_ref = $gmail->get_attachment( attid => $attachid, msgid => $msgid );

Returns a reference to a scalar that holds the data from the attachment.

SAMPLE GMAIL OUTPUT

This is included so you can get an idea of what the underlying HTML looks like for Gmail. It is also included to somewhat document what the current interface needs to manipulate to extract data from Gmail.

<html><head><meta content="text/html; charset=UTF-8" http-equiv="content-type"></head>
<script>D=(top.js&&top.js.init)?function(d){top.js.P(window,d)}:function(){};
if(window==top){top.location='/gmail?search=inbox&view=tl&start=0&init=1&zx=VERSION + RANDOM 9 DIGIT NUMBER&fs=1';}
</script><script><!--
D(["v","fc5985703d8fe4f8"]
);
D(["p",["bx_hs","1"]
,["bx_show0","1"]
,["bx_sc","1"]
,["sx_dn","username"]
]
);
D(["i",0]
);
D(["qu","0 MB","1000 MB","0%","#006633"]
);
D(["ds",1,0,0,0,0,0]
);
D(["ct",[["label 1",1]
,["label 2",0]
,["label 3",1]
]
]
);
D(["ts",0,50,10,0,"Inbox","",13]
);
D(["t",["MSG ID",1,0,"\<b\>12:53am\</b\>","\<span id=\'_user_sender@domain.com\'\>Sender Name\</span\>
","\<b\>&raquo;\</b\>&nbsp;","\<b\>Subject\</b\>","Blurb &hellip;",["label1","label 2"]
,"attachment name1, attachment name2","MSG ID",0]
]
);

D(["te"]);

//--></script><script>var fp='';</script><script>var loaded=true;D(['e']);</script>

SAMPLE TEST SCRIPTS

below is a listing of some of the tests that I use as I test various features

SAMPLE USAGE

my ( $gmail ) = Mail::Webmail::Gmail->new( 
        username => 'username', password => 'password', );

### Test Sending Message ####
my $msgid = $gmail->send_message( to => 'mincus@gmail.com', subject => time(), msgbody => 'Test' );
if ( $msgid ) {
    print "Msgid: $msgid\n";
    if ( $gmail->error() ) {
        print $gmail->error_msg();
    } else {
        ### Create new label ###
        my $test_label = "tl_" . time();
        $gmail->edit_labels( label => $test_label, action => 'create' );
        if ( $gmail->error() ) {
            print $gmail->error_msg();
        } else {
            ### Add this label to our new message ###
            $gmail->edit_labels( label => $test_label, action => 'add', 'msgid' => $msgid );
            if ( $gmail->error() ) {
                print $gmail->error_msg();
            } else {
                print "Added label: $test_label to message $msgid\n";
            }
        }
    }
} else {
    if ( $gmail->error() ) {
        print $gmail->error_msg();
    }
}
###

### Move message to trash ###
my $msgid = $gmail->send_message( to => 'testuser@test.com', subject => "del_" . time(), msgbody => 'Test Delete' );
if ( $gmail->error() ) {
    print $gmail->error_msg();
} else {
    $gmail->delete_message( msgid => $msgid, del_message => 0 );
    if ( $gmail->error() ) {
        print $gmail->error_msg();
    } else {
        print "MSG: $msgid moved to trash\n";
    }
}
###

### Delete all SPAM folder messages ###
my $messages = $gmail->get_messages( label => $Mail::Webmail::Gmail::FOLDERS{ 'SPAM' } );
if ( @{ $messages } ) {
    my @msgids;
    foreach ( @{ $messages } ) {
        push( @msgids, $_->{ 'id' } );
    }
    $gmail->delete_message( msgid => \@msgids, search => 'spam', del_message => 1 );
    if ( $gmail->error() ) {
        print $gmail->error_msg();
    } else {
        print "Deleted " . @msgids . " Messages\n";
    }
}
###

### Print out all user defined labels
my @labels = $gmail->get_labels();
foreach ( @labels ) {
    print "Label: '" . $_ . "'\n";
}
###

### Prints out all _New_ messages attached to the first label
my @labels = $gmail->get_labels();
unless ( $gmail->error() ) {
    my $messages = $gmail->get_messages( label => $labels[0] );
    unless( $gmail->error() ) {
        if ( defined( $messages ) ) {
            foreach ( @{ $messages } ) {
                if ( $_->{ 'new' } ) {
                    print "Subject: " . $_->{ 'subject' } . " / Blurb: " . $_->{ 'blurb' } . "\n";
                }
            }
        }
    } else {
        print $gmail->error_msg();
    }
} else {
    print $gmail->error_msg();
}
###

### Prints out all attachments
my $messages = $gmail->get_messages();

foreach ( @{ $messages } ) {
    my $email = $gmail->get_indv_email( msg => $_ );
    if ( defined( $email->{ $_->{ 'id' } }->{ 'attachments' } ) ) {
        foreach ( @{ $email->{ $_->{ 'id' } }->{ 'attachments' } } ) {
            print ${ $gmail->get_attachment( attachment => $_ ) } . "\n";
            if ( $gmail->error() ) {
                print $gmail->error_msg();
            }
        }
    }
}
###

### Prints out the vendor link from Ads attached to a message
my $messages = $gmail->get_messages( label => $Mail::Webmail::Gmail::FOLDERS{ 'INBOX' } );

foreach ( @{ $messages } ) {
    print "ID: " . $_->{ 'id' } . "\n";
    my %email = %{ $gmail->get_indv_email( msg => $_ ) };
    if ( $email{ $_->{ 'id' } }->{ 'ads' } ) {
        my $ads;
        foreach $ads ( @{ $email{ $_->{ 'id' } }->{ 'ads' } } ) {
            print " - AD LINK: $ads->{vendor_link}\n";
        }
    }
}
###

### Shows different ways to look through your email
my $messages = $gmail->get_messages();

print "By folder\n";
foreach ( keys %Mail::Webmail::Gmail::FOLDERS ) {
    print "KEY: $_\n";
    my $messages = $gmail->get_messages( label => $Mail::Webmail::Gmail::FOLDERS{ $_ } );
    print "\t$_:\n";
    if ( @{ $messages } ) {
        foreach ( @{ $messages } ) {
            print "\t\t$_->{ 'subject' }\n";
        }
    }
}

print "By label\n";
foreach ( $gmail->get_labels() ) {
    $messages = $gmail->get_messages( label => $_ );
    print "\t$_:\n";
    if ( defined( $messages ) ) {
        if ( @{ $messages } ) {
            foreach ( @{ $messages } ) {
                print "\t\t$_->{ 'subject' }\n";
            }
        }
    }
}

print "All (Note: the All folder skips trash)";
$messages = $gmail->get_messages();
if ( @{ $messages } ) {
    foreach ( @{ $messages } ) {
        print "\t\t$_->{ 'subject' }\n";
    }
}
###

### Update preferences
    if ( $gmail->update_prefs( signature => 'Test Sig.', max_page_size => 100 ) ) {
        print "Preferences Updated.\n";
    } else {
        print "Unable to update preferences.\n";
    }
###

### Show all contact email addresses
my ( @contacts ) = @{ $gmail->get_contacts() };
foreach ( @contacts ) {
    print $_->{ 'email' } . "\n";
}
###

### Print out space remaining in mailbox
my $remaining = $gmail->size_usage();
print "Remaining: '" . $remaining . "'\n";
###

AUTHOR INFORMATION

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Address bug reports and comments to: email: mincus \at cpan \. org AIM: mincus c03 Website: http://code.mincus.com

When sending bug reports, please provide the version of Gmail.pm, the version of Perl and the name and version of the operating system you are using.

CREDITS

I'd like to thank the following people who gave me a little direction in getting this module started (whether they know it or not)

Simon Drabble (Mail::Webmail::Yahoo)
Erik F. Kastner (WWW::Scraper::Gmail)
Abiel J. (C# Gmail API - http://www.migraineheartache.com/)
Daniel Stutz (http://www.use-strict.net)

BUGS

Please report them.

To install Mail::Webmail::Gmail, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mail::Webmail::Gmail

CPAN shell

perl -MCPAN -e shell
install Mail::Webmail::Gmail

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)