MailMind is an AI-powered email client that combines intelligent email organization with a conversational assistant. It lets you triage faster, ask natural-language questions over your mailbox (RAG), and draft/send emails with AI assistance.
- Smart email management: Inbox, threads, search, and compose/reply flows
- AI-powered chat (RAG): Ask questions and get citation-backed answers
- Real-time sync: Incremental sync via Aurinko; background workers keep data fresh
- Modern UI: Next.js App Router, shadcn/Radix UI, Tailwind CSS, streaming chat
- Framework: Next.js 15 with TypeScript (App Router)
- UI: shadcn/ui + Radix UI primitives
- Styling: Tailwind CSS
- Data fetching: SWR
- Deployment: Vercel
- Framework: FastAPI (Python)
- Database: PostgreSQL (e.g., Neon)
- ORM: SQLAlchemy 2.0 + Alembic
- Auth: Cookie-based auth (JWT token in cookie), CORS configured for Vercel
- Workers/Queue: ARQ + Redis for background sync/indexing
- AI/RAG: LangChain/LangGraph + Chroma vector store
- Email Integration: Aurinko API
- Deployment: Cloud Run
- Package manager: npm (frontend), pip (backend)
- Code quality: ESLint, TypeScript
- Node.js 18+
- Python 3.10+
- PostgreSQL database (or Neon account)
- Redis (for ARQ workers)
- Aurinko API credentials
- OpenAI API key (optional, for AI features)
-
Navigate to backend and create venv
cd backend python -m venv venv # Windows venv\Scripts\activate # macOS/Linux # source venv/bin/activate
-
Install dependencies
pip install -r requirement.txt
-
Environment configuration
Create a new
.envfile based on the.env.examplefile. -
Migrations and init
alembic upgrade head # optional # python -m app.init_db
-
Start API (dev)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
-
Navigate to frontend
cd frontend -
Install dependencies
npm install
-
Environment configuration
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000 NEXT_PUBLIC_AURINKO_CLIENT_ID=your_aurinko_client_id
-
Start dev server
npm run dev
The application will be available at:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API docs: http://localhost:8000/docs
mailmind/
├── backend/ # FastAPI backend
│ ├── app/
│ │ ├── api/ # API routes
│ │ │ └── routes/ # Route handlers
│ │ ├── core/ # Config
│ │ ├── services/ # Business logic (RAG, etc.)
│ │ ├── models.py # SQLAlchemy models
│ │ ├── crud.py # DB operations
│ │ └── main.py # FastAPI app
│ ├── alembic/ # DB migrations
│ └── requirement.txt # Python deps
├── frontend/ # Next.js frontend
│ ├── src/
│ │ ├── app/ # App Router
│ │ ├── components/ # UI components
│ │ ├── hooks/ # React hooks
│ │ └── lib/ # Utilities
│ └── package.json # Node deps
└── public/ # Static assets
Visit http://localhost:8000/docs for the FastAPI OpenAPI UI.
POST /auth/login– User authenticationGET /mail/threads– Fetch paginated threadsPOST /chat/stream– Streaming chat over emails (RAG)POST /mail/thread/{id}/reply– Send a reply
MailMind includes a RAG service for question answering, summarization, and semantic retrieval over your email history. Answers include citations back to source messages.
- Cookie-based auth (JWT), CORS restricted to your frontend
- Environment-based configuration
cd backend
alembic revision --autogenerate -m "Description of changes"
alembic upgrade headThis project is licensed under the terms specified in the LICENSE file.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
Built with ❤️ using FastAPI, Next.js, and modern web technologies.