Scripting Gmail: A short example


So unfortunately, the guy who developed libgmail has stopped upkeep, and most likely, the version you have is defunct. HOWEVER: There is an updated version of libgmail. Share and enjoy.

I was working on a project once where I needed to download some Google Alert e-mails from a Gmail account and automatically download and organize the data linked from the e-mails. It may or may not sound complicated depending on who you are, but I found a little module called libgmail to be invaluable.

It’s basically an API that, as far as I can tell, interacts with the Gmail Web interface.

You may be asking yourself what benefit this has over, say, accessing your Gmail using IMAP or POP3. I’ll tell you: queries. See, in the Gmail Web interface, you can run queries on your e-mail in the search box, such as from:hilary to get all e-mail correspondence between you and anyone named Hilary. You can do that with domain names as well ( to get anyone who has sent you mail from a Gmail address. You can also combine those with things like is:unread, is:starred, label:inbox or label:work. You get the picture — you can have very specific views of your data, and we can tap into this power using Python with libgmail

So let’s go through a basic script. Once you’ve downloaded and installed libgmail (you must install the mechanize module as a prerequisite), open up your Python interpreter and type this:

>>> import libgmail
>>> ga = libgmail.GmailAccount("", "PASSWORD")
>>> ga.login()
>>> threads = ga.getMessagesByQuery("label:work is:unread", allPages=True)
>>> len(threads)

Fair warning, with allPages=True in the getMessagesByQuery function, it could take a while. If you just want to test to see if this works, set allPages=False.This should print out the number of e-mail threads you’ve filtered to a “work” label, just to see how much of a slacker you’re really being. I get a fairly high number, and I’m sure you will too.

Now, to see the subjects of the last 10 threads you’ve not read in your work e-mail, type this at your console:

>>> for thread in threads[0:10]:
...     print "%s (%s)" % (thread.subject, len(thread))

This should print out something like:

<b>tuesday's page schedule</b> (1) <b>Final Notice -- Free Picture Frame Offer</b> (1) ...


What the previous code did was loop through a slice of the first 10 e-mails, printing out the subject (unread e-mails are bold in Gmail, hence the <b></b> tag pairs.) and number of e-mails in the thread. A “thread” in Gmail is a collection of related messages.

In any case, this is just a small sliver of what you can do with libgmail. I suggest you download the latest version and documentation to figure out a little more of what it can do. The downloads even include sample scripts to give you a hand.


4 Responses to “Scripting Gmail: A short example”

  1. Works like a charm. I can see a lot of powerful uses for this.

  2. To anyone finding this:
    libgmail seems officially defunct.
    ‘Sunday December 13th 2009 ( )
    Unfortunately the GmailFS project has come to an end. libgmail has ceased being maintained by its developers, and as a result libgmail no longer works with the latest Gmail interface (and has not done so for many weeks).’

    If anyone wants a barebones ( no exception checking ) example of how to write an Google IMAP interface, mine might be useful. Think of it more as a starting point than a user ready script:

  3. 3 schwanksta

    Hey Vera,

    There’s actually an updated version here: – Check it out. Of course, no guarantees this will work forever. I’ve edited the post to add this in. Thanks for the comment (sorry it took me forever to moderate it!)


  4. Hey Ken,

    Just following up since I got a spike of traffic that was referring from here. Looks like Anton’s site is defunct now as well. Any updates to libgmail?


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: