GmailAssist

A small Chrome extension that groups your unread Gmail by sender domain, so you can see at a glance who is actually filling your inbox.

Click any domain and your Gmail tab jumps to from:<domain> — from there you can mark all as read, delete, or set up a filter in the usual Gmail way.

Why

Inbox triage is mostly a handful of noisy senders. Scrolling 700 unread emails hides that; a ranked list of domains makes it obvious, and the click-through removes the copy-paste-search step.

Features

• Counts all unread mail and ranks the top 30 sender domains
• One click opens that domain's unread mail in your existing Gmail tab
• Results are cached, so reopening the popup is instant
• Refresh button to force a recount, with a "last updated" timestamp
• Read-only: requests only gmail.readonly and never modifies your mail

Install

The extension is not on the Chrome Web Store, so it runs unpacked. You need your own Google OAuth client — the one committed here is bound to this project's extension ID and will not work for you.

1. Load the extension

git clone https://github.com/orralus/GmailAssist.git

Open chrome://extensions, enable Developer mode, click Load unpacked, and select the app/ folder. Copy the extension ID that appears on the card.

2. Create an OAuth client

In the Google Cloud Console:

• Create a project and enable the Gmail API
• Under APIs & Services → OAuth consent screen, add the https://www.googleapis.com/auth/gmail.readonly scope and add your own Google account as a test user
• Under Credentials, create an OAuth client ID of type Chrome Extension, using the extension ID from step 1

3. Wire it up

Put the new client ID in app/manifest.json:

"oauth2": {
  "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
  "scopes": ["https://www.googleapis.com/auth/gmail.readonly"]
}

Reload the extension in chrome://extensions and open the popup. Chrome will prompt you to grant access on first run.

Troubleshooting

bad client id — the OAuth client does not match this installation. Loading an unpacked extension on a new machine assigns a new extension ID, so the client ID in the manifest no longer matches. Add the new extension ID to your OAuth client in the Cloud Console, or create a new client for it.

Too many concurrent requests for user — Gmail is rate limiting. Requests are batched 20 at a time, so this should be rare; if it recurs, lower batchSize in app/background.js.

Nothing happens / empty list — open the popup, right-click, Inspect, and check the console. Errors are also shown in red in the popup itself.

Privacy

Everything runs locally in your browser. The extension talks only to the Gmail API, and there is no server, analytics, or third-party endpoint. It requests only sender addresses (format=metadata&metadataHeaders=From), never message bodies. Cached domain counts live in chrome.storage.local and are cleared when you uninstall.

How it works

• app/background.js — service worker: OAuth via chrome.identity, pages through unread message IDs, fetches the From header for each in batches of 20, and aggregates by domain
• app/popup.js / app/popup.html — the popup UI, caching, and Gmail click-through

License

MIT