# eghost1/automailsender architecture

> Architecture diagram of the GitHub repository eghost1/automailsender, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eghost1/automailsender
- Repository: https://github.com/eghost1/automailsender

## Overview

##### Project Type and Purpose
- AutoMailSender is a command‑line Python tool (an open‑source utility) for automated bulk email sending via Gmail.
- It reads recipient lists (CSV or TXT), personalizes a template, sends mail through Gmail’s SMTP, and logs sent messages.

##### File Structure Analysis
- Top‐level script and config:
- mail_sender.py – main entry point & orchestrator
- config.py – holds Gmail credentials & settings
- Data files:
- email_template.txt – message template with placeholders
- recipients.csv / recipients.txt – input lists
- sent_emails.txt (runtime) – log of sent mails
- Support:
- requirements.txt – dependencies (pandas, smtplib, email)
- .gitignore – ignores config, logs, etc.

##### Core Components
a. Config Loader
- Reads config.py for EMAIL_ORIGIN, EMAIL_PASSWORD
- Supplies credentials to the SMTP client
b. Recipient Parser
- Branch A: CSV parser (pandas)
- Branch B: TXT parser (regex or line parsing)
c. Template Engine
- Reads email_template.txt
- Substitutes [NOMBRE] with recipient data
d. Mail Sender (SMTP Client)
- Uses smtplib & email libraries
- Connects to Gmail SMTP (smtp.gmail.com)
- Authentication via app password
e. Logger
- Appends timestamp, recipient name & email to sent_emails.txt

##### Component Interactions & Data Flow
- At startup, Config Loader → initializes SMTP client
- User selects input file → Recipient Parser reads list → emits list of {name, email}
- For each recipient:
- Template Engine + recipient data → generates personalized email
- Mail Sender → submits email to Gmail SMTP → success/failure response
- Logger → writes entry to sent_emails.txt

##### Architectural Patterns & Principles
- Separation of Concerns: parsing, templating, sending, logging each in its own module/function
- Single Responsibility: each component does one job
- Extensibility Point: easily swap parsers or add new mail providers by conforming to a common interface

##### Technologies & External Services
- Python 3.6+
- pandas (CSV parsing)
- smtplib & email (SMTP client)
- Gmail SMTP service (external)
- Local file system for templates, recipient lists, logs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Modules
    ConfigLoader["Config Loader"]:::internal
    click ConfigLoader "https://github.com/eghost1/automailsender/blob/main/config.py"
    RecipientParser["Recipient Parser"]:::internal
    click RecipientParser "https://github.com/eghost1/automailsender/blob/main/mail_sender.py"
    TemplateEngine["Template Engine"]:::internal
    click TemplateEngine "https://github.com/eghost1/automailsender/blob/main/mail_sender.py"
    MailSender["Mail Sender (SMTP Client)"]:::internal
    click MailSender "https://github.com/eghost1/automailsender/blob/main/mail_sender.py"
    Logger["Logger"]:::internal
    click Logger "https://github.com/eghost1/automailsender/blob/main/sent_emails.txt"

    %% Data Stores
    RecipientsFile["recipients.csv / recipients.txt"]:::file
    TemplateFile["email_template.txt"]:::file
    click TemplateFile "https://github.com/eghost1/automailsender/blob/main/email_template.txt"
    LogFile["sent_emails.txt"]:::file
    click LogFile "https://github.com/eghost1/automailsender/blob/main/sent_emails.txt"

    %% External Services
    GmailSMTP["Gmail SMTP"]:::external

    %% User
    User["User"]:::external

    %% Data Flow
    User -->|"selects input file"| RecipientParser
    RecipientsFile -->|"reads list"| RecipientParser
    ConfigLoader -->|"initializes SMTP client"| MailSender
    RecipientParser -->|"emits recipients"| TemplateEngine
    TemplateFile -->|"provides template"| TemplateEngine
    TemplateEngine -->|"generates email"| MailSender
    MailSender -->|"sends email"| GmailSMTP
    GmailSMTP -->|"response"| MailSender
    MailSender -->|"logs entry"| Logger
    Logger --> LogFile

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef file fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px;
```
