Looking for info on new Gmail UI? The InboxSDK is committed to supporting all versions of gmail. More Info
The InboxSDK is a library for building browser extensions for Gmail and soon Inbox too. It provides APIs for browser extensions to interact with and extend the Gmail and Inbox UI. The SDK is built so that multiple extensions can use it on a page at once without conflicting with each other.
Note: Don't forget to register for an AppId to run your app in production, it's quick and free: AppId Registration
The library is intended to facilitate the creation of extensions like our Streak extension. The library is sophisticated enough for the Streak extension itself to be built on, but the library does not provide facilities for other extensions to interact with user data specific to the Streak extension (pipelines, boxes, etc.). To integrate with Streak itself, see the Streak API docs.
InboxSDK's support for Gmail is mature and proven in extensions used by millions of users. We're still developing our support for Google Inbox, and developers can opt in early to try out the InboxSDK in Inbox.
Download the SDK here:
Here's how simple it is to build a basic app, you need two files:
myapp.js which is your application code that interacts with the SDK, and the
manifest.json which describes a basic Chrome extension.
To test your new app, open Chrome to
chrome://extensions and check the "Developer Mode" checkbox. Then click on "Load Unpacked Extension" and point it to your extension directory. Next, open Gmail and stand in awe. For more details on testing Chrome extensions, see Chrome Getting Started Docs.
Browser extensions built using the InboxSDK are structured like normal browser extensions. You must additionally:
inboxsdk.jsshould be placed inside your extension directory
info.plist(Safari) needs to list the above file as a content script which runs on "https://mail.google.com" and "https://inbox.google.com"
For more basics of Chrome extensions, see: Chrome Extension Reference
For more basics of Safari extensions, see: Safari Extension Reference
The simplest and easiest way to use the SDK is to have a
myapp.js file placed inside your extension.
This file will then load the SDK using
The previous method, while simple, implies that you must release a new extension (typically to the Chrome Web Store) if you want to make changes to the app. For high usage or frequently updated apps, you may not want to wait for the chrome extension system to update all your users extensions to the latest version.
To handle this scenario, you can host your actual application code on your own server (or somewhere convenient) and remotely load it when needed. This allows you to make updates to it and your users will simply need to refresh Gmail to get the changes.
The InboxSDK has convenient functions for remotely loading your application code, you'll need the following files.
You may want to load other JS libraries like mapping or charting libraries for your application to use. You
can compile these libraries directly into your
myapp.js (for libraries like jquery, this may
make sense), but sometimes you may want to remotely load these instead.
We recommend that you load these dependencies in your
myapp.js file so that they can be updated
in the same way your application can.
To use the InboxSDK, you must include the
inboxsdk.js file in your extension.
This file is just a small shim and is only responsible for remotely loading the full implementation of the SDK. This
is done so that the actual implementation of the SDK can be updated to keep compatibility with Gmail without
requiring you to update your extension for every change. The implementation is often updated to maintain
compatibility with Gmail, fix bugs, and add new SDK features. All that is required for your end users to reap
this benefit is for them to refresh Gmail in their browser.
Since the SDK is remotely loaded, you can't start interacting with it until its been loaded.
Several methods in the InboxSDK return
View types. These
View classes have a variety of functionality
depending on the UI element they represent. However, one critical commonlaity is that they are all
This means that you can subscribe to a variety of events that each
The events they emit are all documented in their respective documentation sections (i.e. see
destroy event and have their
property set to true when they are no longer available in the page. It's
often useful to subscribe to this event and then cleanup any
resources/memory/references you may no longer need. Performance inside
Gmail/Inbox is important to maintain, so it's critical you release any
relevant resources when this event is emitted.
To subscribe to events, refer to the documentation for
Here's a simple example showing how to subscribe to events:
The SDK is currently at version
2 and when loading the SDK that is the number you should specify.
The SDK may add backwards compatible API's to the current version, but incompatible changes
will come with a version update. Your code is guranteed to work so long as you specify the correct version number
AND that version number is at most two releases old.
We've developed several sample extensions that demostrate the use of the InboxSDK. The examples are all hosted on GitHub. If you'd like to help develop more samples, let us know!
We've been hard at work at getting the InboxSDK to work in Google's Inbox too, and we're finally ready to make our initial support public!
To opt in now, pass
2 as the API version parameter to
InboxSDK.load. This will enable the InboxSDK on Google Inbox. This will also disable all previously-deprecated functionality, so if you were getting warnings in the console before from the InboxSDK, then those will be upgraded to errors.
Many APIs have support now, but not all of them. We've annotated our API documentation with Gmail and Inbox icons to show the current status of support. Please let us know if you run into any issues while using the SDK in Inbox, or have functionality in mind that you want to see ported over soon!
Here is a simple example of creating a promise that resolves to a value after a second, and then an example of how to listen to the promise:
In order to create streams, you must include one of the above libraries in your extension. Here is an example of creating and then consuming a stream using the Kefir library:
Note that reactive libraries often contain many specialized functions for creating streams from timers, event listeners, and other streams. This example purposefully uses a general method instead that can be quickly adapted to many uses. The above example should be enough to show you how to interact with the InboxSDK's stream-compatible methods, but if you want more information on reactive streams in order to use them more effectively, some recommended resources include the documentation of the above libraries, Netflix's talk on Reactive Programming, and The introduction to Reactive Programming you've been missing.
Chrome and Safari are currently supported. Chrome version 36 and Safari 10 are the minimum versions we support.
Firefox support is under consideration; please let us know if you're interested.
The InboxSDK loads its code remotely from our servers, so users get the latest code and bug fixes automatically without extension developers being required to make any changes. We also often introduce new features over time, and on occasion we deprecate old APIs and recommend new ones. These API changes will be listed here and announced in emails to registered developers as necessary.
2019-06-13 Removed the limitation on ContentPanelView.open() where it could only be used within a user-input event. The limit was made to discourage extensions from being too aggressive with opening the sidebar, but this limit seemed to be too restrictive.
2019-06-13 Added Lists.getSelectedThreadRowViews() and Lists.registerThreadRowViewSelectionHandler() methods for detecting selected thread rows.
2019-05-29 Fixed an issue caused by a Gmail change that caused ComposeView.getDraftID() to not work in some situations.
2019-04-30 Added ComposeView.addComposeNotice() method to allow adding HTML elements in the compose view.
2019-02-24 Improved ListRouteView.addCollapsibleSection and ListRouteView.addSection so that if a user leaves the ListRouteView and then returns to it, their scroll position is correctly restored, adjusted for the new sections' heights.
2019-02-11 Fixed an issue where custom thread lists could cause a Gmail error message to be displayed while open.
2019-02-11 Fixed an issue where custom thread lists may have threads shown in the wrong order.
2019-02-06 Fixed an issue where ListRouteView.addCollapsibleSection didn't support the iconUrl and iconClass options being used together on a row.
2019-02-06 Fixed an issue where some MessageView methods could cause the "Show details" dropdown on a message to close itself. (Some methods that read information about the message work by opening the details dropdown, reading text out of it, and then closing it. These methods didn't account for the situation where the dropdown was already open.)
2019-02-05 Changed Router.goto to return a Promise (instead of undefined) that resolves once the navigation is complete. Some kinds of navigations to Gmail pages require the InboxSDK to do some work asynchronously before the navigation can happen.
2019-01-24 Fixed an issue where MessageView.getMessageIDAsync sometimes returned an incorrect value after a pre-existing reply draft was sent.
2019-01-18 Fixed an issue where ComposeView sent events weren't emitted in some cases when conversation mode was disabled in Gmail.
2019-01-16 Fixed multiple issues that could cause incorrect ComposeView sent events.
2018-12-31 Fixed an issue where MessageView.getSender threw an exception on collapsed messages.
2018-12-03 Fixed an issue caused by a Gmail change that caused ComposeView.getRecipientEmailAddresses and ComposeView.getRecipientsFull to fail sometimes.
2018-11-13 Fixed an issue where MoleViews were not moved to the left out of the way of the sidebar when an InboxSDK-created sidebar was opened.
2018-11-02 Fixed an issue where switching between multiple sidebars added by Global.addSidebarContentPanel didn't always work correctly.
2018-10-10 Added ContentPanelView.open method.
2018-08-31 Fixed an issue caused by a Gmail change that caused link chips added by ComposeView.insertLinkChipIntoBodyAtCursor to not show up in forwarded emails.
2018-07-31 Fixed multiple issues where a global or thread sidebar would fail to load if the sidebar was added before certain Gmail elements were present in the page.
2018-07-31 Added the ContentPanelView.isActive method.
2018-07-23 Fixed an issue caused by a Gmail change where Widgets.showMoleView() sometimes failed to render a MoleView correctly.
2018-07-09 Fixed an issue caused by a Gmail change where the ComposeView sent event could contain the wrong message and thread IDs.
2018-07-06 Fixed an issue caused by a Gmail change where Router.goto could no longer navigate to Gmail threads.
2018-06-27 Fixed an issue caused by a Gmail change where links created by Router.createLink to custom views would not work.
2018-05-17 Fixed an issue causing AttachmentCardClickEvent.getDownloadURL() to not work sometimes in the Gmail redesign.
2018-05-09 Fixed an issue where ComposeView's sent event didn't fire in some situations.
2017-07-26 Lists.registerThreadRowViewHandler, ThreadRowView.addLabel, ThreadRowView.addImage, ThreadRowView.replaceDraftLabel, ThreadRowView.getSubject, ThreadRowView.getThreadIDAsync, ThreadRowView.getThreadIDIfStableAsync, ThreadRowView.getDraftID, ThreadRowView.getVisibleDraftCount, ThreadRowView.getVisibleMessageCount, and ThreadRowView.getContacts are now all supported in Inbox.
2017-06-22 The ComposeView "sent" event is now properly supported in Inbox. Its threadID and messageID properties have been deprecated in favor of its new asynchronous getThreadID() and getMessageID() methods.
2017-06-14 Deprecated the getThreadID, getThreadIDIfStable, and getMessageID methods of ThreadView, ThreadRowView, and MessageView in favor of getThreadIDAsync, getThreadIDIfStableAsync, and getMessageIDAsync methods. This is done because it turns out that in some cases in Inbox the InboxSDK needs to make network requests against Gmail in order to correctly resolve the ID.
2017-06-14 Fixed the modal and its backdrop to display over any open DrawerView.
2017-05-16 Fixed an issue where MessageView.getBodyElement() would on a message if it was an exact duplicate of a previous message within the same thread. (Surprisingly, Gmail put a different classname on the element in that specific case.)
2017-04-13 The InboxSDK was updated to deal with changes to the format of some of Gmail's network requests. The custom thread list feature was briefly broken today after Gmail's change and before our update.
2017-04-11 Inbox support for ComposeView's getDraftID() method and some of its events was added.
2017-01-23 Our initial Inbox support is live!
2017-01-09 The new ThreadView sidebar design has replaced the old design after an opt-in period.
2016-11-14 The ThreadView sidebar has been re-designed, and developers are encouraged to opt-in, try out the new design, and give feedback before it becomes the default.
2016-09-14 Added the DrawerView.associateComposeView method.
2016-08-18 Added the AttachmentCardClickEvent.getDownloadURL() method, and deprecated the AttachmentCardView.getDownloadURL() method. In Inbox, the download URL of an attachment card view can't be retrieved until after the card's preview overlay has been opened by the user, so the API has been restructured to reflect this.
2016-08-09 Added the Conversations.registerFileAttachmentCardViewHandler() method to allow AttachmentCardViews to be handled directly rather than require them to be retrieved from a MessageView instance. Google Inbox often shows attachment cards outside of messages, so this API is being introduced to allow code to be made forward-compatible with that case now.
2015-12-14 Added the ComposeView.getCurrentDraftID() method to allow determining whether a ComposeView has been assigned a draft ID yet.
2015-12-10 Added the ThreadRowView.getDraftID() method to allow identifying the draft ID from a thread row that represents a draft.
2015-12-09 Added the ComposeView.getDraftID() method.
2015-06-17 Added the ComposeView.getInitialMessageID() method and the "messageID" property on the ComposeView destroy event object. The ComposeView.getMessageID() method and the ComposeView messageIDChange event have been deprecated as they weren't dependable for use directly because there was no guarantee that the message ID hadn't been changed on the server by the time a user tried to do anything with the message ID.
2015-06-26 Deprecate User.getUserContact() in favor of User.getEmailAddress() because it seems that there are situations that the page doesn't contain the data we need to meet the API of User.getUserContact(), and its usage is rare.
2015-06-17 Added the Widgets.showMoleView() method.
Questions? Bugs? Feature Requests? Our team is active on our InboxSDK mailing list, ask away!