Turn recurring Gmail inbox organization into a reviewable, deterministic workflow.

Gmail Inbox Triage & Labeler is a local Python utility for freelancers, operators, creators, and small teams who want to organize recurring mail with explicit rules and a deliberate review step before any label changes.

The workflow is intentionally two-stage:

PLAN -> REVIEW -> APPLY

The plan stage reads Gmail and produces a local CSV plan. You review the proposed actions. Only then does the apply stage request the broader Gmail permission and add the approved SOFL labels.

WHAT IT DOES

- Reads Gmail messages through the official Gmail API.

- Uses the Gmail search query you provide.

- Resolves Gmail label IDs to label names so already-triaged SOFL messages are correctly detected.

- Applies deterministic JSON rules for recurring categories such as Finance, Orders, Work, and Marketing.

- Produces a reviewable CSV plan before mailbox mutation.

- Uses rule priorities and a minimum score threshold.

- Sends unmatched or below-threshold messages to REVIEW.

- Creates missing labels inside the protected SOFL/ namespace.

- Re-checks message identity before every label mutation.

- Uses a SHA-256 identity fingerprint based on thread ID, sender, subject, and date.

- Skips already triaged SOFL/ messages under the default policy.

- Adds only missing labels and never duplicates an existing label.

- Writes a JSON apply report with LABELED, STALE, and ERROR results.

SAFETY BOUNDARY

The product only adds labels through Gmail's message-modify endpoint.

It does not:

- delete messages;

- trash messages;

- archive messages;

- send messages;

- mark messages as read;

- change stars;

- remove labels;

- call an external AI service.

WHAT YOU GET

- gmail_triage.py - main Gmail API adapter and CLI

- Windows launcher

- macOS/Linux launcher

- rules.json and rules.example.json

- JSON rules schema guide

- synthetic local demo dataset

- offline unittest suite

- Excel review template

- 12-page user manual

- SECURITY.md

- SOURCES.md

- README

- START HERE guide

- CHANGELOG

- Commercial license

SAFE WORKFLOW

1. Run check-config.

2. Run the local demo without connecting Gmail.

3. Create a small plan with a conservative Gmail query and limit.

4. Review output/triage_plan.csv.

5. Adjust rules if needed and regenerate the plan.

6. Run apply only after review.

7. Inspect output/apply_report.json.

PLAN OUTPUT

The plan CSV includes:

- message ID

- thread ID

- sender

- subject

- date

- identity SHA-256 fingerprint

- snippet

- matched labels

- matched rules

- rule score

- action

- reason

- source query

The identity fingerprint makes formula-safe CSV output reviewable without weakening stale-plan protection.

CUSTOM RULES

Rules are stored in local JSON and can match on:

- subject text

- sender text

- body text

- any of subject/sender/body

- subject regex

- body regex

- attachment presence

A rule is AND across the matcher fields it defines. Multiple rules under a label are OR alternatives.

Empty rules that would match every message are rejected.

REQUIREMENTS

- Python 3.11+

- Google account with Gmail enabled

- Google Cloud project with Gmail API enabled

- Desktop OAuth 2.0 client saved as credentials.json

The package includes the Google API client dependencies in requirements.txt.

Each buyer supplies their own Google Cloud project and OAuth client. No shared credentials or OAuth tokens are included in the package.

OAUTH & GOOGLE VERIFICATION

The product uses two distinct Gmail scopes:

- plan: gmail.readonly for read-only message planning

- apply: gmail.modify because Google requires that scope for users.messages.modify and it is also accepted for label creation

The code only calls messages.modify with addLabelIds during apply.

It does not call Gmail delete, trash, send, archive, star, mark-as-read, or remove-label operations.

Google currently classifies gmail.readonly and gmail.modify as restricted Gmail scopes. A production OAuth application requesting restricted scopes may require Google's verification unless an applicable exception exists.

This package does not ship a shared OAuth client. Each buyer uses their own Google Cloud project and Desktop OAuth credentials.

PRIVACY

The rule engine runs locally.

During plan/apply, Gmail data is exchanged directly between the buyer's computer and Google's Gmail API.

The product does not send mailbox content to an external AI provider.

OAuth tokens remain on the buyer's machine.

IMPORTANT LIMITATIONS

This is a deterministic rules tool, not a general-purpose AI classifier.

It will not understand every free-form email.

Ambiguous messages should remain in REVIEW rather than being silently guessed.

Gmail API behavior, OAuth policies, and Google Cloud console screens can change over time. Consult Google's current documentation during setup.

LICENSE

Commercial use is allowed for the purchaser's own business and client projects.

The included source files may be modified for internal workflows.

Resale, sublicensing, redistribution, or repackaging of the original source files as a competing product is prohibited.

REFUNDS

Please review the requirements, OAuth setup, supported workflow, and limitations before purchase.

Getly's current platform refund policy applies to the listing.