A local AI mailroom

Promotional folders are digital landfills. We sign up once and receive daily “last chance” offers that bury important context. Traditional filters are too blunt; they can’t distinguish between a shipping notification and a coupon.

I built a suite of Python tools to act as a personal mailroom. It uses local AI to understand, organize, and prune Gmail.

How it works

The system acts as a bridge between your inbox and local inference engines. Metadata is synced to a local database before any analysis occurs to keep the API footprint small.

The Cleanup Workflow

graph TD
    A[Gmail Inbox] -->|Sync Metadata| B[(SQLite DB)]
    B -->|Pending Analysis| C{Local AI Engine}
    C -->|Apple FM SDK| D[Apple Intelligence]
    C -->|Ollama API| E[DeepSeek-R1]
    D -->|Decision: KEEP/DELETE| F[(SQLite DB)]
    E -->|Decision: KEEP/DELETE| F
    F -->|Trash Mode| G[Gmail API: Batch Modify]
    G -->|Move to Trash| H[Gmail Trash]

Local-first strategy

Privacy is the priority when dealing with personal email. The system uses a local-first fallback chain:

1. Apple Intelligence: Uses the apple_fm_sdk to hook into on-device Foundation Models ¹. It is fast, private, and requires no API keys.
2. DeepSeek-R1: A fallback running through Ollama ². It handles complex reasoning without sending data to a cloud provider.

The AI decision engine is simple. It reads the subject and snippet, then outputs a single word: KEEP or DELETE.

Smart organization

Manually creating Gmail filters is tedious. The system includes a discovery module that analyzes top senders and identifies patterns.

graph TD
    A[SQLite DB: Sender Stats] -->|Top 20 Senders| B{Apple Intelligence}
    B -->|Analyze Patterns| C[Proposed Rule Hierarchy]
    C -->|User Approval| D[Gmail API: Create Labels]
    D -->|Create Filters| E[Gmail API: Settings/Filters]
    E -->|Backfill| F[Label Existing Mail]

Instead of flat filters, it proposes a hierarchy (e.g., Cleanup/Retail/Clothing). Once approved, the script creates the labels and filters via the Gmail API ³ and backfills existing messages.

Accessing Gmail

To interact with Gmail, the tool uses the Google API Client Library for Python. It follows the OAuth 2.0 flow for installed applications, requesting a specific set of scopes: gmail.modify, gmail.settings.basic, and gmail.labels.

On the first run, it opens a local server for browser-based authentication. The resulting credentials are saved as token.json and automatically refreshed when they expire. To minimize API latency and respect rate limits, all operations—like trashing or labeling thousands of emails—are performed using batch requests, grouping up to 1,000 operations into a single call.

Unsubscribe auditing

The system scans for List-Unsubscribe headers and attempts to automate the process.

It also logs every unsubscription in a local SQLite database. A week later, a compliance audit checks if those senders have reappeared. If they have, it flags them as a violation. It turns the “unsubscribe” button from a suggestion into a tracked requirement.

Value

The cost of implementing software requirements has dropped. This project shows that unmaintained internal processes—like managing an inbox—can now be fixed by a single person with an AI agent.

We are moving away from monolithic cloud services that read our data to sell ads, toward local agents that read our data to save us time.