📧 Email Deleter — because your inbox is a war zone and you're finally winning

okay so I built this thing because I was getting like 200 promo emails a day and I was NOT about to manually unsubscribe from all of them like some kind of animal. so yeah, this is a full-stack Gmail automation service with a cyberpunk dashboard, encrypted backups, and a cron job that silently deletes your digital trash every night while you sleep. you're welcome.

built with: Next.js 19 + React 19 (yes, the new one) · Express 5 · PostgreSQL · Docker · Gmail API · AES-256-GCM encryption · and a concerning amount of caffeine

---

📸 Screenshots

Dashboard	Rules Management

Reports	Auth Flow

---

✨ what it does

• Rule Engine — define rules by keyword, sender, or email age. set it and forget it.
• Cyberpunk Dashboard — drag-and-drop rule management, live metrics, the whole vibe
• Encrypted Reports — every deletion run saves an XLSX report encrypted with AES-256-GCM. your data, your keys.
• Daily Cron — runs at midnight by default. your inbox wakes up clean every morning.
• Secure by default — helmet, rate limiting, session hardening, encrypted token storage. not just vibes.

---

🛡️ Security & Encryption

This project is built with a security-first mindset. Because it handles your Gmail access, I've implemented multiple layers of protection:

• AES-256-GCM Encryption: All generated reports are encrypted before they hit the disk. I use PBKDF2 with 100,000 iterations for key derivation.
• Encrypted Local Backups: Your data, your keys. Even if someone gains access to your server files, your email backups are unreadable without your ENCRYPTION_KEY.
• OAuth 2.0: I used Google's official OAuth flow. Your Google password never touches my servers.
• Hardened API: Protected by helmet, express-rate-limit, and CSRF protection (where applicable).

---

🔑 Step 0 — Google OAuth Setup (do this first, trust me)

you need a Google Cloud project with the Gmail API enabled. takes like 5 minutes.

1. go to console.cloud.google.com and create a new project
2. navigate to APIs & Services → Library, search for Gmail API, and enable it
3. go to APIs & Services → OAuth consent screen
   • choose External, fill in the app name + your email
   • add the scope: https://www.googleapis.com/auth/gmail.modify
   • add your own Google account as a Test User (required while in testing mode)
4. go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID
   • Application type: Web application
   • Authorized redirect URIs: http://localhost:5555/api/auth/google/callback
5. copy your Client ID and Client Secret — you'll need them in the next step

---

⚙️ Environment Setup

cp .env.example .env

then fill in your .env — here's what everything means:

# Google OAuth — from Step 0 above
GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost:5555/api/auth/google/callback

# Session — just a random string, make it weird
SESSION_SECRET=some_long_random_string_here

# Database
DB_HOST=localhost          # use "db" if running via Docker
DB_PORT=5432
DB_NAME=email_deleter
DB_USER=postgres
DB_PASSWORD=your_password_here

# Encryption Key — MUST be exactly 64 hex characters
# generate one: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_KEY=your_64_char_hex_key_here

# URLs
FRONTEND_URL=http://localhost:3067
NEXT_PUBLIC_API_URL=http://localhost:5555/api

# Cron (default: midnight daily — change if you're a night owl)
CRON_SCHEDULE="0 0 * * *"

⚠️ lose your ENCRYPTION_KEY and all stored tokens become unreadable. back it up somewhere safe. no, a sticky note doesn't count.

---

🐳 Option A — Docker (recommended, aka the "it works on my machine AND yours" path)

make sure you have Docker + Docker Compose installed, then:

# 1. build and start everything (db + backend + frontend)
make deploy

# 2. seed the database with default rules
make seed

that's it. seriously. Docker handles postgres, migrations, everything.

Service	URL
Frontend UI	http://localhost:3067
Backend API	http://localhost:5555

other useful Docker commands

make up        # start containers (after first build)
make down      # stop containers
make restart   # restart all containers
make logs      # tail logs in real-time
make migrate   # run DB migrations manually
make clean     # nuclear option — wipes containers + volumes

or if you're allergic to Makefiles and prefer raw Docker:

docker-compose build --no-cache
docker-compose up -d
docker-compose logs -f
docker-compose down
docker-compose down -v   # also removes the database volume

---

💻 Option B — Local Dev Setup (for contributors / tinkerers)

prerequisites: Node.js 20+, PostgreSQL 15+, npm

Backend

cd backend
npm install

# make sure your .env has DB_HOST=localhost
npm run db:migrate
npm run db:seed
npm dev              # starts with nodemon on port 5555

Frontend

cd frontend
npm install
npm run dev          # starts Next.js on port 3067

Running tests

cd backend
npm test             # jest with coverage
npm run test:watch   # watch mode for when you're in the zone

Linting

npm run lint         # check
npm run lint:fix     # fix (the coward's way, but also the smart way)

---

📂 Project Structure

.
├── backend/          # Express 5 API — rules, cron, Gmail integration
│   └── src/
│       ├── controllers/
│       ├── services/     # the actual brains
│       ├── models/       # Sequelize + PostgreSQL
│       └── routes/
├── frontend/         # Next.js 19 + React 19 dashboard
│   └── src/
│       ├── app/
│       ├── components/
│       └── store/        # Zustand (because Redux is a lot)
├── docs/             # deeper dives if you're into that
├── docker-compose.yml
├── Makefile
└── .env.example

---

📚 Docs (for when you want the full lore)

• Docker Deployment Guide
• Google OAuth Setup Guide
• Security Audit

---

🤝 Contributing

PRs welcome! if you find a bug, open an issue. if you fix a bug, you're a legend.

please don't commit your .env file. I'm begging you.

---

📄 License

This project is licensed under the MIT License. You are free to use, modify, and fork this code, but please give credit to Kashif Raza by keeping the copyright notice intact in all copies or substantial portions of the software.

---

built because I was tired of my inbox. now it's someone else's problem too (yours, if you clone this).