MailMate

Author: Amaan Haider

AI-powered webmail with Gmail + an assistant that controls the UI.

MailMate is a webmail app that uses the Gmail API. The built-in AI assistant doesn't just answer questions—it opens compose, fills fields, filters the inbox, opens emails, drafts replies, forwards as-is, and sends when you ask.

Requirements: REQUIREMENTS.md.

---

Features

Area	What you get
Mail	Inbox, Sent, read email, Compose & send (Gmail API), attachments
Categories	Gmail-style tabs: All, Primary, Social, Promotions, Updates, Forums
Filters	Keyword, unread only, date range (UI + assistant); uses Gmail search
Pagination	Previous / Next with "Showing X–Y"
AI assistant	Open compose · Fill to/subject/body · Filter inbox · Switch category · Open email/sent by position · Reply · Forward (raw, format preserved) · Mark as read · Send · Understand/enhance draft · Rich preview cards
Human-in-the-loop	Confirmation before send and forward
Sync	Inbox refreshes on tab focus and every 30s (no manual refresh)
UI	Dark theme, resizable assistant panel

---

Local setup

Follow these steps in order. You need two things: a Cerebras API key and Google OAuth credentials.

Step 0: Install Node.js

If you don't have Node.js:

1. Go to nodejs.org
2. Download the LTS version
3. Run the installer
4. Open a terminal and type node -v — you should see a version (e.g. v20.x.x)

Step 1: Get a Cerebras API key

1. Go to cloud.cerebras.ai
2. Sign up or log in
3. Find API Keys in the dashboard
4. Click Create new key
5. Copy the key (starts with csk-) and save it — you'll paste it into .env later

Step 2: Get Google OAuth credentials

2a. Create a Google Cloud project

1. Go to console.cloud.google.com
2. Click the project dropdown at the top → New Project
3. Name it (e.g. "MailMate") → Create

2b. Enable Gmail API

1. Left sidebar → APIs & Services → Library
2. Search Gmail API → click it → Enable

2c. Create OAuth credentials

1. APIs & Services → Credentials → + Create Credentials → OAuth client ID
2. If asked to configure consent screen: choose External → fill App name and your email → add your email as Test user → Save
3. Back to Create OAuth client ID:
   • Application type: Web application
   • Name: e.g. "MailMate"
   • Authorized JavaScript origins → Add URI → http://localhost:5173
   • Authorized redirect URIs → Add URI → http://localhost:5001/api/auth/google/callback
   • Create
4. Copy the Client ID and Client Secret — you'll need them for .env

Step 3: Install dependencies

cd server
npm install
cd ../client
npm install

Step 4: Configure the server

1. Copy the example env file:

   cd server
   cp .env.example .env

2. Open server/.env in a text editor and fill in:

   Variable	Where to get it
   CEREBRAS_API_KEY	Step 1
   GOOGLE_CLIENT_ID	Step 2c
   GOOGLE_CLIENT_SECRET	Step 2c
   GOOGLE_REDIRECT_URI	Keep as-is
   FRONTEND_URL	Keep as-is
   SESSION_SECRET	Any string (e.g. my-secret)

3. Save the file

Step 5: Run the app

Terminal 1 — Server:

cd server
npm run dev

Wait for "Server running on port 5001".

Terminal 2 — Client:

cd client
npm run dev

Wait for "Local: http://localhost:5173".

Step 6: Try it

1. Open http://localhost:5173 in your browser
2. Click Sign in with Google and approve
3. Go to Inbox and open the assistant (sidebar)
4. Try: "Show unread from this week" · "Open the first email" · "Reply saying I'll send an update tomorrow" · "Send"

Troubleshooting

• Redirect URI mismatch — Ensure http://localhost:5001/api/auth/google/callback is exactly in Google Console (no trailing slash).
• CEREBRAS_API_KEY not set — Save .env in server/ and restart the server.
• Cannot GET /api/... — Make sure server runs on 5001 and client on 5173.

---

Deployment

→ DEPLOYMENT.md

---

Project structure

Folder	Role
client/	React + Vite UI, CopilotKit assistant tools
server/	Express, Gmail API (OAuth), CopilotKit runtime (Cerebras)