Email Agent (Multi‑User AI Email Copilot)

Gmail + Google Calendar powered email workflow app with:

• Inbox Copilot: global assistant with tool calling + RAG (semantic search)
• Conversations: browse email threads with filters + pagination
• Priority Inbox: triage labels + priority score + streaming run progress
• Suggested Schedule: auto-plan follow‑ups onto your calendar (week grid) and confirm to create events

Demo (personal deployment)
Live web: https://app.mail-agents.net/
This is a personal deployment for demo purposes. For real email accounts and sensitive data, you are strongly encouraged to self‑host this project with your own Google account and database.

UI Pages (Frontend Names)

• Dashboard (/dashboard): overview + quick actions + Suggested Schedule
• Conversations (/threads): browse email conversations
• Priority Inbox (/triage): view priority results + run “Update Priorities”
• Thread Detail (/thread/:threadId): full thread + Thread Chat (draft replies, save to Gmail)
• Inbox Copilot: slide‑in panel from Dashboard, with session history

Key Features

• Multi‑account support: switch between multiple Gmail accounts
• Priority Inbox (Triage):
  • Labels: NEEDS_REPLY, FYI, ARCHIVE, SPAM_LIKE
  • Priority score (0–1), sorted by importance
  • Time filters (Today / 3 / 5 / 7 / 30 days)
  • Pending triage indicator + cooldown based refresh
  • Streaming progress (SSE) and shared progress state across Dashboard + /triage
• Inbox Copilot (Assist Chat):
  • Saves chat sessions to DB (assist_chat_sessions)
  • Tool calling: triage query, RAG search, thread retrieval, draft generation
  • Thread IDs in answers become clickable links in the UI
  • “📖 How to Use This App” quick action
• Knowledge Base (RAG):
  • Local embeddings using all-MiniLM-L6-v2 (SentenceTransformers)
  • Stored in Postgres + pgvector (email_embeddings)
  • Background “silent sync & embed” task with cooldown to avoid repeated heavy work
• Suggested Schedule (Calendar):
  • Generates follow‑up blocks from Priority Inbox and places them into free calendar time
  • Week grid view (drag / resize / select) then Confirm & Create to write events to Google Calendar

⚠️ Security Notice: Self-Hosting Recommended

Important: This application processes sensitive email data, including message content, metadata, and calendar information. To protect your privacy and prevent data leakage:

• Self-host this application on your own infrastructure (AWS, GCP, Azure, or your own servers)
• Do not use third-party hosted instances unless you fully trust the operator
• Review and understand what data is stored and how it's processed
• Use strong authentication and keep your deployment secure
• Regularly update dependencies and monitor security advisories

By self-hosting, you maintain full control over:

• Email data storage and processing
• Database access and encryption
• API keys and OAuth tokens
• Network security and access controls

See deployment guides:

• Backend: See backend/README.md for production deployment steps
• Frontend: See DEPLOY_FRONTEND.md for S3 + CloudFront deployment

Project Structure

Email-Agent/
├── backend/                         # FastAPI + Python
│   ├── app/
│   │   ├── agents/                  # Assist/Thread/Triage agents + tools
│   │   ├── routes/                  # FastAPI routes
│   │   ├── services/                # Gmail/Calendar/RAG/Embedding/background tasks
│   │   ├── models.py                # SQLAlchemy models
│   │   └── database.py              # DB engine/session
│   ├── init_database.py             # Create tables + add missing indexes (non-destructive)
│   ├── main.py                      # FastAPI entry
│   └── requirements.txt
├── frontend/                        # React
│   ├── src/
│   │   ├── components/
│   │   └── pages/
│   └── package.json
└── client_secret.json               # Google OAuth credentials (gitignored)

Setup (Local Development)

Prerequisites

• Python 3.10+
• Node.js 18+
• PostgreSQL 15+
• Google Cloud OAuth credentials (Gmail + Calendar enabled)

1) Backend (FastAPI)

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Create backend/.env (example):

PORT=5001
DEBUG=True
FRONTEND_URL=http://localhost:3000
CORS_ORIGINS=http://localhost:3000
SESSION_SECRET=change-me-in-production

# Google OAuth
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=http://localhost:5001/api/auth/google/callback

# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=email_agent
DATABASE_USER=postgres
DATABASE_PASSWORD=...

# LLM (choose one)
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=...
# or
# LLM_PROVIDER=openai
# OPENAI_API_KEY=...

Initialize DB (creates tables, enables pgvector, and adds missing indexes without wiping data):

python init_database.py

Run backend:

python main.py

Backend:

• API base: http://localhost:5001/api
• Docs: http://localhost:5001/docs

2) Frontend (React)

cd frontend
npm install
npm start

Optional frontend/.env:

REACT_APP_API_URL=http://localhost:5001/api

Frontend:

• http://localhost:3000

Google OAuth Setup

In Google Cloud Console:

• Enable Gmail API + Google Calendar API
• Create OAuth “Web application”
• Add redirect URI: http://localhost:5001/api/auth/google/callback

Scopes used (see backend/app/config.py):

• openid
• https://www.googleapis.com/auth/userinfo.email
• https://www.googleapis.com/auth/userinfo.profile
• https://www.googleapis.com/auth/gmail.readonly
• https://www.googleapis.com/auth/gmail.compose
• https://www.googleapis.com/auth/calendar.events

Main API Endpoints (Backend)

Auth

• GET /api/auth/google/login
• GET /api/auth/google/callback
• GET /api/auth/me
• POST /api/auth/logout

Gmail

• GET /api/gmail/threads (supports pagination via page_token)
• GET /api/gmail/threads/{thread_id}

Priority Inbox (Triage)

• POST /api/triage/run (SSE stream)
• GET /api/triage/results (supports days, limit, skip)
• GET /api/triage/stats (pending count)

Thread Chat

• POST /api/thread-chat/ask (SSE stream)
• POST /api/thread-chat/save-draft (saves to Gmail; auto-detects correct account)

Inbox Copilot (Assist Chat)

• POST /api/assist-chat/ask (SSE stream)
• GET /api/assist-chat/sessions
• GET /api/assist-chat/sessions/{session_id}
• DELETE /api/assist-chat/sessions/{session_id}

Suggested Schedule (Calendar)

• GET /api/calendar/suggestions
• POST /api/calendar/confirm

Production Notes

Security Best Practices:

• Self-host on your own infrastructure to maintain control over sensitive email data
• Set DEBUG=False in production
• Use a strong, randomly generated SESSION_SECRET
• Set FRONTEND_URL + CORS_ORIGINS to your deployed frontend origin(s)
• Update GOOGLE_REDIRECT_URI to your deployed backend callback URL and update OAuth redirect URIs in Google Cloud
• Use a managed Postgres (e.g. Cloud SQL / RDS) with encryption at rest and ensure pgvector is available
• Enable HTTPS in production (required for OAuth)
• Restrict database access to only the application server
• Regularly rotate OAuth tokens and API keys
• Monitor access logs for suspicious activity
• Keep dependencies updated to patch security vulnerabilities

Contact

• Author: Haoji Bian
• Email: haoji.bian@mail-agents.net
• Website: https://mail-agents.net
• GitHub: https://github.com/Haoj1/Email-Agent

License

This project is licensed under the MIT License.
Copyright (c) 2026 Haoji Bian