# harsha2809/ai-powered-bulk-mailer architecture

> Architecture diagram of the GitHub repository harsha2809/ai-powered-bulk-mailer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harsha2809/ai-powered-bulk-mailer
- Repository: https://github.com/harsha2809/ai-powered-bulk-mailer

## Overview

This is a bulk-email/job-inquiry automation tool. Its main workflow extracts addresses from a PDF into a CSV, then sends recipients in batches through SMTP and records outcomes. A separate sender generates personalized message text with a Gemini-backed model. The README also describes HTML mail and resume attachments, but the checked-in tree does not show an HTML sending or attachment path; the template is present without demonstrated runtime wiring. The standalone FastAPI health endpoint is separate. Relationships below follow the sampled code or README; unsampled feature wiring is not inferred.

Main entry points: [`send_next_batch.py`](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/send_next_batch.py) (Resumable batch sender), [`send_smtp.py`](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/send_smtp.py) (AI-enabled sender), [`extract_emails.py`](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/extract_emails.py) (Recipient CSV), [`ai_email_generator.py`](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/ai_email_generator.py) (Email generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Recipient ingestion"]
  node_pdf_extract["PDF extraction<br/>[extract_emails.py]"]
  node_recipient_csv["Recipient CSV<br/>[extract_emails.py]"]
end

subgraph group_delivery["Email delivery"]
  node_batch_sender["Resumable batch sender<br/>[send_next_batch.py]"]
  node_smtp_sender["AI-enabled sender<br/>[send_smtp.py]"]
  node_smtp_service{{"Gmail SMTP"}}
  node_results_csv["Results log<br/>[send_next_batch.py]"]
  node_failures_csv["Failures log<br/>[send_next_batch.py]"]
end

subgraph group_content["Message content"]
  node_generator["Email generator"]
  node_llm{{"Gemini model"}}
  node_html_template["HTML template"]
end

subgraph group_operations["Service status"]
  node_health_api["Health endpoint<br/>[main.py]"]
end

node_operator(("Operator"))
node_api_client(("HTTP client"))

node_operator -->|"runs extraction"| node_pdf_extract
node_pdf_extract -->|"writes addresses"| node_recipient_csv
node_operator -->|"runs batch"| node_batch_sender
node_batch_sender -->|"reads and trims"| node_recipient_csv
node_batch_sender -->|"sends via"| node_smtp_service
node_batch_sender -->|"writes remainder"| node_recipient_csv
node_batch_sender -->|"appends outcomes"| node_results_csv
node_batch_sender -->|"logs failures"| node_failures_csv
node_operator -->|"runs sender"| node_smtp_sender
node_smtp_sender -->|"reads recipients"| node_recipient_csv
node_smtp_sender -->|"requests content"| node_generator
node_smtp_sender -->|"sends via"| node_smtp_service
node_smtp_sender -->|"logs outcomes"| node_results_csv
node_generator -->|"invokes model"| node_llm
node_api_client -.->|"requests status"| node_health_api

click node_pdf_extract "https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/extract_emails.py"
click node_recipient_csv "https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/extract_emails.py"
click node_batch_sender "https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/send_next_batch.py"
click node_smtp_sender "https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/send_smtp.py"
click node_results_csv "https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/send_next_batch.py"
click node_failures_csv "https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/send_next_batch.py"
click node_generator "https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/ai_email_generator.py"
click node_html_template "https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/email_template.html"
click node_health_api "https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pdf_extract,node_recipient_csv,node_api_client toneBlue
class node_batch_sender,node_smtp_sender,node_smtp_service,node_results_csv,node_failures_csv toneAmber
class node_generator,node_llm,node_html_template toneMint
class node_health_api toneRose
class node_operator toneIndigo
```

## Components

### Recipient ingestion

- [PDF extraction](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/extract_emails.py): `extract_emails.py`
- [Recipient CSV](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/extract_emails.py): `extract_emails.py`

### Email delivery

- [Resumable batch sender](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/send_next_batch.py): `send_next_batch.py`
- [AI-enabled sender](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/send_smtp.py): `send_smtp.py`
- **Gmail SMTP**
- [Results log](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/send_next_batch.py): `send_next_batch.py`
- [Failures log](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/send_next_batch.py): `send_next_batch.py`

### Message content

- [Email generator](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/ai_email_generator.py): `ai_email_generator.py`
- **Gemini model**
- [HTML template](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/email_template.html): `email_template.html`

### Service status

- [Health endpoint](https://github.com/harsha2809/ai-powered-bulk-mailer/blob/main/main.py): `main.py`

### Other components

- **Operator**
- **HTTP client**

## Connections

- Operator → PDF extraction: runs extraction (evidence: `README.md`)
- PDF extraction → Recipient CSV: writes addresses (evidence: `extract_emails.py`)
- Operator → Resumable batch sender: runs batch (evidence: `README.md`)
- Resumable batch sender → Recipient CSV: reads and trims (evidence: `send_next_batch.py`)
- Resumable batch sender → Gmail SMTP: sends via (evidence: `send_next_batch.py`)
- Resumable batch sender → Recipient CSV: writes remainder (evidence: `send_next_batch.py`)
- Resumable batch sender → Results log: appends outcomes (evidence: `send_next_batch.py`)
- Resumable batch sender → Failures log: logs failures (evidence: `send_next_batch.py`)
- Operator → AI-enabled sender: runs sender (evidence: `README.md`)
- AI-enabled sender → Recipient CSV: reads recipients (evidence: `send_smtp.py`)
- AI-enabled sender → Email generator: requests content (evidence: `send_smtp.py`)
- AI-enabled sender → Gmail SMTP: sends via (evidence: `send_smtp.py`)
- AI-enabled sender → Results log: logs outcomes (evidence: `send_smtp.py`)
- Email generator → Gemini model: invokes model (evidence: `ai_email_generator.py`)
- HTTP client → Health endpoint: requests status