README.md

---
title: MailFlow AI
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
---

# MailFlow AI - Advanced Email Automation 🚀

A highly attractive, GUI-based Python email automation tool designed for both beginners and advanced businesses. MailFlow AI is tailored for sending personalized emails to a list of contacts from an Excel/CSV file with optional attachments. It includes an intuitive web interface built using Flask and Tailwind CSS.

## Key Features

- **Beautiful GUI Interface**: Run the app locally and get a modern, interactive dashboard and campaign builder.
- **Dynamic Personalization**: Automatically insert variables like `{FirstName}` or `{CompanyName}` dynamically based on your contact sheet columns.
- **Smart Tracking**: Connects to your Excel file, tracking "Already Sent" vs "Pending" emails to prevent duplicate sends. 
- **Real-time Progress Bar**: Watch your emails send one by one with a live success/fail tracker.
- **Optional Attachments**: Super easy UI to mass-upload files like PDFs and Images to your emails.
- **Batch Processing**: Configurable delays to avoid your emails being flagged as spam.

## Quick Start (For Beginners & Pros)

### 1. Installation Requirements

1. Install Python (version 3.x).
2. Clone this repository to your computer.
3. Install the dependencies using terminal/command prompt:
```bash
pip install -r requirements.txt
```

### 2. How to Start the App GUI 🖥️

Run the `app.py` script:
```bash
python app.py
```
After you press enter, open your web browser and navigate to exactly: **[http://127.0.0.1:5000](http://127.0.0.1:5000)**

### 3. Securing Your Gmail App Password (CRITICAL) 🔐

Because of standard security rules, you **cannot** use your normal Gmail login password for automated email software. You need to quickly generate a special 16-character "App Password". 

**Here is exactly how to generate it (Takes 1 minute):**
1. Go to your [Google Account Dashboard](https://myaccount.google.com/).
2. On the left navigation panel, click **Security**.
3. Under the "How you sign in to Google" section, make sure **2-Step Verification** is turned ON.
4. Once 2-Step Verification is active, search for **App Passwords** in the top search bar (or find it at the bottom of the 2-step verification page).
5. Name the app password something recognizable, like `MailFlow AI`.
6. Click **Generate**.
7. Google will give you a **16-letter password** (e.g. `abcd efgh ijkl mnop`). 
8. Copy that password *without* spaces. This is the password you will paste into the GUI when making a new campaign!

### 4. Excel/CSV Contact Sheet Rules 📊

Before creating a campaign, make sure your Excel (.xlsx) or CSV file has columns for your data.
- **Email Column:** You can name your email column anything (e.g. `Email`, `RecipientEmail`, `Contact`). The app will dynamically detect it or let you choose it from a dropdown!
- You can add any custom columns you want! Example: `FirstName`, `Industry`.
- In the "Email Body Message" area of the GUI, just type `{FirstName}` and it will auto-populate that column's data for every single person.

*Note: The app will safely auto-create columns `EmailSent` and `DateSent` tracking to log its successful deliveries.*

---

## Technical Details (For Advanced Users)

- **Framework:** Python Flask (Backend) + HTML/JS/Tailwind CSS (Frontend)
- **Concurrency:** Uses asynchronous sequential dispatch over REST API to prevent browser timeouts for large email lists (`/api/send_next`).
- **Data Persistence:** Updates the specific `.xlsx`/`.csv` contact file locally on each iteration using an optimistic file-lock model so progress is instantly saved on hard drive.
- **SMTP Limitations:** Using Gmail SMTP, be cautious of Google's hard sending limits (approximately 500 emails/day for free accounts, 2000 for Google Workspace). We built-in a 1 second delay per email to prevent automated spam flags. 

License: MIT