README.md

📧 Topmo 📧

Note

Topmo is a Gmail agent that signs into any Google account via production OAuth, learns the owner's voice from their sent history, drafts replies, labels and files newsletters and receipts automatically, and proactively surfaces threads the user sent days ago with no reply, so follow-ups never fall through the cracks.

📑 Table of Contents

• 🌟 Features
• 🧠 AI Capabilities & MeshAPI Pipeline
• 🛠️ Tech Stack & Under the Hood
  • Codebase Architecture & Security Patterns
  • How the Cron Orchestrator Works
• 🗄️ Database Stats & Schema
• 💻 Installation & Setup
  • Environment Variables
  • Local Setup
• 📷 Screenshots
• 💻 Contributing
• 🙋‍♂️ Issues
• 👤 Author
• 📄 License

Video Demo Watch the quick walkthrough on YouTube.

🌟 Features

AI Voice Matching Learns style from history.	Smart Follow-Ups Highlights unanswered sent threads.	Auto-Drafting Generates drafts matching voice.	Email Classification Filters incoming email threads.
Inbox Rules Executes custom rules natively.	Gmail Labels Syncs labels to Gmail.	Voice Overrides Custom greetings and footers.	Admin Portal Monitors logs and content.
Background Cron Processes inbox every tick.	Email Summarize Summarizes long threads instantly.	Body Preview Inspects full email content.	Custom Controls Everything is fully customizable.

🧠 AI Capabilities & MeshAPI Pipeline

Topmo’s core intelligence relies completely on MeshAPI, a unified LLM gateway. The entire agentic pipeline is built to leverage MeshAPI for inference, strict structured JSON outputs, embeddings, and background batch processing.

Why MeshAPI is Critical:

• Pinned Aliases for Latency: We pin specific models via MeshAPI aliases to ensure predictable latencies per endpoint.
• Strict Structured Outputs: Topmo relies heavily on structured output format tightly integrated with our internal validation schemas. This guarantees every AI output (like classification tags or voice profile deltas) returns perfectly typed JSON.
• Unified Gateway: Whether generating tts or complex chat completions, MeshAPI provides a single, scalable unified endpoint handling all underlying AI providers seamlessly.

The AI Pipeline Features:

• Intelligent Classification: Evaluates every incoming email to automatically classify it into categories like REPLY_NEEDED, FYI, NEWSLETTER, RECEIPT, or SPAM, ensuring you only focus on what matters.
• Voice Profiling: Performs a deep extraction on a sample of your past sent emails to build a unique Voice Profile, learning your formality, average length, emoji use, and sign-offs. It can also be customized from a description or custom samples.
• Draft Generation: Acts as an intelligent ghostwriter to compose high-quality, ready-to-send email replies that precisely match your voice profile and contextual thread history.
• Explicit Rules: Natively handles and executes complex user inbox rules, applying explicit logical decisions on when to skip, label, or force a reply.

🛠️ Tech Stack & Under the Hood

• Framework: SvelteKit 2 + Svelte 5
• Package Manager: Bun
• Database: Turso (libSQL) serverless SQLite
• ORM: Drizzle ORM
• Styling: Tailwind CSS v4
• Validation: Zod v4
• Google SDK: googleapis + google-auth-library (OAuth + Gmail API)
• LLM Gateway: MeshAPI
• Email Parsing: mailparser (Plaintext extraction & quote stripping)
• Encryption: Built-in cryptographic algorithms for AES-256-GCM (For Refresh Tokens)

Codebase Architecture & Security Patterns

• Repository Pattern: All database access flows through strict repository functions requiring a user ID to guarantee multi-tenant safety. Raw calls are blocked by ESLint.
• Prompt-Injection Guards: Raw email content is wrapped in a guard function and parsed to strip quotes and signatures, minimizing injection risks.
• Encrypted Token Storage: Google OAuth Refresh Tokens are encrypted at rest using AES-256-GCM with versioned keys for safe storage and easy rotation.

How the Cron Orchestrator Works

Topmo's background tasks are triggered by a cron job hitting the /api/cron/tick endpoint. This can be configured via Vercel Cron (every 5 minutes), run locally via the dev:tick script, or driven by the included GitHub Actions workflow (.github/workflows/cron.yml) which runs every 30 minutes.

The cron orchestrator:

1. Queries the Turso database for users whose lastProcessedAt is older than the interval limit.
2. Decrypts their stored Google refresh tokens dynamically.
3. Fetches unread emails via the Gmail API and parses the content securely.
4. Pings MeshAPI to run the AI classification and extraction pipeline.
5. Orchestrates auto-drafts and follow-up DB updates—all while heavily parallelizing tasks to strictly adhere to Vercel's Serverless function timeout constraints.

🗄️ Database Stats & Schema

Topmo uses Turso (libSQL) with Drizzle ORM. It requires zero-ops connections and seamlessly runs serverless or as a local SQLite file (topmo.db).

Core Tables:

• users: Stores emails, encrypted OAuth tokens, generated voice profiles (JSON), processing timestamps, and daily token budgets.
• emails: Records parsed email metadata, classifications, and actions taken (avoids duplicate processing).
• drafts: Contains AI-generated replies tied to a specific email/user, tracking its status (pending/sent/discarded) and voice edit deltas.
• actions: Audit log of all actions taken and LLM tokens used.
• follow_ups: Tracks sent emails and triggers an alert if the threshold days pass without a reply.
• voice_deltas: Captures manual edits you make to AI drafts to incrementally adjust your voice profile.

💻 Installation & Setup

You can self-host Topmo easily for personal use.

Environment Variables

Copy .env.example to .env and configure it step-by-step:

cp .env.example .env

1. MeshAPI Keys: Sign up at MeshAPI and set MESH_API_KEY.
2. Turso (Prod): Set TURSO_DATABASE_URL and TURSO_AUTH_TOKEN. Leave empty for local development (defaults to a local SQLite file).
3. Google OAuth: Set up an OAuth 2.0 Client in Google Cloud Console. Make sure to enable the Gmail module in Google APIs and Services.
   • Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
   • Set GOOGLE_OAUTH_REDIRECT to http://localhost:5173/auth/callback (or your production URL).
4. Secrets Generation: Generate secure random strings for the application:

   openssl rand -base64 32 # Paste into TOKEN_ENCRYPTION_KEY
   openssl rand -hex 32    # Paste into SESSION_SECRET
   openssl rand -hex 32    # Paste into CRON_SECRET

Local Setup

terminal

# 1. Install dependencies via Bun
bun install

# 2. Generate migrations and push schema to local SQLite db
bun run db:generate
bun run db:push

# 3. Start development server
bun run dev

📷 Screenshots

Here's a working and expected screenshot of Topmo

Inbox & Command Center (/inbox)	Rules & Configurations (/rules)	Account Settings (/settings)
Database Status (/db)	Landing Page (/)	Admin Dashboard (/admin)

Landing Page Full Preview

---

💻 Contributing

Tip

We welcome contributions to improve Topmo! If you have suggestions, bug fixes, or new feature ideas, follow these steps:

1. Fork the Repository
   Click the Fork button at the top-right of the repo page.

2. Clone Your Fork
   Clone the repo locally:

   git clone https://github.com/ArnavK-09/topmo.git

3. Create a Branch
   Create a new branch for your changes:

   git checkout -b your-feature-branch

4. Make Changes
   Implement your changes (bug fixes, features, etc.).

5. Commit and Push
   Commit your changes and push the branch:

   git commit -m "feat(scope): description"
   git push origin your-feature-branch

6. Open a Pull Request
   Open a PR with a detailed description of your changes.

7. Collaborate and Merge
   The maintainers will review your PR, request changes if needed, and merge it once approved.

🙋‍♂️ Issues

Found a bug or need help? Please create an issue on the GitHub repository with a detailed description.

👤 Author

Arnav K

---

📄 License

Topmo is licensed under the MIT License. See the LICENSE file for more details.

---

🌟 If you find this project helpful, please give it a star on GitHub! 🌟