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.

Rules: - Translate the DESCRIPTIVE words of the title. Leave a token in English only when it is an actual trademark or invented brand, a published work's title, or a technical format such as PDF or SVG. - A title made of ordinary words describing the item ("Summer prints", "Instant Download") is NOT a brand - translate it. - Do not return NAME unchanged unless every one of its tokens is one of the above. - Preserve all HTML tags and structure in the description - Keep technical terms in their commonly used form in the target language - Maintain the same tone and style