mailer-sdk 1.0.0

A simple, production-ready Python SDK for sending emails via SMTP

📧 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="[e-mail]", password="your-app-password") as mailer:
    mailer.send(
        to      = "[e-mail]",
        subject = "Hello!",
        body    = "Hey, this was sent using mailer-sdk!"
    )

---

Environment Variables (Recommended)

Instead of hardcoding credentials, use environment variables:

export MAILER_EMAIL=[e-mail]
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="[e-mail]", subject="Hi", body="Hello!")

---

Features

Method	Description
send()	Send plain text or HTML email
send_html()	Shortcut for HTML emails
send_bulk()	Send individually to multiple recipients
send_template()	Send HTML with {{placeholder}} fill-in
send_with_retry()	Auto-retry with exponential backoff

---

Usage Examples

Plain Text

mailer.send(
    to      = "[e-mail]",
    subject = "Hello!",
    body    = "Plain text email."
)

HTML Email

mailer.send_html(
    to      = "[e-mail]",
    subject = "Welcome!",
    body    = "<h1>Hello!</h1><p>This is an <b>HTML</b> email.</p>"
)

With CC, BCC, and Attachment

mailer.send(
    to          = "[e-mail]",
    subject     = "Report",
    body        = "Please find the report attached.",
    cc          = ["[e-mail]"],
    bcc         = ["[e-mail]"],
    attachments = ["report.pdf"]
)

Bulk Send

result = mailer.send_bulk(
    recipients = ["[e-mail]", "[e-mail]", "[e-mail]"],
    subject    = "Newsletter",
    body       = "Hello, here is this month's update!"
)
print(f"Sent {result['sent']}/{result['total']}")

Template Email

mailer.send_template(
    to       = "[e-mail]",
    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          = "[e-mail]",
    subject     = "Important",
    body        = "Please read this.",
    max_retries = 3,   # default
    backoff     = 1    # 1s → 2s → 4s
)

---

Supported Providers

Provider	Value
Gmail	"gmail"
Outlook	"outlook"
Yahoo	"yahoo"

# Outlook example
mailer = Mailer(email="[e-mail]", 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="[e-mail]", password="wrong-pass") as mailer:
        mailer.send(to="[e-mail]", 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

MIT © Your Name