Email Sending Script - Step-by-Step Guide

This project sends emails (with your resume attached) to addresses from an Excel file and writes results to a CSV log.

1. Prerequisites

Install these first:

1. Python 3.10+
2. A Gmail account (or another SMTP account)
3. An SMTP app password (for Gmail, use App Passwords with 2FA enabled)

2. Keep Required Files in This Folder

Make sure these files are in the project root (c:\Users\Gagana\Documents\Email Sending):

• send_emails.py
• requirements.txt
• .env
• cleaned_company_emails.xlsx
• Gagana Resume.pdf

3. Create and Activate a Virtual Environment

Open PowerShell in this folder and run:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

If PowerShell blocks activation, run once:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Then activate again:

.\.venv\Scripts\Activate.ps1

4. Install Dependencies

pip install -r requirements.txt

5. Configure .env

Your script reads SMTP settings from .env.

Use this format:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_password
FROM_NAME=Your Name

Important:

• SMTP_USER is your sender email.
• SMTP_PASS must be an app password (not your normal Gmail password).
• Keep .env private and never share it.

6. Prepare the Excel File Correctly

The script expects:

• File name: cleaned_company_emails.xlsx
• Sheet name: Unique_by_email
• A column named exactly: Email

If sheet name or column name is different, the script will stop with an error.

7. (Optional) Update Email Subject/Body/Attachment

In send_emails.py, you can edit:

• SUBJECT
• BODY_TEMPLATE
• ATTACHMENT_FILE (currently Gagana Resume.pdf)

8. Set Safety Controls Before Running

In send_emails.py, review these values:

DRY_RUN = True
SLEEP_SECONDS = 2
MAX_EMAILS = 3
TEST_OVERRIDE_TO = "your_test_email@gmail.com"

Recommended test setup:

1. DRY_RUN = True (no real emails sent)
2. MAX_EMAILS = 3 (small test batch)
3. TEST_OVERRIDE_TO = "your_test_email@gmail.com" (all test sends go to you)

After successful testing, switch to real send:

DRY_RUN = False
MAX_EMAILS = None
TEST_OVERRIDE_TO = None

9. Run the Script

python .\send_emails.py

10. Check Results

The script writes logs to:

• send_log.csv

Log columns:

• timestamp
• email
• original_email
• status (SENT, FAILED, or DRY_RUN)
• error

11. Troubleshooting

1. Missing SMTP_USER / SMTP_PASS
   Fix .env values and rerun.

2. Excel not found
   Confirm cleaned_company_emails.xlsx exists in the same folder.

3. Excel sheet must contain a column named 'Email'
   Rename/add the exact Email column in the Unique_by_email sheet.

4. Gmail auth errors (535, login failed)
   Recreate app password and verify SMTP_USER/SMTP_PASS.

5. Attachment not found
   Ensure Gagana Resume.pdf exists in the project root.

12. Typical End-to-End Flow

1. Activate virtual environment.
2. Install requirements.
3. Set .env.
4. Confirm Excel sheet/column names.
5. Run a DRY_RUN test with MAX_EMAILS = 3.
6. Run a real test using TEST_OVERRIDE_TO.
7. Send to full list with DRY_RUN = False, TEST_OVERRIDE_TO = None.
8. Review send_log.csv for failures and resend only failed emails if needed.