Gmail Regex Rules Manager Development by Michael GuberGmail Regex Rules Manager Development by Michael Guber

Gmail Regex Rules Manager Development

Michael Guber

Completed work

Email Automation

AI Automation

Gmail

JavaScript

N8N

Electronics

Gmail Regex Rules Manager

A powerful Chrome extension that automatically manages your Gmail emails using regex-based rules. Set up custom patterns to automatically label, archive, mark as read, and perform other actions on incoming emails.

Features

✨ Regex Pattern Matching

Match emails by sender (From)

Match emails by recipient (To)

Match emails by subject

Match emails by body/snippet

Live Regex Helper - Test patterns in real-time as you type

🎯 Automated Actions

Add or remove labels

Mark as read/unread

Mark as important

Star emails

Archive emails

Move to trash

⚡ Real-Time Monitoring

Automatically detects new emails in Gmail

Processes emails as they arrive

Configurable scan interval (1-60 minutes)

Works in the background with retry logic

🎨 User-Friendly Interface

Easy rule creation and management

Drag & drop rule reordering to set priority

Test rules before applying

Enable/disable rules individually

Per-rule match statistics (count & last matched)

Visual feedback and status

📊 Performance & Observability

Stats tab with processing metrics

Configurable retention (5-500 entries)

Adjustable log levels (error/warn/info/debug)

Import/export rules for backup/sharing

Installation

📋 Important: This extension requires your own Google OAuth credentials to access Gmail. Follow the setup guide below.

Quick Setup

Get OAuth Credentials - Follow our detailed OAuth setup guide

Configure the extension - Use the helper script or edit manually

Load in Chrome - Install as an unpacked extension

Method 1: Using the Helper Script (Recommended)

# Install dependencies
npm install

# Configure your OAuth Client ID
npm run config YOUR_CLIENT_ID.apps.googleusercontent.com

Method 2: Manual Configuration

Download or clone this repository

Open manifest.json in a text editor

Find the oauth2 section at the bottom

Replace YOUR_CLIENT_ID.apps.googleusercontent.com with your actual Client ID

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

Load Extension in Chrome

Open Chrome and go to chrome://extensions/

Enable Developer mode (toggle in top right)

Click Load unpacked

Select the extension folder

Click the extension icon and Sign In to authenticate

Need Help?

📖 Complete OAuth Setup Guide - Step-by-step instructions with troubleshooting

🚀 Quick Start Guide - Get started in 5 minutes

❓ Check the Troubleshooting Guide for common issues

Old Installation Section (For Reference)

Click to expand detailed manual setup

Step 1: Set up Google Cloud Project

Go to Google Cloud Console

Create a new project or select an existing one

Enable the Gmail API:

Navigate to "APIs & Services" > "Library"

Search for "Gmail API"

Click "Enable"

Create OAuth 2.0 credentials:

Go to "APIs & Services" > "Credentials"

Click "Create Credentials" > "OAuth client ID"

Select "Chrome Extension" as application type

Copy your Chrome Extension ID (you'll get this after loading the extension)

Add authorized redirect URIs:

https://<extension-id>.chromiumapp.org/

Click "Create"

Copy the Client ID

Step 2: Configure the Extension

Download or clone this repository

Open manifest.json

Replace YOUR_CLIENT_ID.apps.googleusercontent.com with your actual Client ID from Step 1

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

Step 3: Load the Extension

Open Chrome and navigate to chrome://extensions/

Enable "Developer mode" (toggle in top-right corner)

Click "Load unpacked"

Select the gmail-regex-manager folder

Note the Extension ID shown on the extension card

Go back to Google Cloud Console and update your OAuth credentials with this Extension ID

Step 4: Authenticate

Click the extension icon in Chrome

Click "Sign In" button

Authorize the extension to access your Gmail

You're ready to create rules!

Usage

Creating a Rule

Click the extension icon

Go to the "Create Rule" tab

Give your rule a name (e.g., "Newsletter Filter")

Set up patterns:

From Pattern: Regex to match sender email

Subject Pattern: Regex to match subject line

Body Pattern: Regex to match email content

Live Regex Helper: Type sample values below each pattern to see live matches

Choose actions:

Add labels (comma-separated)

Mark as read

Live Regex Helper

The Create Rule tab includes a live testing panel:

Enter sample From, To, Subject, and Body values

As you type patterns, see instant feedback

✔ Green = pattern matches sample

✖ Red = pattern doesn't match

Yellow = regex syntax error

Empty pattern fields show as gray "—"

This helps you validate patterns before saving the rule.

Rule Priority & Ordering

Rules are evaluated in the order shown on the Rules tab. Drag and drop rules using the ☰ handle to reorder them. Higher priority rules run first. Reordering is saved automatically.

Per-Rule Statistics

Each rule card displays:

Matches: Total number of times the rule has matched

Last: Timestamp of the most recent match

Statistics help you understand which rules are actively processing emails.

Example Rules

Filter Newsletters

Name: Newsletter Filter
From Pattern: .*@newsletter\.com|.*@marketing\..*
Actions: Add Label "Newsletters", Mark as Read, Archive

Urgent Emails

Name: Urgent Marker
Subject Pattern: ^\[URGENT\].*|^URGENT:.*
Actions: Add Label "Urgent", Mark as Important, Star

Invoice Tracker

Name: Invoice Detector
Subject Pattern: .*(invoice|receipt|payment).*
Body Pattern: .*(invoice|payment|bill).*
Actions: Add Label "Finance/Invoices"

GitHub Notifications

Name: GitHub Filter
From Pattern: notifications@github\.com
Subject Pattern: ^\[.*\].*
Actions: Add Label "GitHub", Archive

Regex Tips

. - matches any character

.* - matches any characters (zero or more)

^ - start of string

$ - end of string

| - OR operator

\ - escape special characters

[abc] - matches a, b, or c

[a-z] - matches any lowercase letter

\d - matches any digit

\w - matches word characters

Case Insensitive: All patterns are automatically case-insensitive.

Testing Rules

Go to the "Test" tab

Enter sample email data (from, to, subject, body)

Click "Test Against All Rules"

See which rules would match your test email

Settings

The top of the popup includes configuration options:

Auto-process emails: Toggle to enable/disable automatic processing

Log Level: Choose verbosity (error, warn, info, debug)

Processing Interval: Set scan frequency in minutes (minimum 1 minute due to Chrome alarm API limits)

Lower values = more responsive but higher CPU/network usage

Default: 1 minute

Perf Retention: Maximum number of performance entries to store (5-500)

Default: 50 entries

Interval changes take effect immediately and reschedule the background alarm.

How It Works

Content Script: Monitors Gmail webpage for new emails using DOM observation

Background Service Worker: Processes emails and applies rules via Gmail API with exponential backoff retry logic

Storage: Rules and settings are stored locally using Chrome's storage API

Gmail API: Applies actions (labels, read status, etc.) to matched emails with automatic label creation

Performance Tracking: Records metrics for each processing run (configurable retention)

Logging: Structured logging with adjustable verbosity levels

Permissions

The extension requires the following permissions:

storage - Store rules and settings locally

identity - Authenticate with Google

alarms - Periodic email checking

Gmail API scopes:

gmail.modify - Modify emails (labels, read status, etc.)

gmail.labels - Manage labels

Troubleshooting

Extension not processing emails

Make sure the extension is authenticated (click "Sign In")

Check that auto-process is enabled in the extension popup

Verify that Gmail is open in at least one tab

Rules not matching

Use the "Test" tab to verify your regex patterns

Check that patterns are properly escaped

Remember patterns are case-insensitive

Authentication fails

Verify Client ID is correctly configured in manifest.json

Make sure Gmail API is enabled in Google Cloud Console

Check that OAuth consent screen is properly configured

Labels not appearing

Labels are created automatically if they don't exist

Refresh Gmail to see newly created labels

Check browser console for any errors

File Structure

gmail-regex-manager/
├── manifest.json          # Extension configuration
├── background.js          # Service worker (email processing logic)
├── content.js            # Gmail page monitor
├── popup.html            # Extension popup UI
├── popup.css             # Popup styles
├── popup.js              # Popup logic (includes drag & drop, stats, regex helper)
├── gmailActions.js       # Gmail API action helpers with retry logic
├── perf.js               # Performance tracking utilities
├── logger.js             # Structured logging utility
├── rules.js              # Rule matching logic (testable)
├── icons/                # Extension icons
│   ├── icon16.png
│   ├── icon48.png
│   └── icon128.png
├── tests/unit/           # Jest unit tests
│   ├── perf.test.js
│   └── gmailActions.test.js
├── scripts/              # Build and automation scripts
│   ├── test-rules.js     # Offline rule testing harness
│   └── release.js        # Version bump & release helper
├── examples/             # Sample data for testing
│   ├── rules-sample.json
│   └── emails-sample.json
├── .github/workflows/    # CI/CD workflows
│   ├── validate.yml      # Extension validation
│   ├── ci.yml            # Test & lint
│   └── package.yml       # Package & release
└── README.md             # This file

Privacy & Security

All rules are stored locally on your device

No data is sent to external servers (except Google APIs)

Extension only accesses Gmail when authenticated

You can revoke access anytime in your Google Account settings

Development

Local Testing

Make changes to the code

Go to chrome://extensions/

Click the refresh icon on the extension card

Test your changes

Debugging

Offline Rule Testing

Automated Tests

Jest tests live under tests/unit/. Run (after installing dev dependencies locally):

npm install
npm test

Tests cover:

Performance entry creation and storage

Gmail API retry logic with exponential backoff

Label creation and retrieval

Rule matching logic

CI runs tests automatically on push/PR via .github/workflows/ci.yml.

Import / Export Rules

Use the popup's Import/Export tab:

Export: Downloads rules-export.json (current rules)

Import: Select a JSON array of rules, they are validated and appended

Rule object shape:

{
  "id": "rule_id",
  "name": "Readable name",
  "enabled": true,
  "fromPattern": "regex",
  "toPattern": "regex",
  "subjectPattern": "regex",
  "bodyPattern": "regex",
  "actions": {
    "addLabels": ["Label"],
    "removeLabels": ["Label"],
    "markAsRead": true,
    "markAsImportant": false,
    "star": false,
    "archive": false,
    "trash": false
  }
}

Performance Metrics & Stats Tab

Processing performance entries are stored in chrome.storage.local under perfStats (configurable retention: 5-500 entries, default 50). Each entry:

{
  "timestamp": 1730956800000,
  "emails": 10,
  "rules": 12,
  "matchChecks": 120,
  "ruleMatches": 4,
  "processedCount": 4,
  "durationMs": 37.5
}

You can inspect via the DevTools console in the service worker:

chrome.storage.local.get(['perfStats'], x => console.log(x.perfStats));

Stats Tab

Open the Stats tab in the popup to view a table of recent runs with:

Time of run

Emails scanned

Rules count

Match checks performed

Rule matches

Emails processed (actions applied)

Duration (ms)

Buttons:

Refresh: Reload data

Clear: Remove all stored performance entries

Summary line shows entry count, average duration, and total processed across runs.

Release Script

Use the release helper to bump version, update manifest.json, update package.json, append a CHANGELOG entry, commit, and tag:

npm run release -- patch "Improve stats UI and dedupe imports"
git push && git push --tags

Levels: major | minor | patch.


### Packaging Workflow

GitHub Actions workflow `package.yml` zips the extension when you push a tag (e.g., `v1.1.0`) or run manually. Artifact name: `gmail-regex-rules-manager.zip`.

Manual trigger: GitHub UI → Actions → Package Extension → Run workflow.

Tag trigger example:
```powershell
git tag -a v1.1.0 -m "v1.1.0"
git push origin v1.1.0

You can evaluate rules against sample emails outside Chrome using the Node test harness.

Sample data lives in examples/:

examples/rules-sample.json

examples/emails-sample.json

Run harness (JSON output):

node scripts/test-rules.js --rules examples/rules-sample.json --emails examples/emails-sample.json

Compact summary:

node scripts/test-rules.js --rules examples/rules-sample.json --emails examples/emails-sample.json --compact

Single inline email:

node scripts/test-rules.js --rules examples/rules-sample.json --email '{"from":"billing@vendor.com","subject":"Payment Receipt"}' --compact

Version bump helper:

npm run bump -- 1.1.0

Add --tag to auto commit & tag:

npm run bump -- 1.1.0 --tag
git push && git push --tags

Background script: chrome://extensions/ > Click "service worker"

Content script: Open Gmail, press F12, check Console

Popup: Right-click extension icon > "Inspect popup"

Limitations

Rules process emails visible in Gmail's current view

Body matching only works on email snippets (not full content)

Maximum 100 rules recommended for performance

Requires Gmail to be open in at least one browser tab

Future Enhancements

Import/export rules

Rule execution statistics (Stats tab)

Rule priority/ordering (drag & drop)

Live regex helper

Configurable processing interval

Retry logic with exponential backoff

Per-rule match statistics

Structured logging

Advanced regex builder UI

Email templates for responses

Scheduled rule execution (time-based)

Full email body search via API

Rule groups/folders

Conditional actions (if/then logic)

License

MIT License - Feel free to modify and distribute

Support

For issues, questions, or contributions, please visit the GitHub repository.

Note: This extension requires proper Google Cloud OAuth setup. Make sure to follow the installation instructions carefully.

Like this project

Completed work

Posted Feb 4, 2026

Developed a Chrome extension for Gmail email management using regex rules. Managed Regex Pattern Matching, Automated Actions, Real-Time Monitoring features.

Likes

Views