Bulk Email Sender

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

pip install bulk-email-sender

Usage

CLI

# Run the campaign (reads config.json from the current directory)
bulk-email-sender

# Reset progress state and start over
bulk-email-sender --reset

# Or run as a module
python -m bulk_email_sender [--reset]

Programmatic

The library never configures logging handlers — it only emits log records via the standard logging module. Set up your own handlers before calling run():

import logging
from bulk_email_sender import BulkEmailSender

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    handlers=[
        logging.FileHandler("/var/log/campaign.log", encoding="utf-8"),
        logging.StreamHandler(),
    ],
)

body = """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.
"""

config = {
    "provider": "gmail",
    "senders": [
        {
            "email": "you@gmail.com",
            "password": "your-app-password",
            "name": "Name",
        },
        {
            "email": "you@yahoo.com",
            "password": "your-app-password-2",
            "name": "Name",
            "provider": "yahoo",
        },
    ],
    "leads_path": "leads.txt",          # .txt or .csv
    "subject": "Your Subject",
    "body": body,
    "attachment_path": "resume.pdf",    # optional, leave "" for none
    "interval_seconds": 60,
    "daily_limit": 450,
    "state_file_path": "/var/log/campaign.json",  # optional, defaults to ./email_state.json
}

BulkEmailSender(config).run()

Note: Environment variables GMAIL_SENDER and GMAIL_APP_PASSWORD override the "senders" list at runtime — useful for CI/containerised deployments.

Configuration Reference

SMTP Provider Presets

Built-in presets automatically configure the host and port for the chosen "provider":

Individual senders can override the global provider by setting their own "provider", "smtp_host", or "smtp_port" keys inside the senders entry. The library will automatically reconnect with the correct credentials when the active sender changes.

Round-Robin Account Rotation

When multiple accounts are listed in "senders", the library rotates through them in round-robin order (1st email → account 1, 2nd email → account 2, 3rd email → account 1, …). If the rotation switches accounts, the SMTP connection is automatically re-established with the new credentials.

Defining Recipient Leads

Plain Text (.txt)

One recipient per line. Name is optional and can be separated by , or ;:

another-recipient@example.com
Jane Doe; jane.doe@example.com

CSV (.csv)

Requires an email column. An optional name column enables personalised greetings:

name,email
Jane,jane.doe@gmail.com
,another-recipient@example.com

When a name is present, the greeting becomes "Hello Jane,". When absent, it defaults to "Hello,".

Email Attachments (Optional)

Set "attachment_path" to a file path to attach it to every email.

• Supported formats: Any file type (.pdf, .docx, .xlsx, .zip, …).
• Size limit: Files larger than 25 MB will abort the campaign before it starts.
• Missing files: If the path does not exist, the campaign is aborted with an error.
• No attachment: Leave "attachment_path": "" or omit the key entirely.