Automate Gmail Labeling with Paradime, OpenClaw, and the Gmail API

Inbox zero isn't a dream—it's a scheduled job. If you've ever spent fifteen minutes every morning dragging emails into folders, you already know the problem. Manual triage doesn't scale. What you need is an intelligent, repeatable workflow that reads new messages, classifies them by content and sender, applies the right Gmail labels, and runs on autopilot every thirty minutes.

This tutorial walks you through building exactly that. You'll wire together Paradime's Bolt scheduler, the OpenClaw AI agent, and the Gmail API into a single Python script that measures your inbox state, identifies unlabeled emails, fixes them with AI-powered classification, and validates the results—automatically.

Figure 1: End-to-end flow — from new email arrival to auto-labeled inbox, orchestrated by Paradime Bolt.

What Is Paradime?

Paradime is an AI-native data platform—often called "Cursor for Data"—that replaces dbt Cloud™. Analytics and data engineering teams use it to code, ship, debug, and scale data pipelines for analytics and AI.

For this tutorial, the star feature is Bolt, Paradime's production orchestrator. Bolt lets you schedule dbt™ commands and Python scripts on a cron cadence, manage environment variables securely, and monitor every run with full log history. Think of it as a lightweight, managed scheduler that lives right next to your data project—no external Airflow or cron server required.

Key Bolt capabilities we'll use:

📖 Reference: Bolt Python Scripts documentation · Trigger Types

What Is OpenClaw?

OpenClaw is an open-source AI agent that runs locally (or via API) and orchestrates tasks across chat apps, files, the web, and your operating system. It isn't an LLM itself—it connects to models like Claude or GPT and uses skills to act on their output.

In our workflow, we use OpenClaw's Python SDK to classify email content. Rather than writing brittle regex rules for every possible sender domain or subject line pattern, we hand the email metadata and a content snippet to an OpenClaw agent and ask it to return a structured label classification. The agent uses an LLM under the hood, which means it handles edge cases—marketing disguised as transactional mail, internal project threads with vague subjects, vendor invoices from new domains—with far more nuance than static rules.

Figure 2: OpenClaw acts as a broker between your script and the underlying LLM, returning structured classifications.

Setup: openclaw-sdk + Gmail API

Before writing the script, you need two things configured: Gmail API credentials and an OpenClaw API key.

Step 1: Enable the Gmail API and Create OAuth Credentials

1. Go to the Google Cloud Console and create a new project (e.g., paradime-gmail-labeler).

2. Navigate to APIs & Services → Library, search for Gmail API, and click Enable.

3. Go to APIs & Services → OAuth consent screen. Select External user type, fill in the app name and support email, then save.

4. Add the scope https://www.googleapis.com/auth/gmail.modify — this grants read + write access to labels.

5. Go to APIs & Services → Credentials → Create Credentials → OAuth client ID. Choose Desktop app, name it Paradime Labeler, and download the JSON file.

Save the contents of that JSON file—you'll paste it into a Paradime environment variable shortly.

Step 2: Generate a Token File

Run the Google quickstart locally once to generate a token.json:

This will open a browser window, authorize the app, and produce token.json. You'll store the contents of both credentials.json and token.json as environment variables in Paradime.

📖 Reference: Gmail API Python Quickstart

Step 3: Get Your OpenClaw API Key

Install the OpenClaw Python SDK:

Set your API key from your OpenClaw provider dashboard (Anthropic, OpenAI, or local model endpoint):

Verify the installation:

The Script: Fetch, Classify, Label, Validate

Here's the full Python script that ties everything together. It follows a strict measure → identify → fix → validate loop:

Figure 3: The repeatable measure → identify → fix → validate loop that runs every 30 minutes.

gmail_auto_label.py

How the Script Maps to the Workflow

Environment Variables: GOOGLE_CREDENTIALS_JSON and OPENCLAW_API_KEY

The script reads three environment variables. Never hardcode secrets—Paradime's Bolt provides a secure, encrypted variable store.

Setting Variables in Paradime

1. From any page in Paradime, click Settings.

2. Navigate to Workspaces → Environment Variables.

3. In the Bolt Schedules section, click Add New.

4. Add each variable:

1. Click the Save icon (💾).

Figure 4: Credentials flow from source to Paradime's secure environment variable store.

📖 Reference: Bolt Schedules Environment Variables

You can also override variables at the individual schedule level. For example, if you want to label a shared team inbox differently from your personal inbox, create two Bolt schedules pointing to the same script but with different GOOGLE_CREDENTIALS_JSON values.

📖 Reference: Environment Variable Overrides at Schedule Level

Bolt Schedule: Cron Every 30 Minutes

Now let's wire the script into Bolt so it runs automatically.

Step 1: Add Dependencies via Poetry

