📧 Auto Email Sendr

Automatic email mass-sender for outreach and campaigns.

A terminal-based bulk emailer that personalizes messages from a CSV contact list, rotates randomly between multiple sender accounts and write-ups, and keeps a per-batch record of who was contacted.

---

📑 Table of Contents

• Overview
• Features
• Requirements
• Installation
• Configuration
• Usage
• CSV & Personalization
• Output
• Project Structure
• Security
• Contributing
• License
• Author

---

🔎 Overview

Auto Email Sendr is an interactive command-line tool for sending personalized emails in bulk over SMTP. You point it at a CSV of contacts, configure one or more sender accounts and message templates, and it walks each row — substituting placeholders, picking a template and sender at random, and sending the message — while showing live progress and logging the results.

It is designed for legitimate outreach: newsletters, event invites, recruitment campaigns, and similar mailing to recipients who expect to hear from you.

⚠️ Use responsibly. Only email people who have consented to be contacted, and comply with your email provider's terms and applicable anti-spam laws (e.g. CAN-SPAM, GDPR).

---

✨ Features

• 📨 Bulk sending over SMTP with STARTTLS (works with Gmail, Outlook, and most providers).
• 🧩 Placeholder personalization — replace {name}, {company}, etc. in both the subject and body with values from each CSV row.
• 🎲 Randomized rotation of multiple sender addresses and message write-ups across recipients.
• 🛡️ Resilient send loop — a single bad recipient or missing template is logged and skipped, never aborting the whole campaign.
• ⏱️ Configurable throttle (send_delay_seconds) to reduce provider rate-limiting and spam flags.
• 🗂️ Result segregation — output CSVs can be split per write-up and/or per sender address.
• 🖥️ Friendly TUI — arrow-key menus, ASCII-art banners, and a live progress bar.
• 🔧 First-run setup — settings.toml is auto-created from a template; everything is editable from the in-app Settings menu.

---

📦 Requirements

• Python 3.8+
• Works on Windows, Linux, and macOS (keyboard handling adapts per platform).
• An SMTP account and credentials (for Gmail, generate an App Password rather than using your login password).

Dependencies (installed via requirements.txt):

Package	Purpose
colorama	Cross-platform colored terminal output
tomli	Reading the TOML settings file
tomli_w	Writing the TOML settings file

---

🚀 Installation

# 1. Clone the repository
git clone https://github.com/PolybitRockzz/auto-email-sendr.git
cd auto-email-sendr

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run the app
python app.py

On Windows, you can simply double-click run.bat, which installs the dependencies and launches the app.

---

⚙️ Configuration

On first launch the app copies settings.example.toml to settings.toml, which holds your credentials and campaign configuration. You can edit it directly or — recommended — through the in-app Settings menu.

[smtp]
username = ""              # your SMTP login / email address
passkey = ""              # SMTP password or app password
smtp_server = "smtp.gmail.com"
smtp_port = 587
send_delay_seconds = 1.0   # pause between sends (seconds)

[emails]
ids = []                   # sender addresses (chosen at random per email)
subjects = []              # subject lines, paired by index with writeups
writeups = []              # file paths to message bodies, paired with subjects
isfromfile = []            # internal flag per write-up

[csv]
titles = ["Email"]         # CSV column headers to read
placeholders = ["email"]   # placeholder names, paired by index with titles
output_folder = "output"   # where result CSVs are written
segregate_by_writeups = true
segregate_by_ids = false

Key points:

• An email placeholder is required and must map (via titles) to a real column in your CSV.
• subjects[i] and writeups[i] are paired — write-up i is always sent with subject i.
• Write-ups are file paths to plain-text/UTF-8 message bodies.

---

🖱️ Usage

1. Launch the app: python app.py (or run.bat).
2. Open Settings and fill in:
   • SMTP — username, passkey, server, and port.
   • Email Addresses & Write-ups — your sender address(es), subjects, and body files.
   • CSV Data Placeholders — the column titles/placeholders and output filtering.
3. From the main menu, choose Run Automation.
4. Enter the path to your contacts .csv file.
5. Review the confirmation screen and confirm to start sending.

Navigate menus with the arrow keys and select with Enter.

---

🧩 CSV & Personalization

Your contacts file is a standard CSV with a header row. Column titles must match the titles configured in settings; each title is bound to a placeholder of the same index.

Example — contacts.csv:

Email,Name,Company
alice@example.com,Alice,"Acme, Inc"
bob@example.com,Bob,Globex

With placeholders email → Email, name → Name, company → Company, a write-up body like:

Hi {name},

We'd love to work with {company}.

…and a subject Hello {name} become, for the first row:

Subject: Hello Alice Body: Hi Alice, We'd love to work with Acme, Inc.

Quoted fields containing commas (e.g. "Acme, Inc") are parsed correctly.

---

📤 Output

After a run, result CSVs are written to the configured output_folder (default output/). Depending on your filter settings, contacts are recorded:

• Per write-up (segregate_by_writeups = true) → output-<writeup>.csv
• Per sender ID (segregate_by_ids = true) → output-<sender>.csv

The run finishes with a summary of emails sent vs. failed, plus a list of any failures and their reasons.

---

🗂️ Project Structure

auto-email-sendr/
├── app.py                  # Entry point — launches the main menu
├── pages.py                # Page flow: run, send loop, settings, credits, main menu
├── console.py              # Terminal I/O & graphics (menus, key input, banners)
├── config.py               # settings.toml load / save / validation
├── constants.py            # Shared constants (version)
├── settings.example.toml   # Template copied to settings.toml on first run
├── requirements.txt        # Python dependencies
├── run.bat                 # Windows convenience launcher
└── LICENSE                 # Apache License 2.0

---

🔐 Security

• Your SMTP passkey is stored locally in plaintext in settings.toml.
• settings.toml and settings_backup.toml are gitignored by default — never share or commit them.
• Prefer a provider App Password scoped to this tool over your main account password.
• The committed settings.example.toml contains no credentials and is safe to share.

---

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/my-feature.
3. Commit your changes and open a Pull Request against main.

Please keep changes focused and describe the motivation in your PR.

---

📄 License

Distributed under the Apache License 2.0. See LICENSE for details.

If this project helped you, consider giving it a ⭐ on GitHub!