Email Automation

Provides patterns for sending automated emails in invoice workflows.

Basic Email Sending

import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart

def send_email(
    smtp_host: str,
    smtp_port: int,
    username: str,
    password: str,
    to_email: str,
    subject: str,
    body: str,
    from_email: str = None
):
    """
    Send a basic text email.

    Usage:
        send_email(
            smtp_host="smtp.gmail.com",
            smtp_port=587,
            username="your@email.com",
            password="app_password",
            to_email="recipient@email.com",
            subject="Invoice Ready",
            body="Your invoice is attached."
        )
    """
    msg = MIMEMultipart()
    msg["From"] = from_email or username
    msg["To"] = to_email
    msg["Subject"] = subject
    msg.attach(MIMEText(body, "plain"))

    with smtplib.SMTP(smtp_host, smtp_port) as server:
        server.starttls()
        server.login(username, password)
        server.send_message(msg)

HTML Emails

def send_html_email(
    smtp_host: str,
    smtp_port: int,
    username: str,
    password: str,
    to_email: str,
    subject: str,
    html_body: str,
    plain_body: str = None
):
    """Send HTML email with optional plain text fallback."""
    msg = MIMEMultipart("alternative")
    msg["From"] = username
    msg["To"] = to_email
    msg["Subject"] = subject

    if plain_body:
        msg.attach(MIMEText(plain_body, "plain"))
    msg.attach(MIMEText(html_body, "html"))

    with smtplib.SMTP(smtp_host, smtp_port) as server:
        server.starttls()
        server.login(username, password)
        server.send_message(msg)

Emails with Attachments

from email.mime.base import MIMEBase
from email import encoders
from pathlib import Path

def send_email_with_attachment(
    smtp_host: str,
    smtp_port: int,
    username: str,
    password: str,
    to_email: str,
    subject: str,
    body: str,
    attachment_path: str
):
    """
    Send email with file attachment.

    Usage:
        send_email_with_attachment(
            smtp_host="smtp.gmail.com",
            smtp_port=587,
            username="your@email.com",
            password="app_password",
            to_email="recipient@email.com",
            subject="Invoice Attached",
            body="Please find the invoice attached.",
            attachment_path="./invoices/INV-001.pdf"
        )
    """
    msg = MIMEMultipart()
    msg["From"] = username
    msg["To"] = to_email
    msg["Subject"] = subject
    msg.attach(MIMEText(body, "plain"))

    # Attach file
    path = Path(attachment_path)
    with open(path, "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={path.name}")
    msg.attach(part)

    with smtplib.SMTP(smtp_host, smtp_port) as server:
        server.starttls()
        server.login(username, password)
        server.send_message(msg)

Invoice Notification Template

def send_invoice_notification(
    smtp_config: dict,
    recipient: str,
    invoice_number: str,
    amount: float,
    due_date: str,
    attachment_path: str = None
):
    """
    Send invoice notification email.

    Usage:
        send_invoice_notification(
            smtp_config={
                "host": "smtp.gmail.com",
                "port": 587,
                "username": "billing@company.com",
                "password": "app_password"
            },
            recipient="customer@email.com",
            invoice_number="INV-2024-001",
            amount=1500.00,
            due_date="2024-02-15"
        )
    """
    subject = f"Invoice {invoice_number} - Payment Due"
    body = f'''
Dear Customer,

Your invoice {invoice_number} for ${amount:,.2f} is now available.

Payment is due by {due_date}.

Please contact us if you have any questions.

Best regards,
Billing Department
'''

    if attachment_path:
        send_email_with_attachment(
            smtp_config["host"],
            smtp_config["port"],
            smtp_config["username"],
            smtp_config["password"],
            recipient,
            subject,
            body,
            attachment_path
        )
    else:
        send_email(
            smtp_config["host"],
            smtp_config["port"],
            smtp_config["username"],
            smtp_config["password"],
            recipient,
            subject,
            body
        )

Batch Email Sending

from typing import List, Dict
import time

def send_batch_emails(
    smtp_config: dict,
    recipients: List[Dict],
    subject_template: str,
    body_template: str,
    delay_seconds: float = 1.0
):
    """
    Send batch emails with personalization.

    Usage:
        recipients = [
            {"email": "customer1@email.com", "name": "John", "invoice_no": "INV-001"},
            {"email": "customer2@email.com", "name": "Jane", "invoice_no": "INV-002"}
        ]
        send_batch_emails(
            smtp_config,
            recipients,
            subject_template="Invoice {invoice_no} Ready",
            body_template="Dear {name},\n\nYour invoice {invoice_no} is ready."
        )
    """
    for recipient in recipients:
        subject = subject_template.format(**recipient)
        body = body_template.format(**recipient)

        send_email(
            smtp_config["host"],
            smtp_config["port"],
            smtp_config["username"],
            smtp_config["password"],
            recipient["email"],
            subject,
            body
        )

        time.sleep(delay_seconds)  # Rate limiting

Helper Script

Use helper.py for the EmailSender class with template support and error handling.