README.md

metadata

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:

pip install -r requirements.txt

2. How to Start the App GUI 🖥️

Run the app.py script:

python app.py

After you press enter, open your web browser and navigate to exactly: 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.
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