NeatMail is an intelligent email management platform that automatically organizes your Gmail and Outlook inboxes in real-time. No complicated setup, no manual sorting - just clean, organized emails labeled exactly where you need them.

• Drowning in emails with no structure
• Spending hours manually organizing messages
• Missing important emails buried in clutter
• Wasting time drafting repetitive responses

NeatMail watches your inbox 24/7 and:

• ✨ Automatically labels incoming emails directly in Gmail and Outlook
• 🎨 Custom categories - use presets or create your own
• 🤖 AI-powered drafts - generates response drafts for pending emails in your tone
• 🔄 Real-time processing - labels emails as they arrive, not in batches

• Preset Categories: Action Needed, Pending Response, Automated Alerts, Event Updates, Discussion, Read Only, Resolved, Marketing
• Custom Labels: Create personalized labels with custom colors
• Direct Gmail & Outlook Integration: Labels/categories appear instantly in your mailbox interface
• 95%+ Confidence Threshold: Only labels when AI is highly confident

• Automatically detects emails requiring responses
• Generates contextual draft replies in your tone
• Creates drafts directly in Gmail and Outlook for easy editing and sending
• Skips automated/newsletter emails intelligently

• Weekly email trends visualization
• Real-time tracking of labeled emails
• Sender, subject, and label insights
• Date-based filtering and search

• OAuth 2.0 authentication via Clerk
• Minimal permission scope (read metadata, labels/categories, drafts)
• No email content storage
• Row-level security with Prisma

• Node.js 20+ and npm/yarn/pnpm
• PostgreSQL database
• Redis instance
• Google Cloud Project with Gmail API enabled (for Gmail)
• Microsoft Entra app registration with Microsoft Graph Mail permissions (for Outlook)
• Clerk account for authentication
• OpenAI API key
• DodoPay account (payment processing)

1. Clone the repository

git clone https://github.com/Lakshay1509/NeatMail.git
cd neatmail

2. Install dependencies

bun install
#or
npm install
# or
pnpm install

3. Set up environment variables

Create a .env.local file:

# Database
DATABASE_URL="postgresql://..."
DIRECT_URL="postgresql://..."

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
CLERK_WEBHOOK_SECRET=

# OpenAI
OPENAI_API_KEY=

#If using Azure
AZURE_ENDPOINT=
AZURE_API_KEY=

# Gmail Webhook
GMAIL_WEBHOOK_TOPIC=projects/your-project/topics/gmail-notifications

#Gmail service account
GMAIL_SERVICE_ACCOUNT=

# Redis
UPSTASH_REDIS_URL=
UPSTASH_REDIS_TOKEN=

# Payment (DodoPay)
DODO_API=
DODO_WEBHOOK_SECRET=
DODO_PRODUCT_ID_INDIA=
DODO_PRODUCT_ID_GLOBAL=
DODO_WEB_URL=

#API URL
NEXT_PUBLIC_API_URL=http://localhost:3000

#Cron Secret
CRON_SECRET=

#INNGEST
INNGEST_EVENT_KEY=
INNGEST_SIGNING_KEY=

#Classification URL
CLASSIFICATION_API_URL=
CLASSIFICATION_API_BEARER_TOKEN=

# App Configuration
NODE_ENV=development

4. Set up the database

bunx prisma generate
bunx prisma db push

5. Run the development server

bun run dev

Open http://localhost:3000 in your browser.

graph LR
   A[Gmail / Outlook] -->|Push Notification| B[Google Pub/Sub / Graph Subscription]
    B -->|Webhook| C[NeatMail API]
   C -->|Fetch Email| A
   C -->|Classify| D[OpenAI]
    D -->|Label Name| C
   C -->|Apply Label/Category| A
    C -->|Generate Draft| D
    D -->|Draft Content| C
    C -->|Create Draft| A
    C -->|Store Metadata| E[(PostgreSQL)]
    C -->|Deduplication| F[(Redis)]

• Next.js 16 - Frontend & API routes
• Hono - Lightweight API framework
• Prisma - Type-safe ORM
• Gmail API / Microsoft Graph API - Email operations
• OpenAI GPT-4 - Email classification & draft generation
• Clerk - Authentication & OAuth management
• Redis - Message deduplication
• Google Pub/Sub - Real-time webhook delivery

