Outbox 📧

Real-time multi-IMAP email aggregator with Elasticsearch search, Groq AI categorization, and Slack/webhook automation.

Outbox is a powerful email management system that consolidates multiple email accounts, provides intelligent search capabilities, and automates email workflows using AI-powered categorization.

✨ Features

• Multi-Account Support: Connect and manage multiple email accounts through IMAP
• Real-time Synchronization: Automatic email fetching and updates across all connected accounts
• Elasticsearch Integration: Lightning-fast full-text search across all your emails
• AI-Powered Categorization: Automatic email classification using Groq AI and Google Vertex AI
• Smart Automation: Trigger webhooks and Slack notifications based on email content
• Modern UI: Clean, responsive React frontend for easy email management
• RESTful API: Full-featured backend API for integration with other tools

🏗️ Architecture

Backend Stack

• Node.js + Express: RESTful API server
• ImapFlow: IMAP client for email synchronization
• Elasticsearch: Search and indexing engine
• Groq SDK: AI-powered email categorization
• Google Vertex AI: Advanced AI capabilities
• Nodemailer: Email sending functionality
• OpenAI SDK: Additional AI integration

Frontend Stack

• React 19: Modern UI framework
• React Router: Client-side routing
• Vite: Fast build tool and dev server
• Tailwind CSS: Utility-first styling

🚀 Getting Started

Prerequisites

• Node.js (v16 or higher)
• Docker & Docker Compose
• Elasticsearch instance
• API keys for:
  • Groq AI
  • Google Vertex AI (optional)
  • OpenAI (optional)

Installation

1. Clone the repository

   git clone https://github.com/farish-jamal/outbox.git
   cd outbox

2. Set up the backend

   cd backend
   npm install

3. Configure environment variables

   Create a .env file in the backend directory:

   # Email Configuration
   IMAP_HOST=imap.gmail.com
   IMAP_PORT=993
   IMAP_USER=your-email@gmail.com
   IMAP_PASSWORD=your-app-password
   
   # Elasticsearch
   ELASTICSEARCH_URL=http://localhost:9200
   ELASTICSEARCH_INDEX=emails
   
   # AI APIs
   GROQ_API_KEY=your-groq-api-key
   OPENAI_API_KEY=your-openai-api-key
   GOOGLE_APPLICATION_CREDENTIALS=path/to/credentials.json
   
   # Automation
   SLACK_WEBHOOK_URL=your-slack-webhook-url
   WEBHOOK_URL=your-custom-webhook-url
   
   # Server
   PORT=3000

4. Set up the frontend

   cd frontend
   npm install

5. Start Elasticsearch (using Docker)

   docker-compose up -d

Running the Application

Development Mode:

Backend:

cd backend
npm run dev

Frontend:

cd frontend
npm run dev

Connecting Email Accounts

1. Navigate to the settings page in the UI
2. Add your email account credentials (IMAP)
3. The system will automatically start syncing emails

Searching Emails

Use the search bar to perform full-text searches across all your emails. Elasticsearch powers instant results with support for:

• Subject and body text
• Sender and recipient filtering
• Date ranges
• Attachment searches

AI Categorization

Emails are automatically categorized into:

• Primary/Important
• Social
• Promotions
• Updates
• Spam

Configure custom categories and rules through the API or settings UI.

Automation Rules

Set up automation rules to:

• Send Slack notifications for important emails
• Trigger webhooks for specific senders or keywords
• Auto-categorize based on content patterns

🔌 API Endpoints

GET    /api/emails              # List all emails
GET    /api/emails/:id          # Get email by ID
POST   /api/emails/search       # Search emails
POST   /api/accounts            # Add email account
DELETE /api/accounts/:id        # Remove email account
POST   /api/categories          # Create category
GET    /api/categories          # List categories
POST   /api/automation/rules    # Create automation rule

🐳 Docker Support

The project includes a docker-compose.yml file for easy deployment:

docker-compose up -d

This starts:

• Elasticsearch cluster
• Kibana (optional, for debugging)

---

Note: This project is in active development. Features and documentation are subject to change.