I’m happy to announce that I’ve decided to open source Gmailr, a Javascript API for Gmail. It’s the code that is used to run one of my pet projects, 0Boxer, which is an extension for Gmail that turns organizing your inbox into a game.

A few days ago, the 10,000th user signed up for 0Boxer, so I figured this would be a great time to share some of the code that makes the realtime gaming mechanics possible. Go ahead, grab the code and play with it, make your own extensions and apps, and improve it!

A Thorny Road

Developing the code behind Gmailr was fraught with frustration and dead ends. There is no currently supported official javascript API for Gmail. There was a greasemonkey script that was released a few years ago, but is now broken, with no plans from the Gmail team to fix it.

Also, no one else (as far as I know) has released any kind of frontend API for Gmail. And, in order for my app to work, I needed access to the various user actions in the UI — the backend APIs weren’t going to cut it. So, I was stuck writing my own library from scratch.

But this was no easy task. Gmail runs its code through the closure compiler, thereby obfuscating everything. On top of that, Gmail is probably one of the most sophisticated javascript apps out there. Needless to say, I am now intimately familiar with the various DOM elements that make up the Gmail interface, as well as how the data is transported.

A Call to Stop Duplicating Risky Work

I had the chance to actually speak with some people on the Gmail team. Basically, they are reluctant to release any kind of javascript API, for fear of making Gmail slow (ironically, I find Gmail already pretty slow these days). There is no hope in the near future for an official javascript API.

And yet, there are many companies, like Rapportive, Baydin, and Unsubscribe.com that build their own APIs. They’re all building out complex APIs with similar functionality, that can all break independently if Gmail decides to significantly change their app structure (which they inevitably will).

What we really need is for many people to come together and build out a robust and easy-to-use javascript API for Gmail that is shared across many extensions and applications. This is my hope for Gmailr.

Right now, Gmailr is pretty barebones. There are a lot of missing features. However, it has been used for the past half year at 0Boxer, serving thousands of active extension users per week. What I’m hoping for is that developers will improve Gmailr, and over time, it will be the robust API that many developers will find useful.

And maybe, if we get enough apps built on top of it, the Gmail team will take notice.


The architecture of Gmailr and the process of reverse engineering Gmail probably deserves its own blog post. For now, I’ll just show you a quick code snippet of what using Gmailr looks like. If you want more details, head on over to the GitHub repo.

A typical use case looks like this:

Gmailr.init(function(G) {
    G.observe('archive', function(count) {
        alert('Wow, you just archived ' + count + ' emails! Great job!');

Basically, this will show a nice annoying message to the user everytime they archive email. The call to init does a bunch of work to bootstrap the Gmailr API. After that, there is a callback that passes in the API object, which provides the Gmailr API methods.

Let’s say you want to insert some custom DOM elements. That’s easy:

Gmailr.init(function(G) {
    G.insertTop($("<div id='my_div'>Hello World!</div>"));

This will insert a div on the top of the Gmail API, and also inject your own CSS. You can use this to add new features to Gmail.

The Future

I don’t have much time these days to devote to Gmailr. What I’m hoping for is to pass the torch to other developers to improve upon the seedlings. In particular, here are some ways to improve it:

  • Expose methods that allow insertion of UI elements into various places in Gmail, like the sidebar.
  • Improve the reliability of the API, taking into account the various weird states that Gmail can get into.
  • Add capabilities to read the contents and metadata of emails received, sent, and interacted with.

If you want to get in touch, please contact me at jamesjacobyu -AT- gmail.com.

Did you like this post? If so, you might like reading Empathetic Product Development for Hackers.