Hack 80. Program Gmail

Try your hand at writing an alternative interface to Gmail using the freely available Python, Perl, PHP, Java, and .NET libraries and API frameworks.

The relatively simple and lightweight data interface to Gmail stems from the separation between user interface (client-side JavaScript) and data model. This has spawned myriad frontends (graphical and otherwise), libraries, and unofficial "API" implementations in Python, Perl, PHP, Java, and .NET.

For a glimpse of the Gmail engine and protocol underlying the official Gmail interface and the lion's share of the unofficial APIs and libraries written to the service, take a gander at Johnvey Hwang's "About the Gmail engine and protocol" (http://johnvey.com/features/gmailapi/; scroll down).

Programmatic access to Gmail is accomplished by screen-scraping either the web interface or its underlying data format. While the data format is pretty simple and isn't expected to change dramatically, there's no telling what Google might do that could adversely affect the various programmatic interfaces to their service. Thus, it goes without saying that such hackery comes with no quality of service guarantee. In other words, expect breakages. And if you do notice something's gone wrong, visit the home page of your chosen programmatic interface for the latest version of the code, news, and further information.

Rather than taking you step by step through the same code in each of the five languages and frameworks, I provide a walk through in Python. The APIs are all rather similar, which shouldn't come as any great surprise since they are all built upon the Gmail "API" used by the candy-coated JavaScript-powered Gmail Web interface.

6.13.1. Python

The libgmail (http://libgmail.sourceforge.net; GNU Public License 2.0/PSF) Python binding for Gmail provides a nice, clean interface (as you'd expect from Python) to your Gmail account.

Libgmail bundles a lovely set of useful example applications, usable right out of the box:

archive.py: Downloads your Gmail messages to your computer for archiving, importing, or moving purposes.
gmailsmtp.py: Proxies SMTP requests, allowing you to use Gmail to send email from the comfort of your preferred email application; a related script, sendmsg.py, sends a single email message via Gmail from the command line—not unlike using the Unix mail command.
gmailpopd.py: Proxies a standard POP interface to mail from your preferred email application.
gmailftpd.py: Pretends to be an FTP server, allowing you to download (only) messages labeled "ftp" via a standard FTP application.

6.13.1.1 Installing the hack

Installation is just a matter of downloading and unpacking the library (http://sourceforge.net/project/showfiles.php?group_id=113492, or click the Downloads link on the libgmail home page) and putting it someplace findable by Python.

6.13.1.2 The code

Libgmail sports much functionality, each with its own rather self-explanatory function name: getMessagesByQuery, getQuotaInfo, getLabelNames, getMessagesByLabel, getrawMessage, and getUnreadMsgCount. Leaf through libgmail.py for the kind of details only a programmer could love.

Here's a snippet of sample code showing off login, folder selection, and strolling through email—thread by thread, message by message:

#!/usr/bin/python



# libgmail_example.py

# A simple example of the libgmail Python binding for Gmail in action

# http://libgmail.sourceforge.net/

#

# Usage: python gmail_in_python.py



import libgmail



# Login

gmail = libgmail.GmailAccount('raelity@gmail.com', '12bucklemyshoe')

gmail.login( )



# Select a folder, label, or starred messages--in this case, the Inbox

folder = gmail.getMessagesByFolder('inbox')



# Stroll through threads in the Inbox

for thread in folder:

  print thread.id, len(thread), thread.subject



  # Stroll through messages in each thread

  for msg in thread:

    print "  ", msg.id, msg.number, msg.subject

Replace raelity@gmail.com and 12bucklemyshoe with your Gmail email address and password. Instead of inbox, you can use any of Gmail's standard folder names or your custom labels—e.g., starred, sent, or friends.

Save the code to a file called gmail_in_python.py.

6.13.1.3 Running the hack

Run the gmail_in_python.py script on the command line, like so:

$ python libgmail_example.pl

WARNING:root:Live Javascript and constants file versions differ.

ff602fe48d89bc3 1 Hello from Hotmail

   ff602fe48d89bc3 1 Hello from Hotmail

ff5fb9c2829c165 1 Hello Gmail via Gmail Loader

   ff5fb9c2829c165 1 Hello Gmail via Gmail Loader

ff5691f7170cb62 1 Hello Gmail via Gmail Loader

   ff5691f7170cb62 1 Hello Gmail via Gmail Loader

ff3f4310237b607 1 Howdy gmail-lite

   ff3f4310237b607 1 Howdy gmail-lite

6.13.1.4 Hacking the hack

Swap in a call to getMessagesByQuery and you now have a command line right to the Gmail search engine:

#folder = gmail.getMessagesByFolder('inbox')

folder = gmail.getMessagesByQuery('from:rael subject:Howdy')

Here are the results of this little switch:

$ python libgmail_example.pl

WARNING:root:Live Javascript and constants file versions differ.

ff3f4310237b607 1 Howdy gmail-lite

   ff3f4310237b607 1 Howdy gmail-lite

6.13.1.5 See also

gmail.py (http://www.holovaty.com/blog/archive/2004/06/18/1751) is a simple Python interface to Gmail, focusing on exporting raw messages for backup and import.

6.13.2. Perl

Mail::Webmail::Gmail (http://search.cpan.org/~mincus/Mail-Webmail-Gmail-1.00/lib/Mail/Webmail/Gmail.pm) provides Perl hackers a programmatic interface to Gmail. You'll find full POD documentation and more sample code than you can shake a stick it in the module and online at the aforementioned URL.

A Comprehensive Perl Archive Network (CPAN) search for gmail (http://search.cpan.org/search?query=gmail&mode=all) at the time of this writing finds three more Perl Gmail libraries: Mail::Webmail::Gmail, WWW::GMail, and WWW::Scraper::Gmail.

6.13.3. PHP

GMailer or libgmailer (http://gmail-lite.sourceforge.net; GNU Public License) is a PHP library for interacting with Gmail by way of the curl library (http://www.php.net/curl) with SSL support (http://www.openssl.org). It is the engine underlying gmail-lite Hack #76, an HTML-only interface to Gmail.

For full libgmailer documentation and plenty of sample code, leaf through the online documentation (http://gmail-lite.sourceforge.net/docs.html).

6.13.4. Java

G4j or GMail API for Java (http://g4j.sourceforge.net; GNU Public License) is a Java interface to Gmail. The API comes with GMailer for Java, a basic GUI frontend to Gmail built on top of G4j.

Full documentation in Javadoc HTML is available online (http://g4j.sourceforge.net/doc).

6.13.5. .NET

The Gmail Agent API (http://johnvey.com/features/gmailapi; GNU Public License) is a .NET foundation for programming to Gmail. A full package of source for the API itself; the Gmail Agent Applet, a proof of concept Windows frontend to Gmail; and associated Windows Installer projects are available for download.

There's also full documentation available in both HTML format (http://johnvey.com/features/gmailapi/docs) and as Windows Help.

< Day Day Up >