GmailHunt

A production-minded Gmail inbox cleanup SaaS for people with overloaded inboxes.

Features

• Secure Google OAuth - Sign in with your Google account
• Gmail API Integration - Connect and manage your Gmail inbox via official API
• IMAP Fallback - Also supports IMAP connection with App Passwords
• Cleanup Rules - Pre-built rules for newsletters, promotions, receipts, old emails, bills, travel, social media, and shipping
• Preview Mode - See exactly what will happen before any changes
• Bulk Actions - Archive, label, mark read, or move to trash
• Run History - Track all cleanup operations with detailed logs
• Safe by Default - No permanent deletes, trash is disabled by default

Tech Stack

• Next.js 15 with App Router
• TypeScript
• Tailwind CSS
• Prisma ORM
• PostgreSQL
• NextAuth.js with Google OAuth
• Gmail API (googleapis)

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL database
• Google Cloud Console project with Gmail API enabled (for OAuth)
• Gmail IMAP enabled (for IMAP fallback)

1. Clone and Install

cd gmailhunt
npm install

2. Set Up Environment Variables

Copy .env.example to .env and fill in your values:

cp .env.example .env

Required variables:

• DATABASE_URL - PostgreSQL connection string
• NEXTAUTH_SECRET - Generate with openssl rand -base64 32
• NEXTAUTH_URL - http://localhost:3000 (or your production URL)
• GOOGLE_CLIENT_ID - From Google Cloud Console
• GOOGLE_CLIENT_SECRET - From Google Cloud Console

3. Set Up Google OAuth

1. Go to Google Cloud Console
2. Create a new project
3. Enable Gmail API
4. Configure OAuth consent screen
5. Create OAuth credentials (Web application)
6. Add authorized redirect URI: http://localhost:3000/api/auth/callback/google
7. Add authorized JavaScript origins: http://localhost:3000

For testing, add your test user's email to the OAuth test users list.

4. Set Up Database

# Generate Prisma client
npm run db:generate

# Push schema to database
npm run db:push

5. Run Development Server

npm run dev

Open http://localhost:3000

Development Login

For local testing without Google OAuth, use the test login at /test-login with any email address that exists in your database.

Project Structure

gmailhunt/
├── prisma/
│   └── schema.prisma       # Database schema
├── src/
│   ├── app/
│   │   ├── api/            # API routes
│   │   ├── dashboard/      # Authenticated pages
│   │   ├── layout.tsx      # Root layout
│   │   ├── page.tsx        # Landing page
│   │   └── test-login/     # Dev test login
│   ├── components/         # React components
│   ├── hooks/              # Custom React hooks
│   ├── lib/
│   │   ├── auth.ts        # NextAuth config
│   │   ├── db.ts           # Prisma client
│   │   ├── gmail.ts       # Gmail API service
│   │   └── imap.ts        # IMAP fallback service
│   └── types/              # TypeScript types
├── .env.example
├── package.json
├── tailwind.config.js
├── tsconfig.json
└── README.md

Preset Cleanup Rules

The app includes these preset cleanup rules:

1. Newsletters - Archives newsletters with "Newsletters" label
2. Promotions - Archives promotional emails with "Promotions" label
3. Receipts - Labels receipts with "Receipts" label
4. Old Inbox (6 months) - Archives emails older than 6 months
5. Bills & Statements - Labels bills and financial statements
6. Travel Confirmations - Labels travel bookings and reservations
7. Social Media Updates - Archives social media notifications
8. Shipping Notifications - Labels shipping and delivery updates

Safety Features

• Preview First - Always preview changes before applying
• Archive Only - Default action is archive (removes INBOX label), not delete
• Trash Disabled - Trash must be explicitly enabled in settings
• Action Logging - All actions are logged in the database
• Safe Mode - Configurable safe mode to block destructive actions
• Run History - Full audit trail of all cleanup operations

API Routes

Rules

• GET /api/rules - Get user's cleanup rules
• GET /api/rules/[id] - Get specific rule
• POST /api/rules - Create rule
• POST /api/preset-rules - Add preset rule

Runs

• GET /api/runs - Get cleanup run history
• POST /api/preview - Preview rule execution
• POST /api/apply - Apply rule execution

Connection

• GET /api/connection - Get connection status
• POST /api/imap - Connect via IMAP
• DELETE /api/imap - Disconnect IMAP

Utilities

• GET /api/inbox-count - Get current inbox count
• GET /api/preset-rules - Get available preset rules

Production Deployment

1. Set up a PostgreSQL database (e.g., Supabase, Neon, Railway)
2. Update DATABASE_URL in environment
3. Set NEXTAUTH_URL to your production domain
4. Configure Google OAuth with production URLs
5. Build and start: npm run build && npm run start

License

MIT