📧 mailer-sdk

A simple, production-ready Python SDK for sending emails via SMTP. Zero dependencies. Gmail, Outlook, and Yahoo supported out of the box.

Installation

pip install mailer-sdk

Quick Start

from mailer_sdk import Mailer

with Mailer(email="you@gmail.com", password="your-app-password") as mailer:
    mailer.send(
        to      = "friend@example.com",
        subject = "Hello!",
        body    = "Hey, this was sent using mailer-sdk!"
    )

Environment Variables (Recommended)

Instead of hardcoding credentials, use environment variables:

export MAILER_EMAIL=you@gmail.com
export MAILER_PASSWORD=your-app-password
export MAILER_PROVIDER=gmail   # optional, default is gmail

from mailer_sdk import Mailer

with Mailer() as mailer:   # reads from env automatically
    mailer.send(to="friend@example.com", subject="Hi", body="Hello!")

Features

Usage Examples

Plain Text

mailer.send(
    to      = "friend@example.com",
    subject = "Hello!",
    body    = "Plain text email."
)

HTML Email

mailer.send_html(
    to      = "friend@example.com",
    subject = "Welcome!",
    body    = "<h1>Hello!</h1><p>This is an <b>HTML</b> email.</p>"
)

With CC, BCC, and Attachment

mailer.send(
    to          = "friend@example.com",
    subject     = "Report",
    body        = "Please find the report attached.",
    cc          = ["manager@example.com"],
    bcc         = ["archive@example.com"],
    attachments = ["report.pdf"]
)

Bulk Send

result = mailer.send_bulk(
    recipients = ["a@example.com", "b@example.com", "c@example.com"],
    subject    = "Newsletter",
    body       = "Hello, here is this month's update!"
)
print(f"Sent {result['sent']}/{result['total']}")

Template Email

mailer.send_template(
    to       = "customer@example.com",
    subject  = "Order Confirmed",
    template = "<h2>Hi {{name}}!</h2><p>Order <b>#{{order_id}}</b> confirmed. Total: ${{total}}</p>",
    context  = {"name": "Alice", "order_id": "1042", "total": "59.99"}
)

Retry on Failure

mailer.send_with_retry(
    to          = "friend@example.com",
    subject     = "Important",
    body        = "Please read this.",
    max_retries = 3,   # default
    backoff     = 1    # 1s → 2s → 4s
)

Supported Providers

# Outlook example
mailer = Mailer(email="you@outlook.com", password="pass", provider="outlook")

Gmail App Password Setup

Gmail requires an App Password (not your real password):

1. Go to → myaccount.google.com
2. Security → 2-Step Verification (enable it)
3. Security → App Passwords → Generate
4. Copy the 16-character password
5. Use it as your password above

Error Handling

from mailer_sdk import Mailer, AuthError, SendError, ConnectError, ValidationError

try:
    with Mailer(email="you@gmail.com", password="wrong-pass") as mailer:
        mailer.send(to="friend@example.com", subject="Hi", body="Hello!")

except AuthError as e:
    print(f"Auth failed [{e.code}]: {e.message}")    # bad credentials

except ConnectError as e:
    print(f"Can't connect [{e.code}]: {e.message}")  # server unreachable

except SendError as e:
    print(f"Send failed [{e.code}]: {e.message}")    # delivery failed

except ValidationError as e:
    print(f"Bad input [{e.code}]: {e.message}")      # invalid inputs

Logging

Control SDK verbosity using Python's standard logging:

import logging

# See all SDK activity
logging.getLogger("mailer_sdk").setLevel(logging.DEBUG)

# Quiet mode — only errors
logging.getLogger("mailer_sdk").setLevel(logging.ERROR)

License

DT © Rishabh