SpamGuard Mailer

An intelligent email management system with AI-powered content generation, spam detection, and scheduled sending capabilities.

Features • Installation • Usage • Technologies • Contributing

---

✨ Features

• 🤖 AI Email Generation: Automatically generate professional emails based on prompts using advanced AI
• 🛡️ Spam Detection: Naive Bayes classifier to detect and filter spam emails
• ⏰ Scheduled Sending: Schedule emails to be sent at specific times with APScheduler
• 🔐 Google OAuth: Secure authentication via Google OAuth 2.0
• 📧 Gmail Integration: Send emails directly through Gmail API
• 📱 Responsive Design: Modern, mobile-friendly UI with Font Awesome icons

---

📁 Project Structure

SpamGuardMailer/
├── app.py                      # Main application entry point
├── config/
│   ├── __init__.py
│   ├── logging_config.py       # Logging configuration
│   ├── models.py               # Database models (SQLAlchemy)
│   └── mysql.py                # MySQL configuration
├── routes/
│   ├── __init__.py
│   ├── MailerSender.py         # Email sending logic
│   ├── MailerTester.py         # Spam detection logic
│   ├── word_freq.json          # Word frequencies for classifier
│   └── class_freq.json         # Class frequencies for classifier
├── static/
│   ├── Css/
│   │   ├── base.css            # Base styles
│   │   ├── homepage.css        # Homepage styles
│   │   ├── send_email.css      # Email form styles
│   │   ├── preview_email.css   # Preview styles
│   │   ├── rapport.css         # Rapport styles
│   │   └── schedule_email.css  # Schedule form styles
│   └── JS/
│       └── base.js             # JavaScript functionality
├── templates/
│   ├── base.html               # Base template
│   ├── homepage.html           # Landing page
│   ├── send_email.html         # Email generation form
│   ├── preview_email.html      # Email preview
│   ├── schedule_email.html     # Schedule form
│   ├── successful.html         # Success page
│   ├── rapport.html            # Spam detection results
│   ├── detect_spam.html        # Spam detection form
│   └── error.html              # Error pages
├── .env                        # Environment variables (not committed)
├── requirements.txt            # Python dependencies
└── README.md                   # This file

---

🚀 Installation

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.8+
• MySQL/MariaDB database
• Google Cloud Console project with OAuth 2.0 credentials

Step 1: Clone Repository

git clone https://github.com/YSN-B13/SpamGuardMailer.git
cd SpamGuardMailer

Step 2: Create Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure Environment Variables

Create a .env file in the project root with the following variables:

# Flask Configuration
FLASK_SECRET_KEY=your_secret_key_here

# Google OAuth
GOOGLE_OAUTH_CLIENT_ID=your_google_client_id
GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret
OAUTHLIB_INSECURE_TRANSPORT=1  # Only for development

# AI API Key
GEMINI_API_KEY=your_gemini_api_key

# MySQL Database
MYSQL_USER=your_mysql_user
MYSQL_PASSWORD=your_mysql_password
MYSQL_DB=your_database_name
MYSQL_HOST=localhost

Step 5: Set Up Google OAuth

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable Gmail API:
   • Navigate to APIs & Services → Library
   • Search for "Gmail API" and enable it
4. Create OAuth 2.0 Credentials:
   • Go to Credentials → Create Credentials → OAuth 2.0 Client ID
   • Configure consent screen:
     • User Type: External
     • Scopes: openid, email, profile, https://www.googleapis.com/auth/gmail.send
   • Add Authorized redirect URI: http://127.0.0.1:5000/login/google/authorized
5. Copy Client ID and Client Secret to your .env file

Step 6: Run the Application

python app.py

The application will be available at http://127.0.0.1:5000

---

💻 Usage

Sending Emails

1. Navigate to the homepage
2. Click "Send Email" or "Generate Email"
3. Enter email details or provide a prompt for AI generation
4. Preview the email
5. Send immediately or schedule for later

Detecting Spam

1. Navigate to "Detect Spam"
2. Paste email content
3. Click "Analyze"
4. View spam probability and classification results

Scheduled Emails

1. Create an email as usual
2. Select "Schedule Email"
3. Choose date and time
4. Confirm scheduling

---

🔒 Security Considerations

⚠️ Important Security Notes:

• Never commit .env file to version control
• Store OAuth tokens encrypted in production
• Use HTTPS in production (Google requires it for OAuth)
• Set offline=True in Google blueprint to get refresh tokens
• Implement rate limiting for API endpoints
• Validate and sanitize all user inputs
• Use environment-specific configurations

---

🛠️ Technologies Used

Category	Technologies
Backend	Flask, Flask-Dance, Flask-SQLAlchemy
Database	MySQL/MariaDB with SQLAlchemy ORM
Authentication	Google OAuth 2.0
Email	Gmail API
Scheduling	APScheduler
Frontend	HTML5, CSS3, JavaScript, Font Awesome
AI	Gemini API (for email generation)
Machine Learning	Naive Bayes (for spam detection)

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

Contribution Guidelines

• Follow PEP 8 style guide for Python code
• Write descriptive commit messages
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

---

📄 License

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

---

👤 Contact

Yassine Moutawakkil

• GitHub: @YSN-B13
• Email: yassinemoutawakkil2004@gmail.com

---

🙏 Acknowledgments

• Google OAuth for authentication
• Flask community for excellent documentation
• All contributors who help improve this project

---

Made with ❤️ by Yassine Moutawakkil

⭐ Star this repository if you find it helpful!