AI Mail App

This project is a mail web app with an AI assistant.

The assistant can:

• open screens (Inbox, Sent, Compose)
• fill email form fields from natural language
• apply filters (sender, keyword, read/unread, date)
• open specific emails

---

Run With Docker (Recommended)

If you want to run everything with one command, use Docker.

1) Make sure Docker is installed

Check:

docker --version
docker compose version

2) Configure backend environment

Create Backend/.env (or update existing) before starting containers.

At minimum:

PORT=8080
CORS_ORIGIN=http://localhost:5173
USE_GMAIL_PROVIDER=false

If using Gmail, also set:

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GOOGLE_REDIRECT_URI
• GOOGLE_PUBSUB_TOPIC_NAME
• GOOGLE_WATCH_LABEL_IDS

3) Build and start both services

From project root:

docker compose up --build -d

4) Open app

• Frontend: http://localhost:5173
• Backend health: http://localhost:8080/health

5) Stop services

docker compose down

Optional: View logs

docker compose logs -f

---

1) Open app in browser

Go to:

http://localhost:5173

---

Use Real Gmail (Production-Like Mode)

If you want real emails (Inbox/Sent from Gmail API), do this once.

Step A: Create Google OAuth credentials

In Google Cloud Console:

1. Create/select a project
2. Enable Gmail API
3. Create OAuth Client ID (Web Application)
4. Add redirect URI:
   • http://localhost:8080/auth/google/callback
   • or your ngrok URL callback (if using ngrok), for example: https://YOUR-NGROK-DOMAIN/auth/google/callback

Step B: Configure backend .env

Create/edit file: Backend/.env

Use this template:

PORT=8080
CORS_ORIGIN=http://localhost:5173

USE_GMAIL_PROVIDER=true
GOOGLE_CLIENT_ID=YOUR_CLIENT_ID
GOOGLE_CLIENT_SECRET=YOUR_CLIENT_SECRET
GOOGLE_REDIRECT_URI=http://localhost:8080/auth/google/callback

GOOGLE_PUBSUB_TOPIC_NAME=projects/<project-id>/topics/<topic-name>
GOOGLE_WATCH_LABEL_IDS=INBOX

If you use ngrok, set GOOGLE_REDIRECT_URI to your ngrok callback URL exactly.

Step C: Start backend and frontend

Same commands as before:

cd Backend
npm run dev

cd /home/bast/Work/Code/Test/Frontend
npm run dev

Step D: Connect Gmail

Open this in browser:

http://localhost:8080/auth/google/start

After success, the page should say: "Google authentication successful. You can close this tab."

Step E: Verify connection

Open:

http://localhost:8080/auth/status

You should see:

• "provider":"gmail"
• "authenticated": true

---

Real-Time Sync Notes

The app supports server push via SSE and Gmail webhook route.

For full Gmail push behavior, Pub/Sub + webhook setup is needed:

• webhook endpoint: /sync/gmail/webhook
• frontend stream endpoint: /sync/events

If webhook is not configured yet, core app still works; new mail push from Gmail may be limited.

---

How to Use the Assistant (Examples)

Try these in the assistant panel:

• Send an email to john@example.com with subject Meeting Tomorrow and body Let's meet at 3pm
• Show me emails from the last 10 days
• Show me emails from the last 1 day
• Find the email from Sarah about project update
• Open the latest email from David
• Reply to this
• Forward this
• Show only unread emails from this week
• Show read emails
• from date 2026-04-01 to date 2026-04-20

---

If Something Is Not Working

1) Frontend cannot reach backend

• Make sure backend is running on port 8080
• Check: http://localhost:8080/health

2) Google OAuth error: redirect_uri_mismatch

• Ensure Google Console redirect URI exactly matches GOOGLE_REDIRECT_URI
• Protocol, domain, port, and path must be exact

3) Error: "Google tokens missing. Authenticate first at /auth/google/start."

• You enabled Gmail mode but did not complete OAuth yet
• Open /auth/google/start once

4) "Access blocked: app has not completed Google verification"

• Set OAuth consent screen to Testing
• Add your Gmail account as a Test user

5) Changes not visible

• Restart backend and frontend servers
• Refresh browser

---