Smart Email Automation Assistant

A full-stack email assistant that connects to Gmail, summarizes recent emails with Google Gemini, classifies them, extracts useful fields, drafts replies, and saves AI results in SQLite.

The app is approval-first by design: it never sends an email automatically. It can create a Gmail draft, and a separate user click is required before sending.

Tech Stack

• Frontend: React with Vite
• Backend: Python FastAPI
• Database: SQLite
• APIs: Gmail API and Google Gemini API
• Docker: Not used

Complete Folder Structure

smart-email-automation-assistant/
  README.md
  .gitignore
  backend/
    .env.example
    requirements.txt
    app/
      __init__.py
      main.py
      api/
        __init__.py
        auth.py
        emails.py
      core/
        __init__.py
        config.py
        security.py
      db/
        __init__.py
        init_db.py
        session.py
      models/
        __init__.py
        email_record.py
        oauth_token.py
      schemas/
        __init__.py
        auth.py
        email.py
      services/
        __init__.py
        gemini_service.py
        gmail_service.py
        mock_data.py
        token_store.py
      sample_data/
        emails.json
  frontend/
    .env.example
    index.html
    package.json
    src/
      App.jsx
      main.jsx
      components/
        EmailDetail.jsx
        EmailList.jsx
        Header.jsx
      services/
        api.js
      styles/
        app.css

What It Does

• Gmail OAuth login
• Fetches recent Gmail emails
• Shows emails in a clean dashboard
• Uses Gemini to summarize emails
• Classifies each email as Job, Internship, Meeting, Important, Promotion, Spam, or Personal
• Extracts date, time, company name, meeting link, deadline, and required documents
• Generates an AI reply draft
• Requires user approval before sending
• Saves summaries, categories, extracted fields, and drafts in SQLite
• Includes sample test emails when Gmail setup is not ready

Backend Setup

Open a terminal in smart-email-automation-assistant/backend.

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env

Generate a token encryption key:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Paste the generated value into TOKEN_ENCRYPTION_KEY in backend/.env.

Start in mock mode first:

uvicorn app.main:app --reload --port 8001

Backend URL:

http://localhost:8001

API docs:

http://localhost:8001/docs

If port 8001 is already busy, use another port and update both backend/.env and frontend/.env. Example:

uvicorn app.main:app --reload --port 8002

BACKEND_URL=http://localhost:8002
VITE_API_BASE_URL=http://localhost:8002/api

Frontend Setup

Open a second terminal in smart-email-automation-assistant/frontend.

npm install
copy .env.example .env
npm run dev

Frontend URL:

http://localhost:5173

Run With Sample Test Data

The app starts with:

USE_MOCK_DATA=true

With mock mode on:

• Gmail OAuth is skipped.
• Gemini calls are skipped.
• Emails are loaded from backend/app/sample_data/emails.json.
• Approve and Send records approval only. No real email is sent.

This lets you test the full dashboard safely before creating Google credentials.

Gmail API Setup

1. Go to Google Cloud Console.
2. Create or select a project.
3. Enable the Gmail API.
4. Configure the OAuth consent screen.
5. Create OAuth Client ID credentials for a web application.
6. Add this authorized redirect URI:

http://localhost:8001/api/auth/google/callback

7. Copy the client ID and client secret into backend/.env.
8. Set:

USE_MOCK_DATA=false
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Then restart the FastAPI server and click Connect Gmail in the frontend.

Gemini API Setup

1. Go to Google AI Studio.
2. Create an API key.
3. Add it to backend/.env:

GEMINI_API_KEY=your-gemini-api-key
GEMINI_MODEL=gemini-2.5-flash

When USE_MOCK_DATA=false and GEMINI_API_KEY is present, the backend uses Gemini for analysis and reply drafts through the Gemini REST API.

Security Notes

• Emails are never sent automatically.
• POST /api/emails/{email_id}/draft only generates text and creates a Gmail draft.
• POST /api/emails/{email_id}/approve-send sends only after the user clicks Approve and Send.
• OAuth tokens are encrypted before saving in SQLite.
• Keep .env out of git.
• Use a strong TOKEN_ENCRYPTION_KEY and do not rotate it casually, because old encrypted tokens require the same key.
• For production, add real user accounts, HTTPS, secure cookies, CSRF protection, audit logs, and managed secret storage.

Useful API Endpoints

GET  /api/health
GET  /api/auth/status
GET  /api/auth/google/login
POST /api/auth/disconnect
POST /api/emails/sync
GET  /api/emails
GET  /api/emails/{email_id}
POST /api/emails/{email_id}/draft
POST /api/emails/{email_id}/approve-send

Beginner Notes

• Backend comments explain the important functions and safety decisions.
• Frontend state lives in frontend/src/App.jsx.
• API calls are centralized in frontend/src/services/api.js.
• SQLite tables are created automatically when FastAPI starts.
• Delete backend/smart_email_assistant.db if you want a fresh local database.