gmail-labeler

# Gmail Labeler A production-oriented Gmail labeling workflow built around: - `gog` for Gmail access - a local overlay for private rules/accounts/routes - a hybrid review flow: heuristics first, lightweight LLM review for ambiguity-band messages - a 15-minute cron-friendly runner ## What it does - Classifies inbox items into **non-actionable** vs **actionable** buckets - Applies Gmail labels and archives non-actionable mail - Keeps replies, opportunities, urgent billing items, and other actionable mail in Inbox - Supports **English, Portuguese, and Spanish** keyword coverage out of the box - Logs every decision to JSONL for auditability and tuning - Purges logs older than 30 days - Supports a daily self-improvement review loop based on prior decisions and user corrections ## Default categories ### Non-actionable - Newsletters - Promotions - Notifications - Ordinary receipts ### Actionable - Billing issues - Replies - Opportunities - Action Required ## What stays local/private Keep user-specific editorial, business, or inbox-policy rules in the local overlay, not in the shared skill defaults. Examples of local-only rules: - PR / press release handling - press trip or media invitation routing - VIP sender policies - business-specific labels - custom notification routes ## Operating model ### 1. Sender-type-first routing Classify sender as: - `person` - `company` - `person_or_unknown` This keeps bulk automated mail cheap to classify and reserves deeper review for ambiguous or human-origin messages. ### 2. Inbox-by-exception policy Treat Inbox as an **action queue**, not a reading queue. Recommended default: - processed mail always gets `Auto/Triaged` - mail stays in Inbox only when it is clearly actionable / important - everything else should leave Inbox, even when the category is still somewhat generic Practical effect: - **important/actionable** mail → keep in Inbox and add category labels when possible - **non-important** mail → remove `INBOX`, keep `Auto/Triaged`, then add a best-fit category label (`Notification`, `Newsletter`, `Receipt`, `Press Releases`, etc.) ### 3. Confidence-band review Use heuristics first. Then send only ambiguity-band messages to a lightweight LLM review. Recommended pattern: - high confidence → trust heuristics - medium confidence → LLM review - low confidence → conservative fallback ### 4. Conservative-but-useful fallback If a message is clearly automated/company-origin but no specific filter matches, prefer a generic non-actionable classification (for example `Notification`) over leaving it untouched in Inbox. ### 5. Label normalization Use a small canonical label set and avoid near-duplicates caused by translation, singular/plural, or typos. Example normalization targets: - `Press Release` → `Press Releases` - finance label variants → one canonical finance label - keep `Auto/Triaged` as the universal processed marker ## Gmail-native labels to prefer Use Gmail system labels when possible: - `CATEGORY_PROMOTIONS` - `CATEGORY_UPDATES` - `IMPORTANT` - `STARRED` - `INBOX` Create custom labels only when needed, for example: - `Newsletter` - `Notification` - `Receipt` - `Opportunity` - `Action Required` - `Auto/Triaged` ## Local overlay design Keep the skill publishable by storing private configuration outside the skill directory. Recommended local overlay path: ```text ~/.openclaw/local/gmail-labeler.config.json ``` Store private values only in the local overlay: - email accounts - VIP senders/domains - notification targets - business-specific opportunity rules - personal/custom labels ## Logging and review Decision logs should live outside the skill source tree, for example: ```text /home/ubuntu/.openclaw/gmail-labeler-logs/ ``` Recommended format: - one JSONL file per day - one row per decision - separate error rows Suggested daily review inputs: - yesterday's decision log - false positives / false negatives - over-aggressive archiving - missed billing urgency - missed opportunities - user-requested corrections ## Files to read - `references/default-config.json` - `references/config-guide.md` - `references/filter-catalog.md` - `references/implementation-notes.md` - `references/logging-and-review.md` - `references/llm-review.md` - `references/cron-example.md` - `references/ain-email-review.schema.json` ## Runners - Main runner: `scripts/gmail_labeler_runner.py` - Launcher example: `scripts/gmail_labeler_run.sh` ## Publishing guidance Before publishing: - keep only generic defaults in the skill - remove personal accounts, chat ids, private domains, and custom user rules - keep examples generic - document clearly that private configuration belongs in the local overlay - keep PR / press-release handling user-specific when it reflects private editorial policy; do not publish those local heuristics by default - validate cron/non-interactive execution via the launcher, not only via direct Python invocation