Inbox Concierge

An intelligent email classification app that uses AI to automatically organize your Gmail inbox into smart buckets.

TL;DR

cp backend/.env.example backend/.env  # then fill in your credentials
docker-compose up --build

Open http://localhost:5173

Features

• Google OAuth - Securely connect your Gmail account
• AI-Powered Classification - Uses Claude to intelligently categorize emails
• Smart Buckets - Default categories (Important, Can Wait, Newsletter, Auto-archive) plus custom buckets
• Auto-Classification - New emails are automatically classified on refresh

Prerequisites

• Docker & Docker Compose
• Google Cloud Project with Gmail API enabled
• Anthropic API Key

Setup

1. Google Cloud OAuth

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable the Gmail API (APIs & Services > Library)
4. Configure OAuth consent screen:
   • Choose "External" user type
   • Add scope: gmail.readonly
   • Add your email as a test user
5. Create OAuth credentials:
   • Go to Credentials > Create Credentials > OAuth client ID
   • Choose "Web application"
   • Add redirect URI: http://localhost:8000/auth/callback
   • Save the Client ID and Client Secret

2. Anthropic API Key

1. Go to Anthropic Console
2. Generate an API key

3. Environment Variables

cp backend/.env.example backend/.env

Edit backend/.env:

DATABASE_URL=postgresql://postgres:postgres@postgres:5432/inbox_concierge

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:8000/auth/callback

ANTHROPIC_API_KEY=your-anthropic-api-key

SESSION_SECRET=generate-a-random-secret-here

FRONTEND_URL=http://localhost:5173
BACKEND_URL=http://localhost:8000

Generate a session secret:

openssl rand -hex 32

4. Run

docker-compose up --build

The app will be available at:

• Frontend: http://localhost:5173
• Backend: http://localhost:8000

To stop:

docker-compose down

To stop and clear data:

docker-compose down -v

Usage

1. Open http://localhost:5173
2. Click "Sign in with Google"
3. Authorize Gmail access
4. Wait for initial email fetch and classification
5. Browse emails by bucket using the tabs
6. Use "Manage Buckets" to customize categories

Tech Stack

• Frontend: React, TypeScript, Vite, Tailwind CSS
• Backend: Python, FastAPI, SQLAlchemy
• Database: PostgreSQL
• AI: Anthropic Claude

Troubleshooting

"Invalid redirect URI" - Ensure http://localhost:8000/auth/callback is set in Google Cloud OAuth credentials.

"Gmail API not enabled" - Enable Gmail API in your Google Cloud project.

Database errors - Check that PostgreSQL container is running: docker-compose ps