📧 Gmail Mail Parser

A beautiful web application to parse, organize, and manage your Gmail inbox

Features • Demo • Installation • Usage • Contributing

---

🎯 Overview

Gmail Mail Parser is a powerful yet easy-to-use web application that connects to your Gmail account and helps you:

• Visualize your inbox with beautiful statistics
• Organize emails by grouping them by sender
• Clean up your inbox by finding and using unsubscribe links

All processing happens locally on your computer - your emails never leave your machine!

---

✨ Features

Feature	Description
📊 Dashboard	Get a bird's-eye view of your inbox with stats on total emails, unique senders, and categories
👥 Group by Sender	See all emails organized by who sent them, with search and filter capabilities
🚫 Unsubscribe Manager	Automatically detects unsubscribe links in promotional emails for easy cleanup
🔐 Secure OAuth2	Uses Google's official OAuth2 - we never see or store your password
🌙 Modern Dark UI	Beautiful glassmorphism design with smooth animations
📱 Responsive	Works great on desktop, tablet, and mobile devices

---

🖼️ Demo

Landing Page

The sleek landing page with feature highlights and secure sign-in.

Dashboard

Overview of your inbox with category breakdown and top senders.

Sender View

All your emails grouped by sender with filtering options.

Unsubscribe Manager

Find and manage promotional subscriptions easily.

---

🚀 Installation

Prerequisites

• Python 3.8 or higher
• A Gmail account
• Google Cloud project with Gmail API enabled

Quick Start

1. Clone the repository

   git clone https://github.com/D3S-Gaurav/Mail_parser.git
   cd Mail_parser

2. Create a virtual environment

   python -m venv .venv
   
   # Windows
   .venv\Scripts\activate
   
   # Mac/Linux
   source .venv/bin/activate

3. Install dependencies

   pip install -r requirements.txt

4. Set up Google Cloud credentials

   • See SETUP.md for detailed instructions
   • Place your credentials.json in the project root

5. Run the application

   python app.py

6. Open in browser

   http://localhost:5000
   

---

📁 Project Structure

Mail_parser/
├── 📄 app.py                 # Main Flask web application
├── 📄 gmail_parser.py        # CLI version (standalone)
├── 📄 requirements.txt       # Python dependencies
├── 📄 SETUP.md              # Detailed setup guide
├── 📄 README.md             # This file
├── 📁 templates/            # HTML templates
│   ├── base.html            # Base template with navigation
│   ├── index.html           # Landing page
│   ├── dashboard.html       # Email statistics dashboard
│   ├── senders.html         # Emails grouped by sender
│   └── unsubscribe.html     # Unsubscribe manager
└── 📁 static/               # Static assets
    ├── 📁 css/
    │   └── style.css        # Modern dark theme styles
    └── 📁 js/
        └── main.js          # JavaScript utilities

---

🔧 Usage

Web Application (Recommended)

python app.py

Then open http://localhost:5000 in your browser.

Command Line Interface

For a simpler CLI experience:

python gmail_parser.py

This will fetch emails and save them to the parsed_emails/ folder as JSON and CSV files.

---

🔒 Security & Privacy

Aspect	Details
Authentication	OAuth2 via Google - we never see your password
Data Storage	All emails processed locally, nothing sent to external servers
Permissions	Read-only access to emails (gmail.readonly scope)
Credentials	Your credentials.json and tokens are excluded from git

---

🛠️ Tech Stack

• Backend: Python 3, Flask
• Frontend: HTML5, CSS3, JavaScript (Vanilla)
• API: Gmail API via Google Cloud
• Authentication: OAuth 2.0
• Design: Custom CSS with glassmorphism effects

---

📋 API Endpoints

Endpoint	Method	Description
/	GET	Landing page
/login	GET	Initiate OAuth2 login
/oauth2callback	GET	OAuth2 callback handler
/logout	GET	Clear session and logout
/dashboard	GET	Main dashboard view
/senders	GET	Emails grouped by sender
/unsubscribe	GET	Unsubscribe manager
/api/emails	GET	Fetch emails JSON data
/api/sender/<email>	GET	Get emails from specific sender

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

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

---

📝 License

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

---

🙏 Acknowledgments

• Google Gmail API for email access
• Flask for the web framework
• Inter Font for beautiful typography

---

⭐ Star this repo if you find it useful!

Made with ❤️ by D3S-Gaurav