mail_automation/ │ ├── README.md # Main Guide (START HERE) ├── INSTALLATION.md # Step-by-step Windows installation guide ├── TROUBLESHOOTING.md # Solutions for common problems │ ├── send_emails.py # The main Python script ├── requirements.txt # Python library dependencies │ ├── install.bat # Double-click to install all dependencies ├── run.bat # Double-click to run the email script │ ├── images/ # Folder to store images for your emails │ └── README.md # Instructions on how to use images │ ├── credentials.json # Your Google Cloud application credentials └── token.json # Your authorization token (generated on first run)

Automatic Email Sender

This project sends personalized mass emails using the Gmail API, with all contacts and settings managed in a Google Sheet. It is built with a "safety-first" approach, defaulting to a configurable Test Mode and providing a timestamp for every email sent.

Features

• Centralized Google Sheet: Manages both your contact list (Recipients tab) and script settings (Settings tab).
• Sent Timestamp: Automatically records the exact date and time an email was successfully sent in a timestamp column for perfect auditing.
• Multi-Recipient Test Mode: Send a sample of your emails to a list of testers (e.g., you, your manager) before the real campaign.
• Safe by Default: The script always starts in Test Mode to prevent accidental sends.
• Header Validation: The script stops if your Recipients tab is missing the required columns (firstName, lastName, email, sent?, timestamp).

Recommended Workflow

1. Read and follow the INSTALLATION.md guide to set up your Google Sheet and credentials.
2. In the Settings tab of your sheet, add the email addresses of your test group.
3. Add contacts to the Recipients tab with a sent? status of 0.
4. Run the script by double-clicking run.bat. It will run in Test Mode by default.
5. Your test group will receive a sample of the emails. Review them for correctness (personalization, images, etc.).
6. If the test is successful, run the script again and type yes when prompted to run in Live Mode. The script will then send the real emails and update the sheet.