# ckshetty4/cold_mail_automation architecture

> Architecture diagram of the GitHub repository ckshetty4/cold_mail_automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ckshetty4/cold_mail_automation
- Repository: https://github.com/ckshetty4/cold_mail_automation

## Overview

Cold Email Automator is a small Python script that reads contact rows, personalizes an email, attaches a resume, and sends a bounded batch through Gmail. Its main workflow resumes from a saved serial number and records progress after each successful send (or skipped row); randomized pauses separate sends. Configuration provides credentials, template, and batch settings. The README documents Excel input, resume attachment, batching, and restart behavior; sampled source confirms the orchestration and file/SMTP interactions.

Main entry points: [`app.py`](https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py) (Batch Orchestrator), [`config.py`](https://github.com/ckshetty4/cold_mail_automation/blob/main/config.py) (Runtime Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Batch Workflow"]
  node_runner["Batch Orchestrator<br/>[app.py]"]
  node_contacts["Contact Workbook"]
  node_batch["Batch Selection<br/>[app.py]"]
  node_delay["Randomized Delay<br/>[app.py]"]
end

subgraph group_content["Email Content"]
  node_compose["Personalized Email<br/>[app.py]"]
  node_template["Template And Profile<br/>[config.py]"]
  node_sender["SMTP Sender<br/>[app.py]"]
  node_resume["Resume PDF"]
end

subgraph group_state["Configuration And State"]
  node_settings["Runtime Settings<br/>[config.py]"]
  node_history["Progress History"]
end

node_user(("Operator"))
node_gmail["Gmail SMTP"]
node_dotenv["Environment Secrets"]

node_user -->|"runs"| node_runner
node_runner -->|"reads settings"| node_settings
node_settings -->|"loads credentials"| node_dotenv
node_runner -->|"reads progress"| node_history
node_runner -->|"loads workbook"| node_contacts
node_runner -->|"selects rows"| node_batch
node_runner -->|"formats each email"| node_compose
node_compose -->|"fills template"| node_template
node_runner -->|"sends message"| node_sender
node_sender -->|"reads attachment"| node_resume
node_sender -->|"sends via SMTP"| node_gmail
node_runner -->|"updates progress"| node_history
node_runner -->|"waits between sends"| node_delay

click node_runner "https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py"
click node_batch "https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py"
click node_delay "https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py"
click node_compose "https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py"
click node_template "https://github.com/ckshetty4/cold_mail_automation/blob/main/config.py"
click node_sender "https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py"
click node_settings "https://github.com/ckshetty4/cold_mail_automation/blob/main/config.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_runner,node_contacts,node_batch,node_delay toneBlue
class node_compose,node_template,node_sender,node_resume toneAmber
class node_settings,node_history toneMint
class node_user,node_gmail,node_dotenv toneIndigo
```

## Components

### Batch Workflow

- [Batch Orchestrator](https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py): `app.py`
- **Contact Workbook**
- [Batch Selection](https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py): `app.py`
- [Randomized Delay](https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py): `app.py`

### Email Content

- [Personalized Email](https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py): `app.py`
- [Template And Profile](https://github.com/ckshetty4/cold_mail_automation/blob/main/config.py): `config.py`
- [SMTP Sender](https://github.com/ckshetty4/cold_mail_automation/blob/main/app.py): `app.py`
- **Resume PDF**

### Configuration And State

- [Runtime Settings](https://github.com/ckshetty4/cold_mail_automation/blob/main/config.py): `config.py`
- **Progress History**

### Other components

- **Operator**
- **Gmail SMTP**
- **Environment Secrets**

## Connections

- Operator → Batch Orchestrator: runs
- Batch Orchestrator → Runtime Settings: reads settings
- Runtime Settings → Environment Secrets: loads credentials
- Batch Orchestrator → Progress History: reads progress
- Batch Orchestrator → Contact Workbook: loads workbook
- Batch Orchestrator → Batch Selection: selects rows
- Batch Orchestrator → Personalized Email: formats each email
- Personalized Email → Template And Profile: fills template
- Batch Orchestrator → SMTP Sender: sends message
- SMTP Sender → Resume PDF: reads attachment
- SMTP Sender → Gmail SMTP: sends via SMTP
- Batch Orchestrator → Progress History: updates progress
- Batch Orchestrator → Randomized Delay: waits between sends