---

🌟 Overview

The Email Automation System is a professional Python-based automation project developed to send, schedule, and manage emails efficiently using the Gmail API.

💡 Developed as part of an AI Internship Project at Nest-Agent — demonstrating real-world API integration, OAuth authentication, and automation workflows.

What it does: 📩 Gmail API Integration ⏰ Email Scheduling 🎨 HTML Email Templates 🧾 Email Logging System

How it works: 🔐 OAuth Authentication ⚙️ Automation Workflows 🛡️ Secure Email Handling 📂 Modular Architecture

---

✨ Features

Feature	Description	Status
📩 Instant Sending	Send emails immediately via Gmail API	✅
⏰ Scheduling	Auto-deliver emails at set times	✅
🔐 OAuth 2.0	Secure Google authentication, no password stored	✅
🧾 Logging	Full email history with timestamps	✅
🎨 HTML Templates	Beautiful, customizable email designs	✅
📂 Modular Code	Clean, maintainable project structure	✅
⚡ Lightweight	Fast performance, minimal dependencies	✅
🖥️ Terminal UI	Interactive menu-driven interface	✅

---

🛠️ Tech Stack

---

📁 Project Structure

📦 email-automation-system/
│
├── 📁 logs/
│   └── 📄 email_logs.txt          ← all sent email records
│
├── 📁 templates/
│   └── 🎨 email_template.html     ← HTML email design
│
├── 📁 utils/                      ← helper utilities
│
├── 📁 .venv/                      ← virtual environment
│
├── 🔒 .env                        ← secrets (never commit!)
├── ⚙️  config.py                   ← configuration settings
├── 📧 email_service.py            ← core email logic
├── 📝 logger.py                   ← logging system
├── 🚀 main.py                     ← entry point
├── ⏰ scheduler.py                ← scheduling logic
├── 📦 requirements.txt
├── 🔑 credentials.json            ← OAuth credentials (never commit!)
├── 🔑 token.json                  ← OAuth token (never commit!)
└── 📖 README.md

---

⚙️ Installation

1️⃣ Clone Repository

git clone https://github.com/YOUR_USERNAME/email-automation-system.git
cd email-automation-system

2️⃣ Create Virtual Environment

python -m venv .venv

Activate:

# Windows
.\.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

3️⃣ Install Dependencies

pip install -r requirements.txt

---

🔐 Gmail API Setup

Step 1 — Open Google Cloud Console

👉 https://console.cloud.google.com/

Step 2 — Create a Project

Create a new project and name it:

Email Automation System

Step 3 — Enable Gmail API

APIs & Services → Library → Gmail API → Enable

Step 4 — Configure OAuth Consent Screen

APIs & Services → OAuth Consent Screen

Configure:

• App Type: External
• App Name: Email Automation System
• Support Email: your Gmail
• Test Users: add your Gmail

Step 5 — Create OAuth Credentials

APIs & Services → Credentials → Create Credentials → OAuth Client ID → Desktop App

Download the JSON file → Rename to credentials.json → Place in project root.

---

🔑 Environment Variables

Create a .env file in the root directory:

# Email Configuration
SENDER_EMAIL=your_email@gmail.com
SENDER_PASSWORD=your_password_here

# Time Zone
TZ=UTC

⚠️ Never commit this file to GitHub!

---

▶️ Run The Project

python main.py

---

🖥️ Application Menu

╔══════════════════════════════════════╗
║     📧 Email Automation System       ║
╠══════════════════════════════════════╣
║  1.  Send an email immediately       ║
║  2.  Schedule an email               ║
║  3.  Start scheduler loop            ║
║  4.  Exit                            ║
╚══════════════════════════════════════╝

---

🎨 HTML Email Templates

Templates are stored in templates/email_template.html. You can customize:

Element	What to Change
🎨 Colors	Brand color scheme
🖼️ Logo	Company logo URL
🏢 Company Name	Header/footer text
🔘 Buttons	CTA button text & links
📐 Layout	Section arrangement

Adding a logo:

<img src="YOUR_IMAGE_URL" alt="Company Logo" width="150">

Host images on: GitHub · ImgBB · Cloudinary · Your website

---

🧾 Logging System

Every email is automatically logged in logs/email_logs.txt:

[2024-12-15 09:32:11] | TO: client@company.com | SUBJECT: Q4 Report | STATUS: ✅ SENT
[2024-12-15 10:15:44] | TO: team@nestAgent.io  | SUBJECT: Reminder   | STATUS: ✅ SENT
[2024-12-15 11:00:02] | TO: invalid@noDomain   | SUBJECT: Test       | STATUS: ❌ FAILED

---

🔒 Security Notes

⚠️ Never push these files to GitHub!

# Add to .gitignore
.env
credentials.json
token.json

File	Why It's Sensitive
.env	Contains email credentials
credentials.json	Google OAuth app secrets
token.json	Your personal access token

---

🧠 Authentication Flow

Run python main.py
        ↓
First run detected?
        ↓
Browser opens → Google OAuth Login
        ↓
Grant Gmail permissions
        ↓
token.json saved automatically
        ↓
✅ Ready! No re-login needed.

---

🚀 Future Improvements

#	Feature	Priority
1	🖥️ GUI Interface	🔴 High
2	🤖 AI Generated Emails	🔴 High
3	📨 Bulk Email Sending	🟡 Medium
4	📊 Email Analytics Dashboard	🟡 Medium
5	📎 Attachment Support	🟡 Medium
6	👥 Multi-user Support	🟢 Low
7	🌐 Web Dashboard	🟢 Low

---

🤝 Developer

Muhammad Yasir AI Intern @ Nest-Agent

---

📄 License

This project is licensed under the MIT License — feel free to use, modify and distribute.

---

Thank You For Visiting This Project!

⭐ If you found this useful, please star the repository! ⭐