📧 Python Email Automation Tool

A lightweight, production-style email automation API built with FastAPI — supports single SMTP sends, bulk CSV campaigns, environment-based config, structured logging, and unit tests.

---

✨ Features

• 📨 Single email sending via SMTP (TLS/SSL support)
• 📋 Bulk email campaigns from a CSV file
• 🔐 Environment variable config — no secrets in code
• 📝 Structured logging with log levels and file output
• 🧪 Unit tests with pytest
• 🗂 Modular architecture — clean separation of concerns
• ⚡ FastAPI with automatic OpenAPI docs at /docs

---

📁 Project Structure

email-automation/
├── app/
│   ├── api/
│   │   ├── __init__.py
│   │   └── routes/
│   │       ├── __init__.py
│   │       ├── email.py          # Single email endpoint
│   │       └── bulk.py           # Bulk CSV email endpoint
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py             # Settings from .env via Pydantic
│   │   └── logging.py            # Logger setup
│   ├── models/
│   │   ├── __init__.py
│   │   └── email.py              # Pydantic request/response models
│   ├── services/
│   │   ├── __init__.py
│   │   └── email_service.py      # SMTP logic (single + bulk)
│   └── utils/
│       ├── __init__.py
│       └── csv_parser.py         # CSV reading and validation
├── tests/
│   ├── __init__.py
│   ├── test_email_service.py     # Unit tests for email service
│   └── test_csv_parser.py        # Unit tests for CSV utility
├── sample_data/
│   └── recipients.csv            # Example bulk email CSV
├── logs/                         # Auto-created at runtime
├── .env.example                  # Environment variable template
├── .gitignore
├── requirements.txt
├── main.py                       # App entrypoint
└── README.md

---

🚀 Getting Started

1. Clone the Repository

git clone https://github.com/yourusername/email-automation.git
cd email-automation

2. Create & Activate a Virtual Environment

python -m venv venv

# macOS / Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment Variables

cp .env.example .env

Open .env and fill in your SMTP credentials:

# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your_email@gmail.com
SMTP_PASSWORD=your_app_password
SMTP_USE_TLS=true

# Sender Info
DEFAULT_SENDER_NAME=Your Name
DEFAULT_SENDER_EMAIL=your_email@gmail.com

# App Settings
APP_ENV=development
LOG_LEVEL=INFO
LOG_FILE=logs/app.log

Gmail users: Use an App Password, not your account password.

5. Run the Server

uvicorn main:app --reload

API is now live at: http://localhost:8000
Interactive docs: http://localhost:8000/docs

---

📡 API Endpoints

POST /api/email/send

Send a single email.

Request Body:

{
  "to": "recipient@example.com",
  "subject": "Hello from FastAPI",
  "body": "This is a test email.",
  "html": false
}

Response:

{
  "status": "success",
  "message": "Email sent to recipient@example.com"
}

---

POST /api/email/bulk

Send emails to multiple recipients from an uploaded CSV file.

Form Data:

• file — CSV file upload (see format below)
• subject — Email subject line
• body — Email body text (supports {name} placeholder)

Example recipients.csv:

name,email
Alice Johnson,alice@example.com
Bob Smith,bob@example.com
Carol White,carol@example.com

Response:

{
  "status": "success",
  "total": 3,
  "sent": 3,
  "failed": 0,
  "errors": []
}

---

GET /api/email/health

Health check endpoint.

{ "status": "ok", "smtp_connected": true }

---

🧪 Running Tests

pytest tests/ -v

Example output:

tests/test_email_service.py::test_build_message_plain        PASSED
tests/test_email_service.py::test_build_message_html         PASSED
tests/test_email_service.py::test_send_raises_on_bad_config  PASSED
tests/test_csv_parser.py::test_parse_valid_csv               PASSED
tests/test_csv_parser.py::test_parse_missing_email_column    PASSED
tests/test_csv_parser.py::test_parse_empty_file              PASSED

6 passed in 0.42s

---

📋 Requirements

requirements.txt

fastapi==0.111.0
uvicorn[standard]==0.29.0
pydantic==2.7.0
pydantic-settings==2.2.1
python-multipart==0.0.9
python-dotenv==1.0.1
pytest==8.2.0
pytest-asyncio==0.23.6
httpx==0.27.0

---

⚙️ Core Module Reference

app/core/config.py

Uses pydantic-settings to load and validate all environment variables at startup. Raises a clear error if required variables are missing.

app/services/email_service.py

Handles all SMTP logic:

• Opens a single connection per request (context manager)
• Supports text/plain and text/html content types
• Bulk sends iterate recipients with per-email error capture — one failure won't abort the batch

app/utils/csv_parser.py

• Validates CSV has required email column
• Strips whitespace from all fields
• Returns a typed list of Recipient objects

app/core/logging.py

• Logs to both console and logs/app.log
• Log level controlled by LOG_LEVEL env var
• Format: [timestamp] [LEVEL] module: message

---

🔒 Security Notes

• Never commit .env to version control — it's included in .gitignore
• Use App Passwords or OAuth2 tokens instead of raw SMTP passwords
• For production, consider rate-limiting the /bulk endpoint
• Validate and sanitize all CSV inputs before sending

---

🌐 Deployment

Docker

docker build -t email-automation .
docker run -p 8000:8000 --env-file .env email-automation

Render / Railway / Fly.io

1. Connect your GitHub repo
2. Set environment variables in the platform dashboard
3. Set start command: uvicorn main:app --host 0.0.0.0 --port 8000

---

🤝 Contributing

1. Fork the repo
2. Create a branch: git checkout -b feat/your-feature
3. Commit: git commit -m 'feat: describe your change'
4. Push: git push origin feat/your-feature
5. Open a Pull Request

---

📄 License

MIT © [Ashish Yadav]

---

Built with ⚡ FastAPI · 📧 SMTP · 🐍 Python