gmail-auto-label (Rust)

An automatic Gmail labeling tool built with gog + codex (Rust version).
This is the primary documentation.

🌐 Languages: 🇺🇸 English · 🇨🇳 简体中文

Features

• Auto-scan inbox threads and classify emails into business-friendly labels
• Optional custom label rules with higher priority than memoized, learned, and Codex-generated matches
• Cache-first classification (memo + reusable rules) to reduce repeated LLM calls
• Codex fallback for uncached emails, then persist extracted rules for later reuse
• Auto-create missing Gmail labels and apply labels in batches
• Optional archive step (remove INBOX) after labeling, with --keep-inbox support
• Label compression when active labels exceed the limit (public control is --max-labels, merge target defaults to others)
• Gmail rate-limit handling with automatic retry/backoff in single-pass mode, and no in-round retries in watch mode
• Dry-run mode for safe preview without write operations

Prerequisites

• gog is installed and authenticated
• codex CLI is installed (default command: codex exec)
• Rust toolchain is installed

gog Setup

1. Install gog for your operating system.
2. Sign in:

gog auth login

3. Verify Gmail access:

gog gmail labels list --no-input --json

4. List local accounts (to confirm account names):

gog auth list

5. For multiple accounts, pass account name when running this tool:

gmail-auto-label --account your-account-name

Note: all Gmail operations are executed through gog. If auth or permissions are missing, the tool will fail at runtime.

gog Troubleshooting

1. Check current auth/session status:

gog auth status

2. Quick Gmail API read test:

gog gmail search "in:inbox" --max 1 --no-input --json

3. Re-login if token/permission is invalid:

gog auth login

Build

cargo build --release

Binary:

./target/release/gmail-auto-label

Install from crates.io

Install with:

cargo install gmail-auto-label

Optional (pin a version):

cargo install gmail-auto-label --version 0.1.3

After installation, run the binary directly:

gmail-auto-label --help

Common Usage

1. Single pass (default: 10 threads):

gmail-auto-label --limit 10

2. Dry run (no write operations):

gmail-auto-label --dry-run --limit 10

3. Watch mode (base interval: every 5 minutes):

gmail-auto-label --watch 300

Watch mode uses adaptive idle backoff: when rounds stay idle, the next sleep interval grows up to 8x the base interval; once a round processes emails, it resets to the base interval.
In watch mode, Gmail API calls do not retry within the same round; failed calls are retried in the next round.

4. Keep messages in inbox (label only, no archive):

gmail-auto-label --keep-inbox

5. Use custom label rules:

gmail-auto-label --custom-labels-file ./custom-labels.json

Key Options

• --limit: max threads per run, default 10
• --watch: base polling interval in seconds (adaptive idle backoff may extend actual sleep), for example --watch 300
• --account: gog account name
• --dry-run: print actions only, no writes
• --custom-labels-file: load custom label rules from a JSON file
• --max-labels: max active labels, default 10
• --keep-inbox: do not remove processed threads from inbox

Advanced Options

These flags remain supported for compatibility, but are hidden by default:

• --codex-cmd
• --cache-file
• --merged-label
• Legacy compatibility: --loop + --interval still work, but --watch is the preferred form

Built-in feedback file format (internal path is fixed to /tmp/gmail_auto_label_feedback.json):

[
  {
    "event_id": "evt-20260318-001",
    "rule_id": "rule_sha256_id",
    "verdict": "bad",
    "ts": 1773800000
  }
]

Notes:

• event_id must be unique; duplicated/replayed events are skipped.
• ts uses Unix seconds; stale events older than the built-in feedback retention window are skipped.

Custom Label Rules

Use --custom-labels-file <path> to load user-defined label rules before a run starts. Matching order is:

1. Custom label rules
2. Memoized matches
3. Learned rules
4. Codex fallback

Rules are evaluated in file order, first match wins. Custom labels are not auto-pruned by feedback and are not merged into the learned-label compression target.

Example file:

[
  {
    "label": "Important Client",
    "include_keywords": ["vip", "invoice"],
    "exclude_keywords": ["spam"]
  }
]

Validation rules:

• File must be readable JSON
• Top-level value must be an array
• Each rule must include a non-empty label
• Each rule must include at least one non-empty include_keywords value

Help

gmail-auto-label --help