simple-mail-cleaner/README.md

Simple Mail Cleaner

State-of-the-art mail cleanup tool with multi-tenant support, newsletter unsubscribe automation, and a modern web UI.

Stack

• Backend: Node.js + TypeScript + Fastify
• Frontend: React + Vite + TypeScript + i18n
• DB: PostgreSQL
• Queue: Redis + BullMQ worker

Quick start

docker compose up --build

• Web UI: http://localhost:3000
• API: http://localhost:8000
• API Docs: http://localhost:8000/docs

API (initial)

• POST /auth/register { tenantName, email, password }
• POST /auth/login { email, password }
• GET /tenants/me (auth)
• GET /mail/accounts (auth)
• POST /mail/accounts (auth)
• POST /mail/cleanup (auth) { mailboxAccountId, dryRun, unsubscribeEnabled, routingEnabled }
• GET /jobs (auth)
• GET /jobs/:id/events (auth)
• GET /jobs/:id/stream?token=... (auth via query token, SSE)
• GET /rules (auth)
• POST /rules (auth)
• PUT /rules/:id (auth)
• DELETE /rules/:id (auth)
• GET /admin/tenants (admin)
• PUT /admin/tenants/:id (admin)
• GET /admin/users (admin)
• PUT /admin/users/:id (admin)
• PUT /admin/users/:id/role (admin)
• POST /admin/users/:id/reset (admin)
• GET /admin/accounts (admin)
• PUT /admin/accounts/:id (admin)
• GET /admin/jobs (admin)
• GET /admin/jobs/:id/events (admin)

Notes

• Newsletter detection will use List-Unsubscribe headers + heuristics.
• Weblink unsubscribe uses HTTP first, mailto fallback (SMTP required).
• Worker scans headers and applies routing rules (MOVE/DELETE) when not in dry run.

Seed data

cd backend
DATABASE_URL=postgresql://mailcleaner:mailcleaner@localhost:5432/mailcleaner \\
SEED_EMAIL=admin@simplemailcleaner.local \\
SEED_PASSWORD=change-me-now \\
npm run prisma:seed

• DSGVO: data storage is designed for tenant isolation; encryption at rest will be added.

Environment

docker-compose.yml sets default dev credentials. Adjust before production use.