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.

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 archived
  • 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 discarded
  • 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