bulk-email-sender 0.2.0__tar.gz

bulk_email_sender-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Oliveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bulk_email_sender-0.2.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

bulk_email_sender-0.2.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: bulk-email-sender
+Version: 0.2.0
+Summary: A modular, state-persisting mass email sender library using SMTP — supports multi-account rotation, daily limits, and attachments
+Author-email: Jeferson Oliveira Madeira <jeffoliveira977@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jeffoliveira977/Bulk-email-sender
+Project-URL: Repository, https://github.com/jeffoliveira977/Bulk-email-sender
+Project-URL: Issues, https://github.com/jeffoliveira977/Bulk-email-sender/issues
+Project-URL: Changelog, https://github.com/jeffoliveira977/Bulk-email-sender/releases
+Keywords: email,smtp,bulk,sender,automation,newsletter,mass-email
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: English
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Bulk Email Sender
+
+[![PyPI version](https://img.shields.io/pypi/v/bulk-email-sender?color=blue)](https://pypi.org/project/bulk-email-sender/)
+[![Python](https://img.shields.io/pypi/pyversions/bulk-email-sender)](https://pypi.org/project/bulk-email-sender/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A modular, robust, and state-persisting mass email sender library for Python. It supports multiple sender accounts with round-robin rotation, personalized recipient names, automatic daily safety caps, cooldown intervals between emails, attachments, and automatic daily counter resets.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+pip install bulk-email-sender
+
+# 2. Initialise workspace — creates a config.json template in the current directory
+bulk-email-sender
+
+# 3. Edit config.json with your credentials, leads file, subject, body, etc.
+
+# 4. Run the campaign
+bulk-email-sender
+
+# 5. (Optional) Reset progress state and start over
+bulk-email-sender --reset
+```
+
+You can also run the package directly as a Python module:
+
+```bash
+python -m bulk_email_sender [--reset]
+```
+
+Or import and drive it programmatically:
+
+```python
+from bulk_email_sender import BulkEmailSender
+
+config = {
+    "provider": "gmail",
+    "senders": [{"email": "you@gmail.com", "password": "app-password", "name": "You"}],
+    "leads_path": "leads.txt",
+    "subject": "Hello!",
+    "body_path": "body.txt",
+    "attachment_path": "resume.pdf",   # optional
+    "interval_seconds": 60,
+    "daily_limit": 450,
+}
+
+BulkEmailSender(config).run()
+```
+
+
+
+## Configuration
+
+Configurations are loaded from `config.json` in the root workspace.
+
+### Example `config.json`
+
+```json
+{
+  "provider": "gmail",
+  "senders": [
+    {
+      "email": "sender1@gmail.com",
+      "password": "app-password-1",
+      "name": "Marcos (Account 1)"
+    },
+    {
+      "email": "sender2@yahoo.com",
+      "password": "app-password-2",
+      "name": "Marcos (Account 2)",
+      "provider": "yahoo"
+    }
+  ],
+  "leads_path": "leads.txt",
+  "subject": "Your Subject Here",
+  "body_path": "body.txt",
+  "attachment_path": "document.pdf",
+  "interval_seconds": 60,
+  "daily_limit": 450
+}
+```
+
+*Note: Environment variables `GMAIL_SENDER` and `GMAIL_APP_PASSWORD` will override `"senders"` in the configuration on execution if they are set.*
+
+---
+
+## Per-Sender Provider Overrides
+
+Individually configured senders in the `"senders"` list can override the global campaign provider by defining their own `"provider"`, `"smtp_host"`, or `"smtp_port"` keys. 
+
+If a sender specifies a provider override, the library automatically closes the active connection and establishes a session with the correct hostname/port for the new provider.
+
+### SMTP Providers Presets
+
+Built-in presets automatically configure the host and port depending on your chosen `"provider"`:
+
+| Provider Name | Default Host | Port |
+| :--- | :--- | :--- |
+| `"gmail"` | `smtp.gmail.com` | `587` |
+| `"yahoo"` | `smtp.mail.yahoo.com` | `587` |
+| `"icloud"` | `smtp.mail.me.com` | `587` |
+| `"ZOHO"` | `smtp.zoho.com` | `587` |
+| `"GMX"` | `smtp.gmx.com` | `587` |
+| `"YANDEX"` | `smtp.yandex.com` | `587` |
+| `"AOL"` | `smtp.aol.com` | `587` |
+---
+
+## Round-Robin Account Rotation
+
+The library automatically rotates through the configured accounts in `"senders"` round-robin style (1st email from account 1, 2nd email from account 2, 3rd from account 1, etc.).
+
+If a new account is chosen in the rotation, the SMTP connection automatically disconnects and re-establishes session credentials to make sending look natural and stay within safety boundaries.
+
+---
+
+## Customizing Email Body
+
+The email body is loaded dynamically from the file specified in the `"body_path"` key (default: `body.txt`). 
+Any newlines (`\n`) in `body.txt` are automatically converted to HTML line break tags (`<br>`) before sending.
+
+### Example `body.txt`
+
+```text
+I hope this message finds you well.
+
+I am writing to express my interest in potential job opportunities in IT. Please find attached my curriculum vitae for your consideration.
+
+Thank you for your time and review.
+```
+
+---
+
+## Email Attachments (Optional)
+
+An optional file attachment can be sent with every email by configuring the `"attachment_path"` key in `config.json`.
+
+*   **Supported Formats:** Any file type (e.g., `.pdf`, `.docx`, `.xlsx`, `.zip`). The sender automatically encodes and attaches it using standard MIME Base64 encoding.
+*   **Size Limit Validation:** The program checks the file size before starting the campaign. If the attachment exceeds the **25 MB limit**, the campaign is aborted to prevent failures.
+*   **Missing Files:** If the specified file does not exist, the campaign will abort immediately with an error log.
+*   **No Attachment:** If you do not want to send an attachment, simply leave `"attachment_path": ""` as an empty string or omit it.
+
+---
+
+## Auto-Generated Files
+
+The following files are generated automatically in the execution directory and do not need to be configured:
+*   `email_state.json`: Tracks campaign progress, daily counts, and failed indexes. Allows resuming if interrupted.
+*   `email_sender.log`: Logs sending statuses, warnings, and errors.
+
+---
+
+## Defining Recipient Leads (TXT or CSV)
+
+### 1. Plain Text Format (`.txt`)
+Name and email separated by a comma (`,`) or semicolon (`;`). The name is optional:
+
+```text
+another-recipient@example.com      # Generic greeting: "Hello,"
+Jane Doe; jane.doe@example.com     # Personalised greeting: "Hello Jane Doe,"
+```
+
+### 2. CSV Format (`.csv`)
+Requires an `email` column, and optional `name` column:
+
+```csv
+name,email
+Jane,jane.doe@gmail.com
+,another-recipient@example.com
+```
+
+If the name is missing, it defaults to a generic `"Hello,"` greeting.
+
+---

bulk_email_sender-0.2.0/README.md

@@ -0,0 +1,177 @@
+# Bulk Email Sender
+
+[![PyPI version](https://img.shields.io/pypi/v/bulk-email-sender?color=blue)](https://pypi.org/project/bulk-email-sender/)
+[![Python](https://img.shields.io/pypi/pyversions/bulk-email-sender)](https://pypi.org/project/bulk-email-sender/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A modular, robust, and state-persisting mass email sender library for Python. It supports multiple sender accounts with round-robin rotation, personalized recipient names, automatic daily safety caps, cooldown intervals between emails, attachments, and automatic daily counter resets.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+pip install bulk-email-sender
+
+# 2. Initialise workspace — creates a config.json template in the current directory
+bulk-email-sender
+
+# 3. Edit config.json with your credentials, leads file, subject, body, etc.
+
+# 4. Run the campaign
+bulk-email-sender
+
+# 5. (Optional) Reset progress state and start over
+bulk-email-sender --reset
+```
+
+You can also run the package directly as a Python module:
+
+```bash
+python -m bulk_email_sender [--reset]
+```
+
+Or import and drive it programmatically:
+
+```python
+from bulk_email_sender import BulkEmailSender
+
+config = {
+    "provider": "gmail",
+    "senders": [{"email": "you@gmail.com", "password": "app-password", "name": "You"}],
+    "leads_path": "leads.txt",
+    "subject": "Hello!",
+    "body_path": "body.txt",
+    "attachment_path": "resume.pdf",   # optional
+    "interval_seconds": 60,
+    "daily_limit": 450,
+}
+
+BulkEmailSender(config).run()
+```
+
+
+
+## Configuration
+
+Configurations are loaded from `config.json` in the root workspace.
+
+### Example `config.json`
+
+```json
+{
+  "provider": "gmail",
+  "senders": [
+    {
+      "email": "sender1@gmail.com",
+      "password": "app-password-1",
+      "name": "Marcos (Account 1)"
+    },
+    {
+      "email": "sender2@yahoo.com",
+      "password": "app-password-2",
+      "name": "Marcos (Account 2)",
+      "provider": "yahoo"
+    }
+  ],
+  "leads_path": "leads.txt",
+  "subject": "Your Subject Here",
+  "body_path": "body.txt",
+  "attachment_path": "document.pdf",
+  "interval_seconds": 60,
+  "daily_limit": 450
+}
+```
+
+*Note: Environment variables `GMAIL_SENDER` and `GMAIL_APP_PASSWORD` will override `"senders"` in the configuration on execution if they are set.*
+
+---
+
+## Per-Sender Provider Overrides
+
+Individually configured senders in the `"senders"` list can override the global campaign provider by defining their own `"provider"`, `"smtp_host"`, or `"smtp_port"` keys. 
+
+If a sender specifies a provider override, the library automatically closes the active connection and establishes a session with the correct hostname/port for the new provider.
+
+### SMTP Providers Presets
+
+Built-in presets automatically configure the host and port depending on your chosen `"provider"`:
+
+| Provider Name | Default Host | Port |
+| :--- | :--- | :--- |
+| `"gmail"` | `smtp.gmail.com` | `587` |
+| `"yahoo"` | `smtp.mail.yahoo.com` | `587` |
+| `"icloud"` | `smtp.mail.me.com` | `587` |
+| `"ZOHO"` | `smtp.zoho.com` | `587` |
+| `"GMX"` | `smtp.gmx.com` | `587` |
+| `"YANDEX"` | `smtp.yandex.com` | `587` |
+| `"AOL"` | `smtp.aol.com` | `587` |
+---
+
+## Round-Robin Account Rotation
+
+The library automatically rotates through the configured accounts in `"senders"` round-robin style (1st email from account 1, 2nd email from account 2, 3rd from account 1, etc.).
+
+If a new account is chosen in the rotation, the SMTP connection automatically disconnects and re-establishes session credentials to make sending look natural and stay within safety boundaries.
+
+---
+
+## Customizing Email Body
+
+The email body is loaded dynamically from the file specified in the `"body_path"` key (default: `body.txt`). 
+Any newlines (`\n`) in `body.txt` are automatically converted to HTML line break tags (`<br>`) before sending.
+
+### Example `body.txt`
+
+```text
+I hope this message finds you well.
+
+I am writing to express my interest in potential job opportunities in IT. Please find attached my curriculum vitae for your consideration.
+
+Thank you for your time and review.
+```
+
+---
+
+## Email Attachments (Optional)
+
+An optional file attachment can be sent with every email by configuring the `"attachment_path"` key in `config.json`.
+
+*   **Supported Formats:** Any file type (e.g., `.pdf`, `.docx`, `.xlsx`, `.zip`). The sender automatically encodes and attaches it using standard MIME Base64 encoding.
+*   **Size Limit Validation:** The program checks the file size before starting the campaign. If the attachment exceeds the **25 MB limit**, the campaign is aborted to prevent failures.
+*   **Missing Files:** If the specified file does not exist, the campaign will abort immediately with an error log.
+*   **No Attachment:** If you do not want to send an attachment, simply leave `"attachment_path": ""` as an empty string or omit it.
+
+---
+
+## Auto-Generated Files
+
+The following files are generated automatically in the execution directory and do not need to be configured:
+*   `email_state.json`: Tracks campaign progress, daily counts, and failed indexes. Allows resuming if interrupted.
+*   `email_sender.log`: Logs sending statuses, warnings, and errors.
+
+---
+
+## Defining Recipient Leads (TXT or CSV)
+
+### 1. Plain Text Format (`.txt`)
+Name and email separated by a comma (`,`) or semicolon (`;`). The name is optional:
+
+```text
+another-recipient@example.com      # Generic greeting: "Hello,"
+Jane Doe; jane.doe@example.com     # Personalised greeting: "Hello Jane Doe,"
+```
+
+### 2. CSV Format (`.csv`)
+Requires an `email` column, and optional `name` column:
+
+```csv
+name,email
+Jane,jane.doe@gmail.com
+,another-recipient@example.com
+```
+
+If the name is missing, it defaults to a generic `"Hello,"` greeting.
+
+---

bulk_email_sender-0.2.0/bulk_email_sender/__init__.py

@@ -0,0 +1,18 @@
+from .lead import Lead
+from .state import SendState, StateManager
+from .loader import LeadLoader
+from .builder import EmailBuilder
+from .sender import SMTPSender
+from .bulk_sender import BulkEmailSender
+from .provider import SMTPProvider
+
+__all__ = [
+    "Lead",
+    "SendState",
+    "StateManager",
+    "LeadLoader",
+    "EmailBuilder",
+    "SMTPSender",
+    "BulkEmailSender",
+    "SMTPProvider",
+]

bulk_email_sender-0.2.0/bulk_email_sender/__main__.py

@@ -0,0 +1,127 @@
+"""
+bulk_email_sender CLI entrypoint.
+
+Can be invoked as:
+    python -m bulk_email_sender [--reset]
+    bulk-email-sender [--reset]
+
+Loads configuration from config.json in the current working directory,
+initialises logging, and runs the BulkEmailSender campaign loop.
+"""
+
+import os
+import sys
+import json
+import logging
+from pathlib import Path
+
+from . import BulkEmailSender
+
+# ============================================================
+# LOGGING
+# ============================================================
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    handlers=[
+        logging.FileHandler("email_sender.log", encoding="utf-8"),
+        logging.StreamHandler(),
+    ],
+)
+logger = logging.getLogger(__name__)
+
+
+# ============================================================
+# CONFIGURATION LOADER
+# ============================================================
+
+def load_config(config_path: str = "config.json") -> dict:
+    """Load campaign configuration from *config_path*.
+
+    If the file does not exist a default template is created in the current
+    working directory and the process exits with code 0 so the user can fill
+    in their credentials before re-running.
+    """
+    path = Path(config_path)
+
+    if not path.exists():
+        default_config = {
+            "provider": "gmail",
+            "senders": [
+                {
+                    "email": "your-email@gmail.com",
+                    "password": "your-app-password",
+                    "name": "Your Name",
+                }
+            ],
+            "leads_path": "leads.txt",
+            "subject": "Your Subject",
+            "body_path": "body.txt",
+            "attachment_path": "",
+            "interval_seconds": 60,
+            "daily_limit": 450,
+        }
+        try:
+            path.write_text(
+                json.dumps(default_config, indent=2, ensure_ascii=False),
+                encoding="utf-8",
+            )
+            logger.info(
+                f"Created default configuration template at '{config_path}'. "
+                "Please fill in your credentials and re-run."
+            )
+        except Exception as exc:
+            logger.error(f"Failed to create default configuration file: {exc}")
+        sys.exit(0)
+
+    try:
+        config = json.loads(path.read_text(encoding="utf-8"))
+
+        # Allow environment-variable overrides for CI / containerised runs
+        env_email = os.environ.get("GMAIL_SENDER")
+        env_password = os.environ.get("GMAIL_APP_PASSWORD")
+
+        if env_email and env_password:
+            config["senders"] = [
+                {
+                    "email": env_email,
+                    "password": env_password,
+                    "name": config.get("senders", [{}])[0].get("name") or "Sender",
+                }
+            ]
+
+        return config
+
+    except Exception as exc:
+        logger.error(f"Failed to load configuration file '{config_path}': {exc}")
+        sys.exit(1)
+
+
+# ============================================================
+# MAIN ENTRYPOINT
+# ============================================================
+
+def main() -> None:
+    """Entry point registered in pyproject.toml console_scripts."""
+    config = load_config()
+
+    # Reset progress state when --reset flag is passed
+    if "--reset" in sys.argv:
+        state_file = config.get("state_file_path") or "email_state.json"
+        state_path = Path(state_file)
+        if state_path.exists():
+            try:
+                state_path.unlink()
+                logger.info(f"Progress state '{state_file}' has been reset.")
+            except Exception as exc:
+                logger.error(f"Failed to reset state file: {exc}")
+        else:
+            logger.info("No active progress state found to reset.")
+
+    sender = BulkEmailSender(config)
+    sender.run()
+
+
+if __name__ == "__main__":
+    main()

bulk_email_sender-0.2.0/bulk_email_sender/builder.py

@@ -0,0 +1,114 @@
+import logging
+from pathlib import Path
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from email.mime.base import MIMEBase
+from email import encoders
+from .lead import Lead
+
+logger = logging.getLogger(__name__)
+
+class EmailBuilder:
+    """Builds standard/multipart email messages based on a hardcoded template."""
+    
+    TEMPLATE = """\
+<html>
+<head>
+    <style>
+        body {{
+            font-family: Arial, sans-serif;
+            font-size: 14px;
+            line-height: 1.6;
+            color: #333333;
+        }}
+        .signature {{
+            margin-top: 20px;
+        }}
+    </style>
+</head>
+<body>
+    {greeting_part}
+    
+    <div>
+        {body_text}
+    </div>
+    
+    <div class="signature">
+        <p>Best regards,<br>
+        <strong>{sender_name}</strong></p>
+    </div>
+</body>
+</html>
+"""
+
+    def __init__(self, config: dict):
+        self.config = config
+        self.subject = config.get("subject", "No Subject")
+        self.sender_name = config.get("sender_name", "")
+
+        attachment_path = config.get("attachment_path")
+        if attachment_path and str(attachment_path).strip():
+            self.attachment_path = str(attachment_path).strip()
+        else:
+            self.attachment_path = None
+
+        body_text = config.get("body_text", "")
+        body_path = config.get("body_path")
+        if body_path:
+            p = Path(body_path)
+            if p.exists():
+                body_text = p.read_text(encoding="utf-8")
+            else:
+                logger.warning(f"Body file not found at: {body_path}. Using default body text.")
+        self.body_text = body_text
+
+    def build(self, lead: Lead, sender_credentials: dict) -> MIMEMultipart:
+        msg = MIMEMultipart("mixed")
+        msg["Subject"] = self.subject
+        
+        sender_name = sender_credentials.get("name") or self.sender_name
+        sender_email = sender_credentials.get("email", "")
+        
+        msg["From"] = f"{sender_name} <{sender_email}>"
+        msg["To"] = lead.email
+
+        if lead.name:
+            recipient_name = lead.name.strip().title()
+            greeting_part = f"<p>Hello {recipient_name},</p>"
+        else:
+            greeting_part = "<p>Hello,</p>"
+
+        body_html = self.body_text
+        if "<p>" not in body_html and "<br>" not in body_html:
+            body_html = body_html.replace("\n", "<br>\n")
+
+        html_content = self.TEMPLATE.format(
+            greeting_part=greeting_part,
+            body_text=body_html,
+            sender_name=sender_name
+        )
+
+        body_part = MIMEMultipart("alternative")
+        body_part.attach(MIMEText(html_content, "html", "utf-8"))
+        msg.attach(body_part)
+
+        if self.attachment_path:
+            self._attach_file(msg)
+
+        return msg
+
+    def _attach_file(self, msg: MIMEMultipart) -> None:
+        if not self.attachment_path:
+            return
+        
+        p = Path(self.attachment_path)
+        if not p.exists():
+            raise FileNotFoundError(f"Attachment not found: {self.attachment_path}")
+
+        with open(p, "rb") as f:
+            part = MIMEBase("application", "octet-stream")
+            part.set_payload(f.read())
+
+        encoders.encode_base64(part)
+        part.add_header("Content-Disposition", f'attachment; filename="{p.name}"')
+        msg.attach(part)