mymailclaw

Email scanner, categorizer, and cleaner CLI for the OpenClaw ecosystem. Connects to Gmail and IMAP accounts, categorizes emails by rules (or AI), and lets you safely clean up your inbox with a review-first workflow.

Commands

Accounts

| Command | Description | |---------|-------------| | mmclaw accounts add | Add a Gmail or IMAP account | | mmclaw accounts list | List configured accounts | | mmclaw accounts remove <id\|email> | Remove an account |

Scan

Fetches emails from all configured accounts and categorizes them locally.

| Command | Description | |---------|-------------| | mmclaw scan | Fetch and categorize using rules only | | mmclaw scan --since <period> | Fetch emails since N days (d), weeks (w), or months (m) - e.g. 7d, 2w, 1m, 365d | | mmclaw scan --limit <n> | Cap emails fetched per account (default: all emails in the date range) | | mmclaw scan --account <id\|email> | Scan a specific account only | | mmclaw scan --ai | Use AI to categorize emails that rules cannot classify with confidence |

List

| Command | Description | |---------|-------------| | mmclaw list | Show all emails grouped by category with counts | | mmclaw list --category <cat> | Filter by category | | mmclaw list --limit <n> | Limit number of results shown | | mmclaw list --account <id\|email> | Filter by account |

Clean

Dry-run by default - previews what would be cleaned and writes a review file.

| Command | Description | |---------|-------------| | mmclaw clean | Preview all emails that would be cleaned (dry-run) | | mmclaw clean --category <cat> | Filter by category | | mmclaw clean --older-than <period> | Filter by age - e.g. 30d, 6m, 365d | | mmclaw clean --action <action> | delete moves to Trash, archive removes from Inbox but keeps the email (default: delete) | | mmclaw clean --account <id\|email> | Filter by account | | mmclaw clean --execute | Actually perform the cleanup - shows a WARNING and requires confirmation | | mmclaw clean --from-file <path> | Execute cleanup from a reviewed dry-run file - always prompts confirmation |

Unsubscribe

Reads List-Unsubscribe headers stored during scan. Dry-run by default - no action taken until --execute.

| Command | Description | |---------|-------------| | mmclaw unsubscribe | List emails with unsubscribe links, showing HTTP vs mailto | | mmclaw unsubscribe --execute | Follow HTTP unsubscribe links - unsubscribes on the sender's side, does not touch your inbox or DB | | mmclaw unsubscribe --category <cat> | Filter by category | | mmclaw unsubscribe --account <id\|email> | Filter by account | | mmclaw unsubscribe --limit <n> | Cap number of emails processed |

DB

Manage the local SQLite database. Does not touch your inbox.

| Command | Description | |---------|-------------| | mmclaw db stats | Show total count, categories, date range, and last scan time | | mmclaw db clean --older-than <period> | Preview emails to remove from DB (dry-run by default) | | mmclaw db clean --older-than <period> --execute | Actually remove emails from DB | | mmclaw db clean --older-than <period> --category <cat> --execute | Remove only matching category | | mmclaw db remove <id> | Remove a single email record from DB |

Categories

Emails are categorized as: marketing, newsletter, transactional, personal, work, social, unknown.

Classification uses rule-based matching first (sender domain, subject patterns, List-Unsubscribe header). Add --ai to use AI for emails that rules cannot classify with confidence. Rules are defined in data/rules.json - not hardcoded.

Cleanup Workflow

Cleanup is safe by design - dry-run is the default:

# 1. Preview - dry-run is the default, writes a review file
mmclaw clean --category marketing --older-than 30d

# 2. Review and edit the generated file at ~/.mymailclaw/exports/cleanup-YYYY-MM-DD.json
# Remove any entries you want to keep

# 3. Execute only what's in the file
mmclaw clean --from-file ~/.mymailclaw/exports/cleanup-YYYY-MM-DD.json

Each entry in the cleanup file includes the email ID, date, sender, subject, AI summary, category, and intended action. You stay in full control.

DB Management

The local DB grows over time as you scan. Use mmclaw db to inspect and clean it up.

# Show full DB summary
mmclaw db stats

# Preview what would be removed (dry-run)
mmclaw db clean --older-than 90d
mmclaw db clean --older-than 90d --category newsletter

# Actually remove from DB (not from inbox)
mmclaw db clean --older-than 90d --execute
mmclaw db clean --older-than 90d --category newsletter --execute

# Remove a single record
mmclaw db remove <email-id>

db clean only removes records from the local SQLite database - it does not touch your inbox.

Unsubscribe Workflow

mmclaw unsubscribe reads the List-Unsubscribe headers stored during scan and follows the HTTP links automatically. Mailto-only entries are flagged for manual action.