In your project's pyproject.toml:

Step 2: Create the Bolt Schedule

1. Navigate to the Bolt application from the Paradime home screen.

2. Click + New Schedule → + Create New Schedule.

3. Fill in the schedule settings:

1. In the Commands section, add two commands in order:

⚠️ Important: The poetry install command must be first. It installs all dependencies and creates the virtual environment before your script executes.

1. Configure notifications:

1. Click Save to publish the schedule.

Figure 5: The schedule fires every 30 minutes. Each run typically completes in under 2 minutes.

📖 Reference: Creating Bolt Schedules · Trigger Types — Scheduled Run

Monitoring and Debugging

Once the schedule is live, you need visibility into every run. Paradime's Bolt gives you three layers of observability.

Run Log History

Navigate to your schedule in Bolt and open the Run Log History tab. You'll see:

• Execution Time History — A 30-day graph showing success rates, error rates, duration trends, and skipped runs.

• Run History table — Each run listed with Run ID, status (Success / Error / Skipped), trigger source, branch, commit, timestamp, and duration.

Click any Run ID to drill into the detailed analysis view.

Figure 6: Drill-down path from schedule overview to individual run diagnostics.

What to Look For

Reading the Script Logs

The script uses Python's logging module with structured output. In the Bolt run details, look for lines like:

📖 Reference: Viewing Run Log History · Analyzing Individual Run Details

Troubleshooting Common Issues

1. RuntimeError: Token expired and no refresh token available

Cause: The GOOGLE_TOKEN_JSON contains a token that has expired, and Google didn't include a refresh token in the original OAuth flow.

Fix:

1. Re-run the local auth script (python gmail_auto_label.py locally with credentials.json present).

2. When the browser opens, revoke the existing app permission in Google Account Permissions first.

3. Re-authorize. Google will issue a fresh token with a refresh token.

4. Copy the new token.json contents into the GOOGLE_TOKEN_JSON env var in Paradime.

2. HttpError 429: Rate Limit Exceeded

Cause: Gmail API rate limits are 250 quota units per second per user. Rapid consecutive messages.get() calls can exceed this.

Fix: Add a small sleep between API calls:

3. OpenClaw Returns Invalid Classifications

Cause: The LLM occasionally returns a category not in your LABEL_MAP, or includes extra text.

Fix: The script already handles this with a fallback to "other". To improve accuracy:

• Add more examples to the classification prompt (few-shot prompting).

• Tighten the prompt: "Reply with ONLY the category key. No quotes, no explanation, no punctuation."

• Switch to a more capable model (e.g., from claude-3-5-sonnet to claude-3-opus).

4. poetry install Fails in Bolt

Cause: Missing or malformed pyproject.toml, or the file isn't committed to the branch Bolt is running.

Fix:

1. Verify pyproject.toml is committed to the main branch (or whichever branch your schedule targets).

2. Run poetry lock locally and commit the poetry.lock file as well.

3. Ensure the first command in your Bolt schedule is poetry install.

📖 Reference: Python Scripts in Bolt · Using Poetry in Paradime

5. Labels Created but Not Visible in Gmail UI

Cause: Gmail label visibility settings. The script sets labelListVisibility: "labelShow" and messageListVisibility: "show", but nested labels (like Finance/Invoices) may appear collapsed.

Fix: In Gmail's left sidebar, scroll down and click "More" to expand all labels. You can also rearrange label visibility in Settings → Labels.

Quick Diagnostic Checklist

Figure 7: Decision tree for diagnosing failed or unexpected Bolt runs.

Wrapping Up

You've built a complete, production-grade Gmail auto-labeling system that:

1. Measures — Connects to Gmail and surveys the inbox.

2. Identifies — Finds emails with no user-applied labels.

3. Fixes — Uses OpenClaw's AI classification to determine the right label and applies it via the Gmail API.

4. Validates — Re-checks every processed email to confirm the label stuck and logs success metrics.

This entire workflow runs on a 30-minute cron schedule in Paradime Bolt, with secrets stored securely as environment variables, full run-log history for debugging, and Slack/email alerts on failure.

What You've Gained

Next Steps

• Expand the label taxonomy. Add categories specific to your workflow — engineering/pull-requests, legal/contracts, hiring/candidates.

• Chain with dbt™ models. Log classification results to a warehouse table, then build dbt™ models to analyze email volume trends, response time SLAs, or sender patterns.

• Trigger on merge. Use Bolt's On Merge trigger type to redeploy the labeling script whenever you push prompt improvements to main.

• Add a feedback loop. Track emails you manually re-label after the AI classifies them, feed that data back into the prompt for continuous improvement.

📖 Get started with Paradime: paradime.io · Bolt docs: docs.paradime.io/bolt · OpenClaw docs: docs.openclaw.ai