Gmail.js - JavaScript API for Gmail

What Gmail.js is and isn't

Gmail.js is meant to be used for creating WebExtension-based browser-extensions, for Chrome, Firefox and other compatible browsers.

It cannot be used server-side with Node, or from another web-app to interface with Gmail.

Note: This is not an official Gmail API, and isn't affiliated with Google.

Note: Gmail.js requires jQuery to work

TL;DR Summary

• Lots of API methods to work with gmail. See documentation below.
• Easy to use API. Data & DOM.
• Reasonably complete TypeScript-support.
• Compatible with both WebExtension Manifest V2 and V3.
• Many methods are contextual and will work with whatever is on screen when no arguments are given.
• Obtain email data, react to event, etc. No need for OAuth!
• Main methods allow you to observe certain events with gmail.observe.on('lots_of_actions_here', callback()) or similar gmail.observe.before(...) and gmail.observe.after(...)
• Create an issue/pull request for feedback, requests and fixes. See CONTRIBUTING.md for more details.

Using Gmail.js

If you know how to create WebExtensions-based extensions for Firefox and Chrome, you can get started by pulling Gmail.js like this:

npm install gmail-js

Note: Please ensure that Gmail.js is injected into the regular DOM.

Content-scripts which launch injected script must be configured with "run_at": "document_start".

It's recommended to split injected script to have only gmail.js load first because the size of the injected script impacts the loading time. Gmail.js must be injected and loaded before Gmail loads embedded data.

Gmail.js does not work as a content-script.

For a ready to use example/boilerplate repo, look no further:

• GmailJS Node Boilerplate - Example for how to create a browser-extension using GmailJS and modern javascript with NodeJS and script-bundling for instant load-times.

Content Security Policy (legacy advice)

In earlier advice given w.r.t. deployment of GmailJS, where scripts were injected one by one, with cumbersome loading and probing mechanisms, CSP could be an problem causing your extension to fail if GmailJS was injected incorrectly.

If you use modern javascript and script-bundling in your extension (like in the boilerplate example), CSP will not interfere with loading of your extension, nor GmailJS.

If you have any issues with CSP, the general advice is to build your extension using script-bundling and eliminate the cause of the error all together.

While you may be able to make it work, legacy loading is no longer considered supported by GmailJS.

Typescript

Using gmail-js with TypeScript is relatively easy, but if you use normal import syntax it will fail. Instead you need to use require-syntax to load it:

const GmailFactory = require("gmail-js");
const gmail = new GmailFactory.Gmail() as Gmail;
// working on the gmail-object now provides type-safety.

You will also have to import the types somewhere, like in a file called types.d.ts in your project:

import "gmail-js";

Methods

Summary (click for more info)

GET

• gmail.get.user_email()
• gmail.get.manager_email()

• gmail.get.current_page()

• gmail.get.new.email_id()

• gmail.get.new.email_data()
• gmail.get.new.thread_id()

• gmail.get.new.thread_data()

• gmail.get.email_subject()

• gmail.get.compose_ids()
• gmail.get.email_source_async(identifier=undefined, callback, error_callback, preferBinary)
• gmail.get.email_source_promise(identifier=undefined, preferBinary)
• gmail.get.search_query()
• gmail.get.unread_emails()
• gmail.get.unread_inbox_emails()
• gmail.get.unread_draft_emails()
• gmail.get.unread_spam_emails()
• gmail.get.unread_forum_emails()
• gmail.get.unread_update_emails()
• gmail.get.unread_promotion_emails()
• gmail.get.unread_social_emails()
• gmail.get.last_active()
• gmail.get.storage_info()
• gmail.get.loggedin_accounts()
• gmail.get.beta()
• gmail.get.localization()

GET (deprecated methods)

• gmail.get.thread_id()
• gmail.get.email_id()
• gmail.get.email_ids()
• gmail.get.email_data(email_id=undefined)
• gmail.get.email_data_async(email_id=undefined, callback)
• gmail.get.displayed_email_data()
• gmail.get.displayed_email_data_async(callback)
• gmail.get.selected_emails_data()
• gmail.get.visible_emails()
• gmail.get.visible_emails_async(callback)

CHECK

• gmail.check.is_new_data_layer()
• gmail.check.is_new_gui()
• gmail.check.is_thread()
• gmail.check.is_inside_email()
• gmail.check.is_plain_text()
• gmail.check.is_preview_pane()
• gmail.check.is_multiple_inbox()
• gmail.check.is_horizontal_split()
• gmail.check.are_shortcuts_enabled()
• gmail.check.is_vertical_split()
• gmail.check.is_tabbed_inbox()
• gmail.check.is_right_side_chat()
• gmail.check.should_compose_fullscreen()
• gmail.check.is_conversation_view()
• gmail.check.is_google_apps_user()
• gmail.check.is_priority_inbox()
• gmail.check.is_rapportive_installed()
• gmail.check.is_streak_installed()
• gmail.check.is_anydo_installed()
• gmail.check.is_boomerang_installed()
• gmail.check.is_xobni_installed()
• gmail.check.is_signal_installed()

