An unofficial blog that watches Google's attempts to move your operating system online since 2005. Not affiliated with Google.

Send your tips to

November 7, 2007

Gmail API for Greasemonkey

Gmail's new version broke many plug-ins and Greasemonkey scripts, so Google decided to come up with a long-term solution: an API for Greasemonkey.
Greasemonkey is an integral part of the web experience for many experienced users. Google acknowledges that some people are going to change their own experience of our web applications regardless of what we do. Resistance, as they say, is futile. It would also be somewhat hypocritical. After all, a Google employee wrote Greasemonkey in the first place [my note: Aaron Boodman], another wrote these scripts to add functionality to Gmail [my note: Mihai Parparita], and a third wrote two books on the subject (and these docs) [my note: Mark Pilgrim].

Instead, we would like to provide a little help to make such scripts more robust. Instead of finding elements by XPath or DOM traversal, this API provides accessor methods for getting common screen elements. Instead of forcing you to monkey-patch (ahem) our internal functions, this API provides callbacks to call your functions when specific events occur.

This API is experimental. New features and code changes may still cause Greasemonkey scripts to break.

The first Greasemonkey script that uses this API is Mihai Parparita's Macro, which brings additional keyboard shortcuts to Gmail, and the rest of his already famous scripts should also be ported to Gmail's new codebase. The API is not meant to expose messages, contacts or settings, it's more like a convenient way to customize Gmail's interface and functionality without relying too much on the implementation's details.


  1. Nice!
    I like that they've seen the requests from hundreds of Greasemonkey addicts and released the API.

    Resistance is futile! Nor should there be any resistance.
    Greasemonkey just makes any sites more comfortable to use (not everyone has the same taste).

  2. No new version for me yet (Sigh!), so I do not have to worry about broken GM plugins.. but then again, why the Gmail updates haven't been implemented to all the accounts? I have never used before a product from an online company that is that slow to update their products.

  3. If the new version is buggy, they screw up only like 5% of their users.
    That's the principle behind their slow changing of systems.

    First users to get new features are somewhat testers of this novelty, in their own way...

  4. The API unfortunately doesn't expose messages themselves, only the views and panes, so you need to do some clever hacks to do things with message bodies. That, however, works both for Greasemonkey and GreaseKit users, which is a good thing in and of itself.

  5. Is there a Greasemonkey script that shows only the unread mail when you click a label?

  6. On November 17, 2009, two API functions, addNavModule() and getNavModule() stopped working. They now throw an exception with the message "Service H is not registered". Is this an intentional change, or a mistake of some kind?

  7. "Gmail's new version broke many plug-ins and Greasemonkey scripts, so Google decided to come up with a long-term solution: an API for Greasemonkey."

    It appears there are some other aspects of the API that are broken again by a new version --- is Google looking into this?

    New issue that affects some key Gmail related Firefox addons like GTDinbox and IntegratedGmail

    And it looks like there are a lot of unaddressed issues on the "Issues" tracker

    I hope someone can look into and fix the recent API issues soon! And keep the API in mind when new changes to Gmail are released.

    Thanks Google!