# Preview - lists all emails with unsubscribe links
mmclaw unsubscribe
mmclaw unsubscribe --category newsletter

# Execute - follow HTTP unsubscribe links
mmclaw unsubscribe --execute

HTTP links are followed with a GET request (with redirect following). This actually unsubscribes you from the mailing list on the sender's side - it does not delete or modify anything in your inbox or local DB. Mailto entries cannot be automated - the output tells you which senders require manual action.

Storage

All data stored at ~/.mymailclaw/. Override with MYMAILCLAW_HOME.

~/.mymailclaw/
├── .env               # GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET
├── config.json        # AI provider, model, API keys
├── accounts.json      # Gmail tokens and IMAP credentials (mode 600)
├── mymailclaw.db      # SQLite - emails, categories, scan history
└── exports/           # Dry-run cleanup files

Nothing is hardcoded. No credentials ever touch the repository.

Configuration

~/.mymailclaw/config.json:

{
  "provider": "anthropic",
  "model": "claude-haiku-4-5-20251001",
  "anthropicApiKey": "sk-ant-...",
  "openaiApiKey": "sk-..."
}

API keys are only needed when using --ai. Without --ai, no external calls are made.

Gmail Setup

Gmail requires OAuth2. You need a Google Cloud project with the Gmail API enabled:

1. Go to Google Cloud Console
2. Enable Gmail API - APIs & Services → Library → search "Gmail API" → Enable
3. Create credentials - APIs & Services → Credentials → Create Credentials → OAuth client ID
4. Application type: Desktop app
5. Go to OAuth consent screen → add your Gmail address as a test user
6. Put your credentials in ~/.mymailclaw/.env:

GMAIL_CLIENT_ID=your-client-id.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=GOCSPX-your-secret

Then run:

mmclaw accounts add
# Choose (1) Gmail - browser opens for authorization

IMAP Setup

mmclaw accounts add
# Choose (2) IMAP - enter host, port, username, password

Credentials are stored with mode 600 in ~/.mymailclaw/accounts.json.

File Structure

mymailclaw/
├── src/
│   ├── cli.ts                  # CLI entry point
│   ├── commands/
│   │   ├── accounts.ts         # accounts add/list/remove
│   │   ├── scan.ts             # fetch + categorize
│   │   ├── list.ts             # list by category
│   │   ├── clean.ts            # dry-run + execute cleanup
│   │   ├── unsubscribe.ts      # list + follow unsubscribe links
│   │   └── db.ts               # db stats / clean / remove
│   └── lib/
│       ├── types.ts            # TypeScript interfaces
│       ├── config.ts           # config and paths
│       ├── accounts.ts         # account storage
│       ├── db.ts               # SQLite layer
│       ├── rules.ts            # rule-based categorization
│       ├── ai.ts               # AI categorization
│       ├── gmail.ts            # Gmail OAuth2 + API
│       └── imap.ts             # IMAP connection
├── data/
│   └── rules.json              # classification rules (domains, patterns)
├── tests/
│   ├── rules.test.ts
│   ├── db.test.ts
│   ├── accounts.test.ts
│   ├── config.test.ts
│   ├── ai.test.ts
│   ├── scan.test.ts
│   ├── list.test.ts
│   ├── clean.test.ts
│   ├── unsubscribe.test.ts
│   └── db-command.test.ts
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── biome.json
├── LICENSE
└── README.md

Requirements

• Node 22+
• For Gmail: Google Cloud project with Gmail API enabled
• For AI: Anthropic or OpenAI API key

Install

npm install -g mymailclaw

The package is mymailclaw on npm. The binary is mmclaw.

Usage

# First run - add an account
mmclaw accounts add

# Scan inbox
mmclaw scan --since 7d

# Review categories
mmclaw list
mmclaw list --category marketing

# Preview cleanup (dry-run by default)
mmclaw clean --category marketing --older-than 30d

# Execute after review
mmclaw clean --from-file ~/.mymailclaw/exports/cleanup-YYYY-MM-DD.json

Testing

pnpm test

76 tests across 10 test files covering rules, db, accounts, config, AI, scan, list, clean, unsubscribe, and db commands.

Development

To work on mymailclaw locally, clone the repo and install dependencies:

pnpm install

Run the CLI directly from source without building first:

pnpm dev -- scan --since 7d
pnpm dev -- list
pnpm dev -- unsubscribe

Build the TypeScript to dist/:

pnpm build

Lint, format, and test:

pnpm lint
pnpm test

Related

• psclawmcp - MCP server exposing OpenClaw tools to AI assistants

License

See MIT