• Framework: Next.js 16.1.1 (App Router)
• Language: TypeScript 5.x
• UI Library: React 19.2.3
• Styling: Tailwind CSS 4.x
• UI Components: Radix UI, shadcn/ui
• Charts: Recharts 3.6.0
• State Management: TanStack Query 5.90.16 (React Query)
• Forms: React Hook Form 7.71.1 + Zod 4.3.5

• API: Hono.js 4.11.3
• Database: PostgreSQL
• ORM: Prisma 7.2.0 with Prisma Adapter PG
• Cache: Redis (Upstash Redis 1.36.0)
• Authentication: Clerk 6.36.5
• Payments: DodoPay 2.14.1
• Webhooks: Svix 1.84.1

• Draft Generation: OpenAI 6.15.0 (GPT-4 Mini)
• Classification: OpenAI 6.15.0 (GPT-4 Mini)
• Email APIs: Google APIs 169.0.0 (Gmail API), Microsoft Graph API (Outlook)
• Webhooks: Google Cloud Pub/Sub

• Hosting: Vercel (recommended)
• Database: Neon/Supabase PostgreSQL
• Redis: Upstash Redis
• Monitoring: Vercel Analytics

1. Click the button above or manually:

npm install -g vercel
vercel

2. Configure environment variables in Vercel dashboard

3. Set up Google Cloud Pub/Sub webhook:

   • Create a Pub/Sub topic
   • Add your Vercel domain as webhook endpoint
   • Grant Gmail API permissions

npx prisma migrate deploy

1. Go to Google Cloud Console
2. Create a new project
3. Enable Gmail API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URIs (Clerk callback)
6. Create a Pub/Sub topic for webhooks

1. Go to Azure Portal
2. Open Microsoft Entra ID → App registrations → New registration
3. Add redirect URIs used by your auth provider (Clerk callback)
4. Add Microsoft Graph delegated permissions (for example):
   • Mail.Read
   • Mail.ReadWrite
   • Mail.Send
   • offline_access
5. Grant admin consent if required by your tenant policy
6. Configure subscription/webhook notifications for mailbox events

1. Create a Clerk application
2. Enable Google OAuth provider
3. Add required Gmail scopes:
   • https://www.googleapis.com/auth/gmail.modify
   • https://www.googleapis.com/auth/gmail.compose
   • https://www.googleapis.com/auth/gmail.readonly
4. Configure webhook endpoints if needed

1. Create a DodoPay account
2. Create a subscription product
3. Configure webhook endpoints for subscription events
4. Add webhook secret to environment variables

1. Configure Environment Fill in the .env.build file with your credentials (ensure no empty lines or comments):

   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=...
   NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
   NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
   NEXT_PUBLIC_API_URL=http://localhost:8080
   DATABASE_URL=...
   DIRECT_URL=...
   UPSTASH_REDIS_URL=...
   UPSTASH_REDIS_TOKEN=...
   OPENAI_API_KEY=...

2. Build Image Build the container image using podman (or docker), passing the variables as build arguments:

   podman build \
     $(sed 's/^/--build-arg /' .env.build) \
     -t neatmail .

3. Run Container Run the container passing the environment variables:

   podman run -p 8080:8080 --env-file .env.local neatmail
   

• /app - Next.js 16 App Router with route groups for auth and dashboard
• /components - Reusable React components including shadcn/ui primitives
• /features - Custom React Query hooks organized by feature domain
• /lib - Core utilities for Gmail, OpenAI, Prisma, Redis integrations
• /prisma - Database schema with multi-schema support and generated client
• /types - Shared TypeScript interfaces and type definitions

We love contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow TypeScript best practices
• Write meaningful commit messages
• Add tests for new features
• Update documentation as needed
• Ensure code passes linting (npm run lint)

This project is licensed under the MIT License - see the LICENSE file for details.

• Next.js - React framework
• Clerk - Authentication
• OpenAI - AI models
• Prisma - Database ORM
• shadcn/ui - UI components

• Website: neatmail.tech
• Issues: GitHub Issues
• Email: help.neatmail@gmail.com