MAILSTROM

MAILSTROM is an autonomous, conversational email outreach desktop application. It acts as a smart "JARVIS-like" agent that can ingest raw text, extract contacts, draft personalized emails, and send them at scheduled intervals.

Architecture

• Backend: Python (FastAPI). Handles SQLite database, APScheduler for interval sending, and AI generation (Gemini / Ollama).
• Frontend: HTML/CSS/JS (Vanilla).
• Native Wrapper: Tauri (Rust). Packages the frontend into a lightweight desktop application window.

Prerequisites

• Python 3.10+
• Node.js & npm (for Tauri)
• Rust (Cargo)
• Ollama (For local email classification)

Quick Start

MAILSTROM has been upgraded to a unified native desktop app using Tauri! The desktop application automatically starts and stops the internal Python server for you.

1. Install Python dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

2. Install Node dependencies (for the Tauri desktop shell):

   npm install

3. Run the desktop app:

   npm run dev

   (This opens the native window and automatically spins up the internal backend!)

Setup

1. Ollama Setup: MAILSTROM uses Ollama for local email classification. Ensure Ollama is running and download the model:

   ollama run qwen2.5:7b-instruct-q4_K_M

2. Gmail OAuth 2.0 Credentials:

   • Go to the Google Cloud Console.

   • Enable the Gmail API.

   • Create an OAuth 2.0 Client ID (Desktop App).

   • Download the JSON file and save it in the project root as credentials/credentials.json.

   • Run the auth script to log in for the first time:

     PYTHONPATH=. .venv/bin/python gmail/auth.py

     This will generate credentials/token.json.

3. Node Modules (Tauri):

   npm install

Running the Application

MAILSTROM runs as a native desktop application, communicating with a local FastAPI backend.

1. Start the Backend API:

   PYTHONPATH=. .venv/bin/uvicorn api.main:app --host 0.0.0.0 --port 8000

   The backend must be running for the frontend to function.

2. Start the Desktop App: In a new terminal window:

   npx tauri dev

3. Configure API Key in UI:

   • Once the app launches, click on the Settings tab in the sidebar.
   • Enter your Gemini API Key and hit Save. The backend will instantly use it for drafting.

This will launch the MAILSTROM dashboard window where you can ingest contacts and schedule drafts!