ConverseMail

What if your inbox felt like a messaging app? ConverseMail turns your Gmail threads into a clean, real-time chat interface — so you can read and reply to emails just like you would on WhatsApp.

How it works

• Connect your Gmail account via OAuth2
• Only contacts listed in ALLOWED_CONTACTS appear in the sidebar — no inbox scanning
• Click a contact to see all threads, click a thread to open the chat
• Each email is rendered as a chat bubble (sent/received)
• Reply directly from the chat UI — replies stay threaded properly in Gmail
• Polls for new messages every 5s (active thread) / 15s (contacts & thread list)
• Columns are resizable (drag the handles between them)

Setup

1. Google Cloud Console

1. Go to https://console.cloud.google.com/apis/credentials
2. Create an OAuth 2.0 Client ID (Web application)
3. Add http://localhost:3001/auth/google/callback to authorized redirect URIs
4. Enable the Gmail API: https://console.cloud.google.com/apis/library/gmail.googleapis.com

2. Backend

cd backend
cp .env.example .env

Edit .env with your Google OAuth credentials, then generate secure keys:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Put the output as SESSION_SECRET and ENCRYPTION_KEY.

ALLOWED_CONTACTS is required — set it to the emails you want to chat with:

ALLOWED_CONTACTS=friend@example.com,colleague@example.com

npm install
npm run dev

3. Frontend

cd frontend
npm install
npm run dev

Open http://localhost:5173 — on first login a loading screen syncs your messages before showing the chat UI.

Environment variables (backend/.env)

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=http://localhost:3001/auth/google/callback
SESSION_SECRET=           # crypto.randomBytes(32).toString('hex')
ENCRYPTION_KEY=           # crypto.randomBytes(32).toString('hex')
FRONTEND_URL=http://localhost:5173
ALLOWED_CONTACTS=         # required — comma-separated list of allowed emails
PORT=3001
DB_PATH=./data/conversemail.db
MAX_THREADS=100           # optional — max threads to fetch per contact
PUBSUB_TOPIC=             # optional — Gmail push notification topic

Project structure

ConverseMail/
├── backend/
│   ├── src/
│   │   ├── auth/        OAuth2 flow, token encryption
│   │   ├── gmail/       Gmail API client & email parser
│   │   ├── db/          SQLite schema & migrations
│   │   ├── routes/      Express route handlers
│   │   └── server.js    Entry point, ALLOWED_CONTACTS validation
│   ├── .env
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── components/  ChatBubble, Sidebar, ThreadList, MessageInput
│   │   ├── pages/       ChatView, LoginPage
│   │   ├── services/    API client
│   │   ├── App.jsx      Three-column layout, login → sync → chat flow
│   │   └── main.jsx
│   └── package.json
├── .gitignore
└── README.md

Author

Frederic Uhrweiller