Gmail SecretaryIMAP/SMTP Client for AI Agents

Quick Start ​

Install via Docker (recommended):

# docker-compose.yml
services:
  workspace-secretary:
    image: ghcr.io/johnneerdael/gmail-secretary-map:latest
    container_name: workspace-secretary
    restart: always
    ports:
      - "8000:8000"
    volumes:
      - ./config:/app/config
    environment:
      - LOG_LEVEL=INFO

Important: Generate a unique bearer token for security:

# macOS/Linux
uuidgen

# Windows PowerShell
[guid]::NewGuid().ToString()

Add to your config.yaml:

bearer_auth:
  enabled: true
  token: "your-generated-uuid-here"

Then start with: docker compose up -d

See Getting Started for complete installation instructions.

Why Gmail Secretary MCP? ​

Traditional email clients are built for humans. Gmail Secretary MCP is built for AI assistants.

• Instant reads: SQLite cache means sub-millisecond email queries
• Persistent connections: Engine maintains IMAP connection (no per-request reconnect)
• Token-efficient: Bulk email fetching with smart truncation (700 chars) for fast triage
• Context-rich: Full thread history, attachment content, and calendar context in one tool call
• Intelligence signals: VIP detection, urgency markers, question detection—not hardcoded decisions
• Agentic workflows: Compose specialized agents (Triage, Scheduler, Intelligence Clerk) using atomic tools

Example Workflows ​

What's New in v4.8.0 ​

Database Layer Refactoring & Bug Fixes:

• 🗄️ Shared Query Modules: All SQL queries extracted to db/queries/ modules (56 functions total)
• 📉 ~1,070 Lines Removed: Eliminated duplicate SQL between engine and web layers
• 🔧 Bug Fixes:
  • Calendar page no longer returns 500 error (missing strftime filter)
  • Email sync works correctly (boolean type mismatch fixed)
  • Embedding sync no longer errors (missing methods added)
  • CSRF tokens now sent correctly with HTMX requests

See the Architecture Documentation for the new database layer structure.

What's New in v4.7.x ​

Critical Bug Fixes:

• 🔐 OAuth2 Token Persistence: Refreshed tokens now properly saved to disk (v4.7.2)
• 🧠 Embedding Dimensions: Fixed config path for embedding dimensions (v4.7.1)
• 🗄️ Shared Database Layer: New workspace_secretary/db/ module for unified access

What's New in v4.6.0 ​

Calendar Caching & Offline-First Architecture:

• ⚡ Instant Calendar Reads: 10x faster queries via intelligent caching
• 🌐 Offline-First Events: Create/edit/delete events without internet
• 🔄 Background Worker: Autonomous sync daemon with incremental updates
• 🏷️ Status Badges: Visual indicators for pending sync and conflicts
• ⚙️ Calendar Selection: Choose which calendars to display in settings

What's New in v4.4.0 ​

Web UI Configuration:

• 📝 Config Documentation: Added web UI configuration options to config.sample.yaml

What's New in v4.3.3 ​

Phase 4 Dashboard:

• 📊 Dashboard Stats: Email statistics overview (total, unread, today's count)
• ⚡ Priority Queue: Priority email list with quick actions
• ⌨️ Keyboard Shortcuts: j/k navigation, o to open, r to reply

What's New in v4.3.2 ​

halfvec Support for High Dimensions:

• 🧠 Automatic Quantization: 16-bit halfvec type for dimensions > 2000
• 🔧 HNSW Fix: Resolves "column cannot have more than 2000 dimensions" error
• 📉 50% Storage Savings: halfvec uses half the space with ~0.1% recall loss

What's New in v4.3.0 ​

Gemini Embeddings & Provider Fallback:

• 🧠 Google Gemini Provider: Native google-genai SDK with task_type optimization
• 🔄 Automatic Fallback: Switch providers on rate limit (Cohere → Gemini or vice versa)
• 📊 L2 Normalization: Auto-normalizes Gemini vectors for dimensions ≠ 3072
• 📖 Detailed Guides: Copy-paste configs with rate limits, sync time estimates, batch calculators

See Embeddings Guide for configuration details.

What's New in v4.2.7 ​

Gap Sync & Accurate Counters:

• 🔍 Set Difference Sync: Compares IMAP UIDs vs DB UIDs to find exactly what's missing
• 📊 Real Progress: Counters reflect actual DB state, not estimates
• 🔧 Gap Recovery: Fixes sync when emails were synced from both ends leaving a gap

What's New in v4.2.6 ​

Resumable Sync & Stability Fixes:

• 🔄 Resume on Restart: Sync picks up where it left off using stored uidnext
• 📡 IDLE Starts Immediately: Real-time email detection even during initial sync
• 🛡️ Embeddings Stability: Filters invalid texts, prevents 400 errors from empty emails
• 📊 Accurate Progress: Shows "Resuming (16000/26000 done, 10000 remaining)"

What's New in v4.2.5 ​

Lockstep Sync+Embed Architecture — Fixes critical race conditions:

• 🔄 Lockstep Processing: Sync 50 emails → embed those 50 → repeat (no parallel race)
• 📊 Oldest-First Sync: Now processes all emails from oldest to newest UID
• ⚡ Event Loop Fixes: Pool init runs in executor, httpx client reused with semaphore
• 🛡️ Race Condition Fixed: Embeddings can no longer exceed synced email count

What's New in v4.2.4 ​

Parallel Sync & Smart Scheduling:

• ⚡ Parallel Folder Sync: Up to 5 concurrent IMAP connections via connection pool
• 🔄 IDLE + Catch-up Strategy: Real-time INBOX push, 30-min periodic catch-up for other folders
• 🎛️ Configurable: MAX_SYNC_CONNECTIONS and SYNC_CATCHUP_INTERVAL env vars

What's New in v4.2.3 ​

Fix for IDLE Blocking Issues:

• Threaded IDLE Operation:
  • Moved idle_start, idle_done, idle_check to a dedicated thread.
  • Prevents event loop blocking during IMAP IDLE.
• Event-loop Safe Communication:
  • Uses loop.call_soon_threadsafe() for updates.
• Updated Documentation:
  • Added architecture section for threaded IDLE pattern.

What's New in v4.2.2 ​

Bug Fixes & Documentation Overhaul:

• 🔧 Database Init Fix: Engine now properly initializes database connection pool
• 🐘 PostgreSQL Support: Docker image includes psycopg drivers out of the box
• 📝 Sync Logging: INFO-level logs show sync progress ("Synced N emails from INBOX")
• 📚 Docs Refresh: Simplified OAuth setup, added PostgreSQL guide, updated threading docs

What's New in v4.2.1 ​

Authentication UX Improvements — Easier setup with better error messages:

• 🔐 Fixed OAuth Token Storage: auth_setup now saves client_id and client_secret in token.json (fixes "Missing client_id or client_secret" error)
• 📋 Better Setup Instructions: Startup warning now shows both OAuth2 and App Password options
• 🔒 Hardcoded Config Paths: Removed user-configurable output paths to prevent misconfiguration

What's New in v4.2.0 ​

Calendar API Passthrough — Simplified architecture with real-time calendar access:

• 🗓️ Direct API Access: Calendar operations now go directly to Google Calendar API (no local caching)
• ⚡ Real-Time Data: All calendar queries return live data, no sync staleness
• 🧹 Simplified Architecture: Removed calendar database tables and sync complexity
• 🔧 New Endpoints: Added 6 new calendar API endpoints for fine-grained control

New Calendar API Endpoints ​

Removed ​

• calendar_cache.py — Calendar caching layer removed
• gmail_client.py — Deprecated Gmail REST API client removed
• CalendarSync class — No longer needed without caching
• Calendar database tables (calendars, events, attendees)
• calendar_cache_path config option (ignored if present)

What's New in v4.1.0 ​

CONDSTORE & IDLE Support — Efficient incremental sync with push notifications:

• ⚡ CONDSTORE (RFC 7162): Skip sync when mailbox unchanged, fetch only changed flags via CHANGEDSINCE
• 📬 IMAP IDLE (RFC 2177): Push-based notifications for instant new mail detection
• 🏷️ Gmail Extensions: Native X-GM-MSGID, X-GM-THRID, X-GM-LABELS support
• 📎 Attachment Metadata: has_attachments and attachment_filenames stored in database
• 🔄 Debounced Sync: Mutations trigger 2-second debounced sync to batch rapid changes

Performance Improvements ​

What's New in v4.0.0 ​

Complete Architecture Rewrite — Read/Write Split for reliability and consistency:

• 🔄 Engine Owns All Writes: Engine now uses DatabaseInterface for all database mutations
• 📖 MCP is Read-Only: MCP reads directly from database, calls Engine API only for mutations
• 🗄️ Unified Database: Both Engine and MCP use the same DatabaseInterface abstraction
• 📅 Integrated Calendar Sync: Calendar operations now use direct API passthrough (no local caching)
• 🧠 Auto Embeddings: Engine generates embeddings automatically after email sync (PostgreSQL)
• 🚀 Graceful Enrollment: Engine starts in "no account" mode, auto-connects when OAuth tokens appear

New Engine API Endpoints ​

See the Architecture Documentation for the complete technical overview.

What's New in v3.2.0 ​

Standardized Docker Paths & OAuth Consolidation:

• 📁 Config Path: /app/config/config.yaml is now the default (Docker-first)
• 🔐 Single OAuth Entry: auth_setup.py handles all OAuth flows (browser_auth removed)
• 📅 Calendar Scope: OAuth now includes Gmail + Calendar scopes by default
• 🛠️ Token Output: --token-output flag for Docker-friendly token management

What's New in v3.1.0 ​

Single Container Architecture — Simplified deployment with supervisor-managed processes:

• 📦 One Container: Engine + MCP server run together via supervisord
• 🔌 Unix Socket IPC: Internal communication between processes
• ⚡ Persistent IMAP: Engine maintains connection (no per-request reconnect)
• 🔄 Background Sync: Continuous incremental sync every 5 minutes
• 📝 Better Docs: Added credentials.json example format

What's New in v3.0.0 ​

Dual-Process Architecture — Complete separation of concerns for reliability:

• 🔄 Engine + MCP Split: Independent sync daemon + MCP server
• 📅 Calendar Sync: Full calendar synchronization with local SQLite cache
• 🧠 Semantic Search: Optional PostgreSQL + pgvector backend with embeddings
• ⚡ Database Options: SQLite (default) or PostgreSQL with pgvector for AI features
• 🚫 IMAP-Only: Removed deprecated API mode (oauth_mode config removed)

Database Options ​

See the Architecture Documentation for technical details.

What's New in v2.2.0 ​

RFC 5256 Threading Support — Full conversation threading with automatic backfill:

• 🧵 Server-Side Threading: Uses IMAP THREAD command (RFC 5256) when available
• 🔄 Automatic Backfill: Existing emails get thread headers populated on first sync
• 📊 Thread Data Model: in_reply_to, references, thread_root_uid stored in SQLite
• ⚡ Cache-First Threads: get_email_thread queries local cache instead of IMAP

See the Threading Guide for details.

Previous Releases ​

See Migration Guide for upgrading from earlier versions.

Community & Support ​

• GitHub Repository
• Report Issues
• View Releases