• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

KartikTalwar/gmail.js: Gmail JavaScript API

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称:

KartikTalwar/gmail.js

开源软件地址:

https://github.com/KartikTalwar/gmail.js

开源编程语言:

JavaScript 100.0%

开源软件介绍:

Gmail.js - JavaScript API for Gmail

Node.js CI npm

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.

Methods

Summary (click for more info)

GET

GET (deprecated methods)

CHECK

CHAT

COMPOSE

OBSERVE

It is considered best practice to wait for the gmail interface to be loaded before observing any XHR actions.

gmail.observe.on("load", function(){
    //... now you can safely register other observers using gmail.observe.on
});
  • 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

TRACKER

These are some of the variables that are tracked and kept in memory while the rest of the methods are in use.

  • gmail.version
  • gmail.tracker**.events**
  • gmail.tracker**.xhr_init**
  • gmail.tracker**.xhr_open**
  • gmail.tracker**.xhr_send**
  • gmail.tracker**.watchdog**
  • gmail.tracker**.view_data**
  • gmail.tracker**.email_data**
  • gmail.tracker**.ik**
  • gmail.tracker**.rid**

Details

gmail.new.get.email_id()

Obtains the new-style email-ID from the email currently on screen. Extracted via DOM.

This ID can only be used by gmail.new.get.*-functions.

Can be provided email-element from HTML DOM, or Gmail DOMEmail object to look up specific email ID.

gmail.new.get.thread_id()

Obtains the new-style thread-ID from the email currently on screen. Extracted via DOM.

This ID can only be used by gmail.new.get.*-functions.

gmail.new.get.email_data(identifier)

Returns a data-object for the requested email, if found in the email-cache.

identifier must be an object or string which uniquely identifies an email:

  • new-style email-id
  • legacy-style email-id (will cause warning)
  • DomEmail instance
  • EmailData instance

If no email-data can be found in Gmail.JS email-cache, null or undefined is returned instead.

This method returns immediately, uses no XHR, and has no async-equivalent.

Please note: Email-data is intercepted and stored in the cache only when Gmail itself has requested or used and email.

This typically happens when loading a label (pre-loading all emails in view) or when navigating to view a full thread.

That means that calling the same method later may return data even if the first invocation returned null.

{
  "id": "msg-f:1581064946762017791",
  "legacy_email_id": "15f1123136926bff",
  "thread_id": "thread-f:1581064946762017791",
  "smtp_id": "<[email protected]>",
  "subject": "[PATCH] Flymake support for C/C++",
  "timestamp": 1507821032297,
  "content_html": "Hi,<br>\n<br>\nHere&#39;s a proposal for supporting Flymake in C/C++. This patch...",
  "date": "2017-10-12T15:10:32.297Z",
  "from": {
    "address": "[email protected]",
    "name": ""
  },
  "to": [
    {
      "address": "[email protected]"
    }
  ],
  "cc": [
    {
      "address": "[email protected]"
    },
    {
      "address": "[email protected]"
    }
  ],
  "bcc": [],
  "attachments": [
    {
      "attachment_id": "0.1",
      "name": "0001-Add-a-Flymake-backend-for-C.patch",
      "type": "application/x-patch",
      "url": "https://mail.google.com/mail/?ui=2&ik=94da28fb67&attid=0.1&permmsgid=msg-f:1581064946762017791&th=15f1123136926bff&view=att&zw",
      "size": 11225
    }
  ]
}

gmail.new.get.thread_data(identifier)

Returns a data-object for the requested email-thread, if found in the email-cache.

identifier must be an object or string which uniquely identifies a thread:

  • a new-style thread-id
  • new-style email-id
  • legacy-style email-id (will cause warning)
  • DomEmail instance
  • DomThread instance
  • EmailData instance

If no thread-data can be found in Gmail.JS email-cache, null or undefined is returned instead.

This method returns immediately, uses no XHR, and has no async-equivalent.

Please note: Email-data is intercepted and stored in the cache only when Gmail itself has requested or used and email.

This typically happens when loading a label (pre-loading all emails in view) or when navigating to view a full thread.

That means that calling the same method later may return data even if the first invocation returned null.

{
    "thread_id": "thread-f:1581064946762017791",
    "emails": [...email_data elements...]
}

gmail.get.email_source(identifier=undefined)

Deprecated function. Will be removed. Migrate to gmail.get.email_source_async or gmail.get.email_source_promise instead.

gmail.get.email_source_async(identifier=undefined, callback, error_callback, preferBinary=false)

Retrieves raw MIME message source from the gmail server for the specified email identifier.

identifier must be an object or string which uniquely identifies an email:

  • new-style email-id
  • legacy-style email-id (will cause warning)
  • DomEmail instance
  • EmailData instance

If not specified, current email will be resolved automatically.

By default, once retrieved the resulting data will be passed to callback in text-format. This may corrupt the actual email MIME-data, by causing irreversible content-encoding consistency-errors.

If you need to parse this data in a proper MIME-parser later, the only way to avoid this kind of error is to download the data in binary format and do your own decoding inside your own MIME-parser.

To get the email-source in binary form, you must set the preferBinary-parameter to true.

gmail.get.email_source_promise(identifier=undefined, preferBinary=false)

Does the same as above but implements it using ES6 promises.

gmail.get.user_email()

Returns the current user's email address

gmail.get.manager_email()

Returns the email address of the user currently managing the account (if the inbox is used by the owner, this function returns the same value as gmail.get**.user_email()**)

gmail.get.delegated_to_email()

Returns the email address of the user the account is currently delegated to (if the inbox is used by the owner, this function returns null)

gmail.get.storage_info()

Returns current user's file storage stats

{
  "used": "0 GB",
  "total": "15 GB",
  "percent": 0
}

gmail.get.current_page()

Returns what page of gmail the user is currently on. These are the possible responses

['sent', 'inbox', 'starred', 'drafts', 'imp', 'chats', 'all', 'spam', 'trash', 'circle'] // pages
"email" // inside email conversation
"/search/[.+]" // inside search view
"/label/[.+]" // inside label view
"/category/[.+]" // inside category view
"/settings/[.+]" // settings sub-page (excluding settings root page)

gmail.get.email_subject()

Returns the opened email's subject from the DOM

"test"

gmail.get.compose_ids()

Returns the latest/last email id of emails that have been saved as drafts (currently open)

["14469c73bba6ff53", "14469c7b8581ccfa"]

gmail.get.search_query()

Returns the search bar data

"from:[email protected] is:unread"

gmail.get.unread_emails()

Returns a count of total unread emails for the current account.

{
  "inbox": 2,
  "drafts": 0,
  "spam": 0,
  "forum": 0,
  "notifications": 0,
  "promotions": 0,
  "social": 0
}

You can also request the data individually

  • 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()

Gets user's account activity data

{
  "time": "9:41 pm",
  "ip": "54.234.192.48",
  "mac_address": "2620:101:f000:702:a966:ab42:4a46:195e",
  "time_relative": "31 minutes ago"
}

gmail.get.loggedin_accounts()

Returns a list of signed-in accounts (multiple user accounts setup in gmail)

[{"name":"California","email":"[email protected]"}]

gmail.get.beta()

Although hand picked, this method returns the checks on beta features and deployments

{"new_nav_bar":true}

gmail.get.localization()

Returns the Gmail localization, e.g. 'US'.

gmail.check.is_new_data_layer()

Returns True if the user is running Gmail with the new 2018 data-layer False otherwise

gmail.check.is_new_gui()


鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap