📬 Onebox

A unified, AI-powered email dashboard built to tame inbox chaos

Born from the frustration of juggling multiple email accounts, missing important follow-ups, and typing the same replies over and over — Onebox is a real-time, multi-account email management system that intelligently categorizes, searches, and helps you respond to emails faster.

What makes it different? Real-time IMAP sync (no polling!), AI-powered classification, semantic search for replies, and instant notifications for what matters — all wrapped in a clean, focused interface.

---

✨ Key Features

🔄 Real-Time IMAP Email Sync

Built on persistent IMAP connections using ImapFlow with live IDLE monitoring — your emails appear the moment they arrive.

• Multi-account support — manage all your inboxes in one place
• 30-day historical backfill on first sync
• Zero polling overhead — event-driven updates only
• Efficient parsing with mailparser

🔍 Lightning-Fast Search (Elasticsearch)

Every email is indexed instantly for sub-second search and filtering.

• Full-text search across subject, body, sender, and recipient
• Advanced filtering by account, folder (inbox/sent/spam), and AI category
• Pagination support (100 emails per page)
• Date-sorted results (newest first)

🤖 AI-Powered Email Categorization

Let AI do the triage work using Google Gemini (gemini-2.5-flash-lite).

Categories:

• ✅ Interested — warm leads and positive responses
• 📅 Meeting Booked — confirmed appointments
• ❌ Not Interested — polite declines
• 🚫 Spam — promotional noise
• 🏠 Out of Office — automated replies

Every email (new and historical) is automatically classified before indexing — helping you focus on what needs your attention.

🔔 Smart Notifications

Stay informed about important emails without constant checking.

Notification triggers:

• Interested emails → Instant Slack DM
• Meeting Booked → Custom webhook automation (optional)

Gracefully handles missing webhooks without crashing — just logs a friendly warning.

💬 AI-Suggested Replies (RAG-Based)

Context-aware reply suggestions powered by semantic search and LLMs.

How it works:

1. Query arrives with email subject + body
2. Pinecone retrieves top 3 semantically similar knowledge snippets
3. Gemini generates 3 contextual reply options
4. Choose, customize, and send

Knowledge base includes:

• Product information and features
• Common objection handling
• Meeting scheduling templates
• Professional response patterns

🎨 Modern Frontend (Next.js 15 + React 19)

A clean, responsive interface designed for productivity.

Features:

• Email list with smart pagination
• Multi-filter support (account, folder, category)
• Real-time full-text search
• Category statistics and chips
• AI reply modal with one-click insertion
• Mobile-responsive design

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        IMAP Servers                          │
│              (Gmail, Outlook, Custom IMAP)                   │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
         ┌──────────────────────┐
         │   IMAP Sync Service   │
         │   (ImapFlow + IDLE)   │
         └──────────┬────────────┘
                    │
                    ▼
         ┌──────────────────────┐
         │  Email Parser         │
         │  (mailparser)         │
         └──────────┬────────────┘
                    │
                    ▼
         ┌──────────────────────┐
         │  AI Categorization    │
         │  (Gemini 2.5 Flash)   │
         └──────────┬────────────┘
                    │
         ┌──────────┴──────────┐
         ▼                     ▼
┌─────────────────┐   ┌──────────────────┐
│  Elasticsearch  │   │  Notifications   │
│  (Indexing)     │   │  (Slack/Webhook) │
└────────┬────────┘   └──────────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│           REST API (Express)             │
│  /get-all-email  /search  /suggest-replies│
└────────┬────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│        Frontend (Next.js 15)             │
│    Email Dashboard + Reply Assistant     │
└─────────────────────────────────────────┘
         │
         ▼ (RAG Flow)
┌─────────────────────────────────────────┐
│  Pinecone Vector DB → Gemini → Replies  │
└─────────────────────────────────────────┘

Backend Stack

• Runtime: Node.js + TypeScript
• Framework: Express
• Email Sync: ImapFlow (IMAP IDLE)
• Search & Storage: Elasticsearch 8.x
• AI: Google Gemini API
• Vector DB: Pinecone
• Parsing: mailparser

Frontend Stack

• Framework: Next.js 15 (App Router)
• UI: React 19
• Styling: Tailwind CSS
• Icons: Lucide React
• State: React Hooks

---

📡 API Reference

Email Retrieval

GET /get-all-email

Fetch all emails with pagination.

Query Parameters:

• page (number, optional) — Default: 1

Response: Array of email objects (100 per page)

---

GET /get-filtered-emails

Filter emails by specific criteria.

Query Parameters:

• accountId (string, optional) — Filter by email account
• folder (string, optional) — inbox, sent, spam, or all
• category (string, optional) — AI-assigned category
• page (number, optional) — Default: 1

Response: Filtered array of email objects

---

GET /search

Full-text search across all indexed emails.

Query Parameters:

• q (string, required) — Search query

Response: Matching email objects sorted by relevance

---

AI Features

GET /suggest-replies

Generate contextual reply suggestions using RAG.

Query Parameters:

• subject (string, required) — Email subject line
• body_text (string, required) — Email body content

Response:

{
  "replies": [
    "Thanks for reaching out! I'd be happy to schedule a call...",
    "I appreciate your interest. Here's some information...",
    "Let me check my calendar and get back to you..."
  ]
}

---

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm
• Docker & Docker Compose (for Elasticsearch)
• Gmail/Outlook accounts with app-specific passwords
• API keys: Google Gemini, Pinecone (optional: Slack webhook)

Backend Setup

1. Clone and install dependencies

   cd backend
   npm install

2. Start Elasticsearch

   cd elastic-search
   docker compose up -d

3. Configure environment variables

   Create backend/.env:

   PORT=4000
   
   # Elasticsearch
   ES_PORT=http://localhost:9200
   ES_INDEX=reachinbox_emails
   
   # Email Accounts (add more as needed)
   USER_EMAIL_1=your-email@gmail.com
   USER_PASSWORD_1=your-app-specific-password
   USER_EMAIL_2=another-email@gmail.com
   USER_PASSWORD_2=another-app-password
   
   # AI Services
   GEMINI_API_KEY=your_gemini_api_key
   PINECONE_API_KEY=your_pinecone_key
   PINECONE_INDEX_NAME=reach-inbox-kb
   PINECONE_HOST=your-pinecone-host.io
   
   # Notifications (optional)
   SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
   AUTOMATION_WEBHOOK_URL=https://your-automation-endpoint.com

4. (Optional) Populate Pinecone knowledge base

   In server.ts, uncomment:

   await run(); // Populate Pinecone with knowledge base

   Run once, then re-comment to avoid duplicates.

5. Start the backend

   npm run dev

   Backend runs on http://localhost:4000

Frontend Setup

1. Install dependencies

   cd frontend
   npm install

2. Configure environment

   Create frontend/.env.local:

   NEXT_PUBLIC_API_URL=http://localhost:4000

3. Start the development server

   npm run dev

   Open http://localhost:3000 in your browser

---

📊 Email Object Schema

interface Email {
  messageId: string;
  subject: string;
  from: { address: string; name?: string };
  to: Array<{ address: string; name?: string }>;
  cc?: Array<{ address: string; name?: string }>;
  date: string; // ISO 8601
  body_text: string;
  body_html?: string;
  folder: 'inbox' | 'sent' | 'spam';
  accountId: string;
  category?: 'Interested' | 'Meeting Booked' | 'Not Interested' | 'Spam' | 'Out of Office';
  hasAttachments?: boolean;
  importance?: 'low' | 'normal' | 'high';
}

---

🛠️ Technical Decisions & Trade-offs

Why IMAP IDLE over Polling?

• Real-time updates — emails appear instantly
• Resource efficient — no wasteful periodic checks
• Scalable — works with any IMAP-compliant provider

Why Elasticsearch?

• Sub-second search across thousands of emails
• Flexible querying — full-text, filters, pagination
• Production-ready — battle-tested at scale

Why Gemini over OpenAI?

• Cost-effective — Flash Lite model is fast and cheap
• JSON mode — structured output for reliable categorization
• Generous rate limits for personal projects

Why Pinecone for RAG?

• Managed service — no infrastructure overhead
• Fast semantic search — <100ms query latency
• Simple API — easy to integrate and maintain

Current Simplifications

• App passwords instead of OAuth2 (faster initial setup)
• Single INBOX folder per account (expandable to all folders)
• Basic error handling — no retry queues or dead-letter mechanisms yet
• No threading — emails treated independently

---

🔮 Roadmap & Future Enhancements

Authentication & Security

• OAuth2 integration for Gmail/Outlook
• Token refresh and rotation
• Rate limiting and request throttling
• Email encryption for sensitive content

Performance & Scalability

• Bulk indexing optimization (batch writes)
• Redis caching layer for frequently accessed emails
• Background job queue (Bull/BullMQ)
• Horizontal scaling with load balancing

Features

• Email threading — group conversations intelligently
• Send email — compose and send directly from UI
• Attachment handling — preview, download, search
• Email templates — save and reuse common replies
• Read/unread status — sync with mail server
• Multi-folder support — beyond inbox (drafts, archives)
• Smart filters — auto-apply rules to incoming emails
• Analytics dashboard — response times, category distribution

Real-Time & Collaboration

• WebSocket push updates for live UI sync
• Team inbox mode (shared accounts)
• Collaborative tagging and notes
• Slack bot integration for quick actions

AI & Automation

• Sentiment analysis for customer emails
• Auto-reply for common queries
• Priority scoring based on sender history
• Smart scheduling assistant (calendar integration)
• Custom AI categorization rules (user-defined)

---

🤝 Contributing

This is a personal learning project, but suggestions and feedback are welcome!

If you'd like to contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 License

This project is open source and available under the MIT License.

---

🙏 Acknowledgments

Built with:

• ImapFlow — Modern IMAP client
• Elasticsearch — Search and analytics engine
• Google Gemini — AI categorization and reply generation
• Pinecone — Vector database for semantic search
• Next.js — React framework
• Tailwind CSS — Utility-first CSS

---

💡 Why I Built This

Email shouldn't feel like a chore. After years of switching between tabs, missing important messages, and rewriting the same responses, I wanted something better — a single dashboard that's smart enough to know what matters and helpful enough to draft replies for me.

Onebox started as a weekend experiment and evolved into my daily email driver. It's not perfect, but it's mine — and it makes managing multiple inboxes actually enjoyable.

If you're drowning in email or just curious about building real-time data pipelines with AI, I hope this project inspires you to build something cool too.

---

Questions or feedback? Open an issue or reach out — I'd love to hear from you! 📧