CHAT

• gmail.chat.is_hangouts()

COMPOSE

• gmail.compose.start_compose()

OBSERVE

• gmail.observe.http_requests()
• gmail.observe.actions()
• gmail.observe.register(action, class/args, parent) - registers a custom DOM observer
• gmail.observe.off(action,type)
• gmail.observe.on(action, callback)
• XHR observers
• load - When the gmail interface has finished loading
• http_event - When gmail any CRUD operation happens on gmail
• poll - When gmail automatically polls the server to check for new emails every few seconds
• new_email - When a new email appears in the inbox
• open_email - When an email is opened from the inbox view
• refresh - When you click the refresh button
• unread - When a conversation(s) is marked unread
• read - When a conversation(s) is marked read
• delete - When a conversation(s) is deleted
• delete_message_in_thread - When a conversation(s) is deleted inside a thread
• mark_as_spam - When a conversation(s) is marked as spam
• mark_as_not_spam - When a conversation(s) is unchecked as spam
• label - When a conversation(s) get applied a label
• archive - When a conversation(s) is archieved
• move_to_inbox - When a conversation(s) is moved to the inbox
• delete_forever - When a conversation(s) is deleted forever
• star - When a conversation(s) is starred
• unstar - When a conversation(s) is unstarred
• undo_send - When the Undo Send button is clicked after trying to send a new email
• mark_as_important - When a conversation(s) is marked as important
• mark_as_not_important - When a conversation(s) is marked as not important
• filter_messages_like_these - When a filter button is triggered for a conversation
• mute - When a conversation(s) is muted
• unmute - When a conversation(s) is unmuted
• add_to_tasks - When an item is added to google tasks
• move_label - When a conversation(s) is moved to a label folder
• save_draft - When a draft is saved
• discard_draft - When a draft is dicarded
• send_message - When a message is sent (except scheduled messages)
• send_scheduled_message - When a message is scheduled for sending (but not actually sent)
• expand_categories - When a category is expanded from the left nav sidebar
• restore_message_in_thread - When a deleted message is restored inside a thread
• delete_label - When a label is deleted
• show_newly_arrived_message - When inside an email and a new email arrives in the thread
• upload_attachment - When an attachment is being uploaded to an email being composed
• DOM observers
• compose - When a new compose window is opened, or a message is replied to or forwarded
• recipient_change - When an email being written (either new compose, reply or forward) has its to, cc or bcc recipients updated
• view_thread - When a conversation thread is opened to read
• *view_email - When an individual email is loaded within a conversation thread. It's worth noting this event is only triggered when the email is actually rendered in the DOM. Gmail tends to cache the rendered emails, so it should not be expected to fire reliably for every viewing of the same email. It will most likely fire once, for the initial and possibly only rendering.
• load_email_menu - When the dropdown menu next to the reply button is clicked
• gmail.observe.before(action, callback)
• gmail.observe.after(action, callback)
• gmail.observe.bind(type, action, callback) - implements the on, after, before callbacks
• gmail.observe.on_dom(action, callback) - implements the DOM observers - called by gmail.observe.on
• gmail.observe.bound(action, type) - checks if a specific action and/or type has any bound observers
• gmail.observe.trigger(type, events, xhr) - fires any specified events for this type (on, after, before) with specified parameters

DOM

These methods return the DOM data itself

• gmail.dom.inboxes()
• gmail.dom.inbox_content()
• gmail.dom.visible_messages()
• gmail.dom.email_subject()
• gmail.dom.email_body()
• gmail.dom.email_contents()
• gmail.dom.get_left_sidebar_links()
• gmail.dom.header()
• gmail.dom.search_bar()
• gmail.dom.toolbar()
• gmail.dom.right_toolbar()
• gmail.dom.compose() - compose dom object - receives the DOM element for the compose window and provides methods to interact
• gmail.dom.composes() - retrieves an array of gmail.dom.compose objects representing any open compose windows
• gmail.dom.email() - email dom object - receives an email DOM element or email id for an email currently being viewed. Abstracts interaction with that email.
• gmail.dom.thread() - thread dom object - receives a conversation thread DOM element currently being viewed. Abstracts interaction with that thread.

TOOLS

These are some helper functions that the rest of the methods use. See source for input params

• gmail.tools.infobox(message, time)
• Adds the yellow info box on top of gmail with the given message
• gmail.tools.rerender(callback)
• Re-renders the UI using the available data.
• gmail.tools.xhr_watcher()
• gmail.tools.parse_url()
• gmail.tools.deparam()
• gmail.tools.parse_view_data()
• gmail.tools.parse_email_data()
• gmail.tools.extract_email_address(str)
• gmail.tools.extract_name(str)
• gmail.tools.make_request()
• gmail.tools.make_request_async()
• gmail.tools.make_request_download_promise(url, preferBinary) - function specialized for downloading email MIME messages or attachments.
• gmail.tools.sleep(ms)
• gmail.tools.multitry(ms_delay, tries, func, bool_success_check)
• gmail.tools**.i18n(labe