IntentMail

Multi-surface email platform with MCP server, Discord bot, and web dashboard. AI-powered email management with team collaboration features.

What This Is

A complete email management platform:

• MCP Server: 19 tools for programmatic email access
• Discord Bot: Slash commands for inbox management
• Web Dashboard: React/PWA for browser-based access
• Team Collaboration: Shared inboxes, assignments, analytics
• AI Features: Smart drafts, semantic search, inbox triage

---

Status

v0.4.0 - All core epics complete.

Implemented:

• Gmail connector (OAuth, History API delta sync)
• 19 MCP tools with rules engine + rollback
• Discord bot with slash commands
• Web dashboard with PWA support
• Team collaboration (shared inboxes, assignments)
• AI features (drafts, semantic search, triage)

Not done:

• Outlook connector OAuth testing
• Integration tests with real Gmail
• Production deployment validation

---

Quick Start (Development)

Prerequisites

node --version  # v20 or higher
npm --version   # v10 or higher

1. Clone and Install

git clone https://github.com/intent-solutions-io/intent-mail.git
cd intent-mail
npm install

2. Set Up Gmail OAuth (One-Time)

Create OAuth credentials:

1. Go to Google Cloud Console
2. Create a new project (or use existing)
3. Enable Gmail API: https://console.cloud.google.com/apis/library/gmail.googleapis.com
4. Create OAuth 2.0 Client ID:
   • Application type: Web application
   • Authorized redirect URIs: http://localhost:3000/oauth/callback
5. Copy the Client ID and Client Secret

Configure environment:

cp .env.example .env
# Edit .env and add your credentials:

# .env
GMAIL_CLIENT_ID=your-client-id.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=your-client-secret
GMAIL_REDIRECT_URI=http://localhost:3000/oauth/callback

Set up OAuth consent screen (required by Google):

1. Go to: https://console.cloud.google.com/apis/credentials/consent
2. Choose External (unless you have Google Workspace)
3. Fill in app name: IntentMail Dev
4. Add your email as a test user
5. Click Save

3. Build and Run

# Build TypeScript
npm run build

# Start MCP server
npm start

You should see:

Database initialized at ./data/intentmail.db
intentmail-mcp-server v0.1.0 started successfully
Listening on stdio...

4. Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "intentmail": {
      "command": "node",
      "args": ["<absolute-path-to-intent-mail>/dist/index.js"]
    }
  }
}

Replace <absolute-path-to-intent-mail> with the full path where you cloned the repository (e.g., /Users/you/projects/intent-mail on macOS, /home/you/intent-mail on Linux).

Restart Claude Desktop, then try:

Use the health_check tool

5. Authorize Gmail

In Claude Desktop:

Use mail_auth_start with provider: gmail

Click the URL, authorize, and you're ready!

---

MCP Tools (19 Total)

Authentication & Accounts

• health_check - Server status and capabilities
• mail_auth_start - Start OAuth flow (Gmail/Outlook)
• mail_auth_complete - Complete OAuth with code
• mail_list_accounts - List connected accounts

Email Operations

• mail_sync - Sync emails from provider (delta sync)
• mail_sync_stats - View sync statistics
• mail_search - Full-text search with filters
• mail_get_thread - Get email thread with all messages
• mail_send - Send email with threading support

Labels & Organization

• mail_list_labels - List all labels/folders
• mail_apply_label - Apply labels to emails

Attachments

• mail_list_attachments - List email attachments
• mail_get_attachment - Download attachment

Rules & Automation

• mail_list_rules - List automation rules
• mail_create_rule - Create new rule
• mail_delete_rule - Delete rule
• mail_apply_rule - Apply rule with dry-run support

Audit & Rollback

• mail_get_audit_log - View execution history
• mail_rollback - Rollback rule executions

---

Architecture

┌──────────────────────────────────────────┐
│   Claude Code / AI Assistant             │
└────────────────┬─────────────────────────┘
                 │ MCP Protocol (stdio)
┌────────────────▼─────────────────────────┐
│   IntentMail MCP Server (Node.js)        │
│   ┌────────────────────────────────────┐ │
│   │ 19 MCP Tools                       │ │
│   │ (search, send, rules, rollback)    │ │
│   └──────────────┬─────────────────────┘ │
│                  │                        │
│   ┌──────────────▼─────────────────────┐ │
│   │ Rules Engine + Audit Log           │ │
│   │ (dry-run, plan, rollback)          │ │
│   └──────────────┬─────────────────────┘ │
│                  │                        │
│   ┌──────────────▼─────────────────────┐ │
│   │ SQLite Storage + FTS5 Search       │ │
│   │ (local database, full-text index)  │ │
│   └──────────────┬─────────────────────┘ │
└──────────────────┼───────────────────────┘
                   │
      ┌────────────┴────────────┐
      │                         │
┌─────▼──────┐         ┌───────▼────────┐
│  Gmail API │         │  Outlook Graph │
│  (History) │         │  (Delta sync)  │
└────────────┘         └────────────────┘

---

Features

Delta Sync

• Gmail: Uses History API with historyId tracking
• Outlook: Uses Graph API /delta endpoint with deltaToken
• Only fetches changed emails, not entire mailbox
• Works alongside normal email usage (web, mobile apps)

Rules-as-Code

// Create a rule
mail_create_rule({
  name: "Archive Newsletters",
  conditions: [
    { field: "from", operator: "contains", value: "newsletter" }
  ],
  actions: [
    { type: "archive" }
  ]
})

// Test it first (dry-run)
mail_apply_rule({ ruleId: 1, dryRun: true })
// Shows: "Would archive 15 emails"

// Apply it
mail_apply_rule({ ruleId: 1, dryRun: false })

// Changed your mind?
mail_rollback({ ruleId: 1 })
// Restores all emails to previous state

Audit Trail

All actions logged with before/after states:

{
  "ruleId": 1,
  "emailId": 42,
  "stateBefore": { "labels": ["INBOX"], "flags": [] },
  "stateAfter": { "labels": ["ARCHIVED"], "flags": ["SEEN"] },
  "executedAt": "2025-12-24T10:00:00Z"
}

Local Storage

• Email stored in SQLite (./data/intentmail.db)
• OAuth tokens encrypted with OS keychain
• No cloud storage required
• Offline access after initial sync

---

Development Workflow

Run Tests

npm test                 # Run all tests
npm run typecheck        # TypeScript strict mode check

Database Inspection

sqlite3 ./data/intentmail.db
> .tables
> SELECT * FROM accounts;
> SELECT COUNT(*) FROM emails;

OAuth Testing

# Automatic mode (opens browser)
node test-oauth-auto.js

# Manual mode (paste code)
node test-oauth.js

Task Tracking

bd list                  # List all tasks
bd show <id>             # Show task details
bd update <id> --status in_progress

---

Deployment

Docker (Recommended)

Quick start:

docker-compose up -d

For distribution: See Docker Guide for:

• Multi-platform builds (AMD64, ARM64)
• Docker Hub publishing
• Custom client connections
• Security best practices

Cloud Deployment

• Local/Docker: ✅ Recommended (see Docker Guide)
• Google Cloud Run: ❌ Not recommended (MCP requires stdio, not HTTP)
• Compute Engine: ✅ Works (VM with Docker)
• Kubernetes: ✅ Works (GKE, K8s)

See Setup Guide for infrastructure details (Terraform, WIF).

---

Security

OAuth 2.0 only. No passwords stored.

Security features:

• OAuth tokens encrypted (OS keychain)
• Input validation with Zod schemas
• Audit log for all actions
• Rate limiting with exponential backoff
• TypeScript strict mode

Requirements:

• Don't commit .env files
• Don't share OAuth credentials
• Test rules with dry-run first

Report vulnerabilities: Security Policy

---

Roadmap

Current (Phase 3):

• Gmail connector (done)
• Rules engine (done)
• Outlook connector (needs testing)
• Integration tests (in progress)

Next (Phase 4):

• Real-time sync (push notifications)
• Background sync daemon
• Multi-account support
• Rule scheduling

Later (Phase 5):

• Web UI
• Analytics
• IMAP connector

---

FAQ

Q: Does this replace Gmail/Outlook? No - IntentMail is a layer on top. You keep using Gmail/Outlook normally. IntentMail just gives AI access to automate things.

Q: What happens if I use Gmail while IntentMail is running? Everything stays in sync. Gmail is the source of truth. Changes you make in Gmail web/mobile show up in IntentMail, and vice versa.

Q: Can I undo actions? Yes! Every rule execution is logged with before/after states. Use mail_rollback to restore emails to their previous state.

Q: Is my email data safe? Email is stored locally in SQLite (not in the cloud). OAuth tokens are encrypted. Code is open source for review.

Q: Does this work with personal Gmail accounts? Yes - works with both personal Gmail and Google Workspace accounts.

---

Contributing

We welcome contributions! See Contributing Guide for:

• Code style guidelines
• How to add new connectors
• PR review process
• Where planning docs live

---

Project Structure

intent-mail/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── mcp/tools/            # 19 MCP tool implementations
│   ├── connectors/           # Gmail, Outlook, IMAP
│   ├── rules/                # Rules engine + parser
│   ├── storage/              # SQLite + migrations
│   └── types/                # TypeScript interfaces
├── infra/                    # Terraform (GCP deployment)
├── .github/workflows/        # CI/CD pipelines
├── test-oauth-auto.js        # OAuth testing scripts
└── data/                     # SQLite database (gitignored)

---

License

TBD - To be determined once project reaches beta.

---

Links

• Documentation: 000-docs/
• GitHub: https://github.com/intent-solutions-io/intent-mail
• Issues: Use Beads task tracking (bd list)
• Security: Security Policy
• FAQ: FAQ - Common questions answered
• Docker: Docker Guide - Deployment guide

---

Stack: TypeScript, Node.js 20, SQLite, MCP SDK, Gmail API, Microsoft Graph

Status: Alpha. Breaking changes expected.