InboxGuard

AI-powered Chrome Extension that cleans, categorizes, and declutters your Gmail inbox.

Features · Quick Start · Architecture · Privacy · Troubleshooting

---

Why InboxGuard?

The average professional receives 120+ emails per day. Half are newsletters you forgot you signed up for. A quarter are notifications you never read. InboxGuard fixes this in three clicks:

1. Scan your inbox for subscription bloat
2. Unsubscribe from unwanted senders (one-click, RFC 8058)
3. Categorize remaining emails with AI-generated Gmail labels

No server. No subscription. No data leaves your browser unless you opt into AI classification. Completely free.

---

Features

Auto-Unsubscribe

• Detects emails with List-Unsubscribe headers (RFC 2369)
• Ranks senders by frequency and spam score
• One-click unsubscribe (RFC 8058) for instant removal
• Falls back to opening unsubscribe URLs or mailto links
• Batch unsubscribe from multiple senders at once

AI-Powered Categorization

• Classifies emails into 9 smart categories using AI: Important · Work · Personal · Finance · Shopping · Social · Newsletters · Notifications · Likely Spam
• Automatically creates Gmail labels under InboxGuard/ with color coding
• Scheduled auto-categorization at configurable intervals
• Three AI provider options (all free):

Provider	Model	Free Tier	Best For
Google Gemini	Gemini 2.0 Flash	15 req/min, 1M tokens/min	Recommended default
Groq	Llama 3.3 70B	30 req/min, 131K tokens/day	Fast fallback
Smart Rules	Built-in patterns	Unlimited, works offline	Zero-config start

Bulk Cleanup

• Delete, archive, or trash emails older than a configurable threshold (7 days to 1 year)
• Safe mode: only processes read emails by default
• One-click execution from the dashboard or the Gmail floating button

Dashboard & Analytics

• Real-time inbox statistics: total, unread, spam, trash
• Lifetime counters for emails unsubscribed and cleaned
• Last scan results with top sender breakdown and spam scores

Gmail Integration

• Floating action button (FAB) inside Gmail for quick scan, categorize, or cleanup
• Visual badges on email rows for detected subscription senders
• In-page notifications for action confirmations without leaving Gmail

---

Quick Start

Prerequisites

• Google Chrome (or any Chromium-based browser)
• A Google account with Gmail

1. Create OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project (e.g., "InboxGuard")
3. Navigate to APIs & Services > Library and enable Gmail API
4. Go to APIs & Services > Credentials
5. Click Create Credentials > OAuth 2.0 Client ID
6. Select Chrome Extension as the application type
7. You'll need your extension ID from step 2 below — come back to enter it

2. Load the Extension

1. Clone this repository:

   git clone https://github.com/ghwmelite-dotcom/Inbox-Guard.git
   cd Inbox-Guard

2. Open inbox-guard/manifest.json and replace YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com with your OAuth Client ID from step 1

3. Open Chrome and navigate to chrome://extensions/

4. Enable Developer mode (top-right toggle)

5. Click Load unpacked and select the inbox-guard/ directory

6. Copy the extension ID shown on the card and paste it back into your OAuth credential in Google Cloud Console

3. Connect & Configure

1. Click the InboxGuard icon in your Chrome toolbar
2. Click Connect Gmail Account and authorize access
3. Open Settings (gear icon) and choose your AI provider:
   • Google Gemini Flash (recommended) — get a free key at aistudio.google.com/apikey
   • Groq Llama 3.3 — get a free key at console.groq.com/keys
   • Smart Rules — no key needed, works immediately
4. Configure scan depth and auto-categorization preferences
5. Click Save Settings

You're ready. Click Scan Inbox to find your first batch of subscriptions.

---

Architecture

inbox-guard/
├── manifest.json              # Chrome Extension Manifest V3
├── background/
│   └── service-worker.js      # Core engine: auth, scanning, AI classification,
│                               # unsubscribe, cleanup, label management, scheduling
├── content/
│   ├── gmail-inject.js        # Gmail DOM injection (FAB, badges, notifications)
│   └── gmail-inject.css       # Injection styles (dark theme, animations)
├── popup/
│   ├── popup.html             # Dashboard UI (4 tabs: Overview, Unsubscribe,
│   │                          #   Categorize, Cleanup)
│   ├── popup.css              # Dark editorial theme with emerald accent
│   └── popup.js               # Dashboard logic & service worker communication
├── utils/
│   ├── gmail-api.js           # Gmail REST API wrapper (OAuth2, messages, labels,
│   │                          #   unsubscribe detection via RFC 2369/8058)
│   └── ai-engine.js           # Multi-provider AI classifier with fallback chain
│                               #   (Gemini → Groq → Rule-based)
└── icons/                     # Extension icons (16, 48, 128px)

Tech Stack

Layer	Technology
Platform	Chrome Extension (Manifest V3)
Language	Vanilla JavaScript (no build step)
Gmail API	OAuth2 via chrome.identity, REST v1
AI	Gemini 2.0 Flash / Groq Llama 3.3 70B / Rule-based
Storage	Chrome Storage API (local)
UI	HTML/CSS with dark theme, DM Sans + JetBrains Mono

Communication Flow

┌──────────┐   chrome.runtime    ┌─────────────────┐   Gmail REST API   ┌──────────┐
│  Popup   │◄──── sendMessage ──►│  Service Worker  │◄─── fetch() ─────►│  Gmail   │
│  (UI)    │                     │  (Background)    │                    │  API v1  │
└──────────┘                     │                  │   AI REST API      └──────────┘
                                 │  importScripts() │◄─── fetch() ─────►┌──────────┐
┌──────────┐   chrome.runtime    │  ┌────────────┐  │                   │ Gemini / │
│ Content  │◄──── sendMessage ──►│  │ gmail-api  │  │                   │  Groq    │
│ Script   │                     │  │ ai-engine  │  │                   └──────────┘
│ (Gmail)  │                     │  └────────────┘  │
└──────────┘                     └─────────────────┘

---

Privacy & Security

InboxGuard is designed with a local-first, zero-trust approach:

Concern	How It's Handled
Data storage	All settings, stats, and history stay in chrome.storage.local — never transmitted
Gmail access	API calls go directly from your browser to Google's servers. No proxy. No middleman.
AI classification	Only email metadata is sent (sender, subject, snippet). Never email body content.
Offline mode	Smart Rules mode processes everything locally — zero data leaves your browser
Tracking	No analytics, no telemetry, no cookies, no fingerprinting
Disconnection	Revoke access and clear all data at any time from Settings

---

Customization

Custom Categories

Edit the DEFAULT_CATEGORIES array in utils/ai-engine.js:

{
  id: 'your_category',
  label: '🏷️ Your Label',
  color: { bg: '#hex', text: '#hex' },
  description: 'Guidance for the AI classifier'
}

Scan Depth

Adjust in Settings > Scan Depth. Options: 50, 100, 200, or 500 emails. Higher values find more subscriptions but take longer.

Auto-Categorization Schedule

Enable in Settings > Auto Categorization with intervals of 15 min, 30 min, 1 hour, or 2 hours.

---

Troubleshooting

Issue	Solution
"Authentication failed"	Re-check your OAuth Client ID in manifest.json. Make sure the extension ID matches your Google Cloud credential.
"No AI API key configured"	Add a free Gemini or Groq key in Settings, or switch to Smart Rules mode.
Gemini returns errors	Verify your key at aistudio.google.com. Free tier allows 15 req/min.
Groq returns errors	Verify your key at console.groq.com. Free tier has a 131K tokens/day limit.
Extension won't load	Ensure manifest.json is valid JSON. Open chrome://extensions/, click Errors on the InboxGuard card.
Gmail FAB not showing	Hard-refresh the Gmail tab (Ctrl+Shift+R). Check that content script permissions include https://mail.google.com/*.
Labels not created	Ensure your OAuth scopes include gmail.labels and gmail.modify. Re-authorize if needed.
Actions feel slow	Increase Chrome's service worker timeout or reduce scan depth in Settings.

---

Contributing

This is a personal project. If you'd like to suggest improvements, open an issue.

---

License

All rights reserved.

---

_{Built by ghwmelite-dotcom}