Mail::Webmail::Gmail - An interface to Google's webmail service
# 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"; } }
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.
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.
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.
Returns an array of all user defined labels.
my @labels = $gmail->get_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 );
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 );
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 );
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' } $indv_email{ 'sender' } $indv_email{ 'subject' } $indv_email{ 'blurb' } @{ $indv_email{ 'labels' } } @{ $indv_email{ 'attachments' } }
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%" ]
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' } $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 => '', );
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"] );
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 );
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.
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\>»\</b\> ","\<b\>Subject\</b\>","Blurb …",["label1","label 2"] ,"attachment name1, attachment name2","MSG ID",0] ] ); D(["te"]); //--></script><script>var fp='';</script><script>var loaded=true;D(['e']);</script>
below is a listing of some of the tests that I use as I test various features
my ( $gmail ) = Mail::Webmail::Gmail->new( username => 'username', password => 'password', ); ### Test Sending Message #### my $msgid = $gmail->send_message( to => 'testuser@test.com', subject => time(), msgbody => 'Test' ); print "Msgid: $msgid\n"; if ( $msgid ) { 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"; } } } } ### ### 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"; } } ### ### Prints out new messages attached to the first label my @labels = $gmail->get_labels(); my $messages = $gmail->get_messages( label => $labels[0] ); if ( defined( $messages ) ) { foreach ( @{ $messages } ) { if ( $_->{ 'new' } ) { print "Subject: " . $_->{ 'subject' } . " / Blurb: " . $_->{ 'blurb' } . "\n"; } } } ### ### Prints out all attachments $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 $messages = $gmail->get_messages( label => $Mail::Webmail::Gmail::FOLDERS{ 'INBOX' } ); print @{ $messages } . "\n"; 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 $messages = $gmail->get_messages(); print "By folder\n"; foreach ( keys %Gmail::FOLDERS ) { my $messages = $gmail->get_messages( label => $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"; } } ###
Copyright 2004, Allen Holman. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Address bug reports and comments to: mincus \at cpan \. org. Or through AIM at mincus c03.
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.
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)
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.