Smart Bulk Email & Certificate System with AI-Powered Column Detection
Features • Quick Start • Tech Stack • Documentation • Contributing
MailForge AI is a powerful full-stack application for sending personalized bulk emails with automatic certificate generation.
It leverages Google AI for intelligent column detection and offers a seamless, drag-and-drop experience.
- 🔐 Secure Authentication - JWT-based login with AES-256 encrypted SMTP credentials
- 📊 Smart File Upload - AI detects Name & Email columns automatically from any Excel/CSV
- ✏️ Dynamic Recipients - Edit, add, remove, and validate recipients in real-time
- 📧 Rich Email Editor - WYSIWYG + HTML mode with dynamic variables support (e.g.,
{{name}},{{event}}) - 🎓 Certificate Generator - Auto-attach personalized PDF certificates
- 📮 Bulk Sending Engine - Optimized for Gmail with intelligent rate limiting (1 email/sec)
- 📈 Campaign Analytics - Real-time tracking of sent, failed, and pending emails
- AI-Powered: Uses Google Gemini for smart column mapping (with rule-based fallback)
- Zero-Block Sending: Intelligent queue management to prevent SMTP blocks
- Military-Grade Encryption: AES-256 encryption for all sensitive credentials
- Reactive UI: Auto-refreshing status updates and smooth Framer Motion animations
- Dark Mode: Beautiful, GitHub-inspired dark theme with Space Mono typography
| Frontend | Backend |
|---|---|
 |
 |
 |
 |
 |
 |
 |
 |
- Node.js 18+ installed
- Gmail Account with an App Password
git clone https://github.com/YOUR_USERNAME/bulk-email.git
cd bulk-email# Open a new terminal for Backend
cd backend
npm install
# Configure Environment
cp .env.example .env
# Edit .env and set your secrets
# Start Backend
npm run dev# Open a new terminal for Frontend
cd frontend
npm install
# Start Frontend
npm run devCreate a .env file in the backend folder:
PORT=5000
JWT_SECRET=your_super_secret_jwt_key_32chars_min
ENCRYPTION_KEY=your_32_character_key_for_aes_encryptionWith both terminals running, visit:
- Frontend App: http://localhost:3000
- Backend API: http://localhost:5000
- Navigate to http://localhost:3000
- Enter ANY email and password.
- The first user is automatically created as the Admin.
- Go to the Settings tab.
- Enter your Gmail Address.
- Enter your App Password (Not your login password!).
💡 To get an App Password: Go to Google Account > Security > 2-Step Verification > App Passwords.
- Upload: Drag & drop your Excel/CSV file.
- Review: The AI will auto-detect Name/Email columns. Verify and edit if needed.
- Compose: Write your email using
{{name}}variables. - Certificate: (Optional) Toggle "Attach Certificate" and customize the template.
- Send: Click "Send Campaign" and watch the progress in real-time! 🚀
bulk-email/
├── 📂 backend/ # Node.js + Express API
│ ├── 📂 routes/ # Auth, Upload, Campaign endpoints
│ ├── 📂 utils/ # DB helpers, Encryption
│ ├── 📂 data/ # JSON Database (users.json, campaigns.json)
│ └── 📂 uploads/ # Temp file storage
│
├── 📂 frontend/ # React + Vite App
│ ├── 📂 src/
│ │ ├── 📂 components/ # UI Components (Editors, Tables)
│ │ ├── 📂 pages/ # Dashboard, Settings
│ │ └── 📂 context/ # Auth State Management
│ └── 📄 main.jsx # Entry Point
│
├── 📂 docs/ # Detailed Documentation
└── 📄 README.md # You are here!- Zero-Knowledge Storage: SMTP passwords are encrypted using AES-256-CBC before saving.
- Secure Sessions: Authentication via JWT (JSON Web Tokens) with auto-expiry.
- Data Safety: Inputs are sanitized to prevent injection attacks.
- Rate Control: Built-in throttles to respect Gmail's sending limits.
For more detailed information, check out the docs/ folder:
- 📖 Setup Guide: Detailed installation and troubleshooting.
- 📡 API Reference: Endpoints, request bodies, and examples.
- 🏗️ Architecture: System design and data flow.
We love contributions! Please read our Contributing Guide to get started.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
Built with ❤️ for hassle-free bulk emailing.