Gmail Cleaner

A powerful Node.js application for cleaning and organizing Gmail inboxes through automated rules and batch operations.

🚀 Features

Smart Email Filtering: Advanced query building with Gmail search operators
Batch Operations: Archive, delete, or label multiple emails efficiently
OAuth2 Authentication: Secure Google account integration
Rule-Based Automation: Create custom rules for automatic email management
Real-time Dashboard: Monitor email statistics and operations
Production Ready: Comprehensive error handling, monitoring, and rate limiting
RESTful API: Full API access for programmatic control

⚡ Quick Start

Clone and Install

git clone https://github.com/NicolasFares/gmail-cleaner
cd gmail-cleaner
npm install

Setup Google OAuth

# Follow the OAuth setup guide
cp .env.example .env
# Add your Google OAuth credentials to .env

Run the Application
```
npm run dev
```
Access the Dashboard Open http://localhost:3000 and sign in with your Google account.

🛠 Requirements

Node.js: v18.0.0 or higher
npm: v8.0.0 or higher
Google Cloud Account: For Gmail API access
Modern Browser: Chrome, Firefox, Safari, or Edge

📦 Installation

1. Clone Repository

git clone <repository-url>
cd gmail-cleaner

2. Install Dependencies

npm install

3. Setup Environment

cp .env.example .env

4. Configure Google OAuth

Follow our Google OAuth Setup Guide to:

Create a Google Cloud project
Enable Gmail API
Configure OAuth consent screen
Create OAuth 2.0 credentials

5. Generate Session Secret

npm run generate-secret

⚙️ Configuration

Environment Variables

Variable	Description	Example
`NODE_ENV`	Environment mode	`development`
`PORT`	Server port	`3000`
`GOOGLE_CLIENT_ID`	OAuth client ID	`your-client-id`
`GOOGLE_CLIENT_SECRET`	OAuth client secret	`your-client-secret`
`GOOGLE_REDIRECT_URI`	OAuth redirect URI	`http://localhost:3000/auth/google/callback`
`SESSION_SECRET`	Session encryption key	`generated-secret`
`DATABASE_PATH`	SQLite database path	`./data/gmail_cleaner.db`
`LOG_LEVEL`	Logging level	`debug`

See .env.example for all available options.

🎯 Usage

Web Interface

Authentication: Sign in with your Google account
Dashboard: View email statistics and system health
Search & Filter: Use advanced Gmail search operators
Batch Operations: Select and apply actions to multiple emails
Rule Management: Create automated rules for email organization

API Access

The application provides a RESTful API for programmatic access:

# Get email statistics
curl http://localhost:3000/api/dashboard/stats

# Search emails
curl http://localhost:3000/api/emails/search?query=from:example.com

# Archive emails
curl -X POST http://localhost:3000/api/emails/archive \
  -H "Content-Type: application/json" \
  -d '{"messageIds": ["id1", "id2"]}'

Command Line Scripts

# Development server with hot reload
npm run dev

# Production server
npm start

# Run tests
npm test

# Code quality checks
npm run lint
npm run format

📊 Monitoring & Health

The application includes comprehensive monitoring capabilities:

Health Checks: /health, /health/detailed, /health/ready, /health/live
Metrics: Prometheus-compatible metrics at /health/metrics
Alerts: Real-time alerting for system issues
Circuit Breakers: Protection for external API calls
Rate Limiting: Configurable request limiting

🏗 Architecture

src/
├── api/                    # API layer
│   ├── routes/            # Express route handlers
│   ├── middleware/        # Authentication, error handling, monitoring
│   └── schemas/           # Input validation schemas
├── services/              # Business logic
│   ├── gmail.service.js   # Gmail API interactions
│   ├── auth.service.js    # OAuth authentication
│   ├── rules.service.js   # Email filtering rules
│   ├── metrics.service.js # Performance monitoring
│   └── alert.service.js   # Alerting system
├── models/                # Data models
├── utils/                 # Utilities (logger, constants)
├── config/                # Configuration files
├── app.js                 # Express app setup
└── index.js              # Server entry point

🔧 Development

Setup Development Environment

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Configure your .env file

# Start development server
npm run dev

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific test suite
npm test -- --testPathPattern=gmail.service

Code Quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

🚢 Deployment

Production Deployment

Environment Setup

export NODE_ENV=production
export PORT=3000
# Set production environment variables

Database Migration

# Setup production database (PostgreSQL recommended)
npm run migrate

Start Application
```
npm start
```

Docker Deployment

# Build image
docker build -t gmail-cleaner .

# Run container
docker run -p 3000:3000 --env-file .env gmail-cleaner

Production Checklist

📚 Documentation

Setup Guide - Detailed installation instructions
Google OAuth Setup - OAuth configuration guide
Troubleshooting - Common issues and solutions
API Documentation - Complete API reference
Developer Guide - Development guidelines
Deployment Guide - Production deployment
FAQ - Frequently asked questions

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contributing Steps

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

🛡 Security

OAuth2: Secure Google account authentication
Session Management: Encrypted session storage
Input Validation: Comprehensive request validation
Rate Limiting: Protection against abuse
Audit Logging: Security event tracking
Error Handling: Secure error responses

📄 License

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

🙋‍♂️ Support

Documentation: Check our comprehensive docs
Issues: Report bugs via GitHub Issues
Discussions: Ask questions in GitHub Discussions

🔗 Related Resources

Gmail Cleaner - Efficient Gmail inbox management
Made with ❤️ for productive email management

Name		Name	Last commit message	Last commit date
.claude		.claude
backlog		backlog
config		config
data		data
docs		docs
public		public
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.env.production.example		.env.production.example
.gitignore		.gitignore
.prettierrc		.prettierrc
CLAUDE.md		CLAUDE.md
Dockerfile.production		Dockerfile.production
GOOGLE_OAUTH_SETUP.md		GOOGLE_OAUTH_SETUP.md
README.md		README.md
docker-compose.production.yml		docker-compose.production.yml
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
setup_guide.md		setup_guide.md

Latest commit

History

Folders and files

Repository files navigation