postiee 0.1.0

A minimal Python client for the Postmark API

Postie

A minimal Python client for the Postmark API.

Installation

pip install postie

Quick Start

from postie import PostieClient

# Initialize client
client = PostieClient(server_token="your-postmark-server-token")

# Send a simple email
response = client.send_email(
    from_email="[e-mail]",
    to="[e-mail]",
    subject="Hello from Postie",
    html_body="<h1>Hello!</h1><p>This is a test email.</p>",
    text_body="Hello! This is a test email."
)

print(response)

Features

• ✅ Send single emails
• ✅ Send batch emails (up to 500)
• ✅ Send template-based emails
• ✅ HTML and plain text support
• ✅ CC, BCC, Reply-To
• ✅ Email tagging and metadata
• ✅ Open and link tracking
• ✅ Type hints
• ✅ Minimal dependencies (only requests)

Usage

Send Email

client.send_email(
    from_email="[e-mail]",
    to="[e-mail]",
    subject="Welcome!",
    html_body="<h1>Welcome to our platform</h1>",
    text_body="Welcome to our platform",
    tag="onboarding",
    track_opens=True
)

Send Batch Emails

emails = [
    {
        "From": "[e-mail]",
        "To": "[e-mail]",
        "Subject": "Hello User 1",
        "HtmlBody": "<p>Hello User 1</p>"
    },
    {
        "From": "[e-mail]",
        "To": "[e-mail]",
        "Subject": "Hello User 2",
        "HtmlBody": "<p>Hello User 2</p>"
    }
]

responses = client.send_batch(emails)

Send Template Email

client.send_template_email(
    from_email="[e-mail]",
    to="[e-mail]",
    template_id=123456,
    template_model={
        "name": "John Doe",
        "action_url": "https://example.com/verify"
    }
)

Django Integration

Option 1: Use Django Email Backend (Recommended)

Configure Postie as your Django email backend:

# settings.py
EMAIL_BACKEND = 'postie.django_backend.PostieEmailBackend'
POSTMARK_SERVER_TOKEN = os.getenv('POSTMARK_SERVER_TOKEN')
DEFAULT_FROM_EMAIL = '[e-mail]'

Then use Django's standard email functions:

from django.core.mail import send_mail, EmailMultiAlternatives

# Simple email
send_mail(
    subject='Welcome!',
    message='Welcome to our platform',
    from_email='[e-mail]',
    recipient_list=['[e-mail]'],
)

# HTML email
email = EmailMultiAlternatives(
    subject='Welcome!',
    body='Welcome to our platform',
    from_email='[e-mail]',
    to=['[e-mail]'],
)
email.attach_alternative('<h1>Welcome!</h1>', "text/html")
email.send()

Option 2: Use PostieClient Directly

# utils/email.py
from postie import PostieClient
from django.conf import settings

postmark = PostieClient(server_token=settings.POSTMARK_SERVER_TOKEN)

def send_welcome_email(user_email, user_name):
    postmark.send_email(
        from_email="[e-mail]",
        to=user_email,
        subject=f"Welcome {user_name}!",
        html_body=f"<h1>Welcome {user_name}!</h1>",
        text_body=f"Welcome {user_name}!"
    )

Error Handling

from postie import PostieClient, PostieAPIError, PostieError

try:
    client.send_email(...)
except PostieAPIError as e:
    print(f"API Error: {e}")
    print(f"Error Code: {e.error_code}")
    print(f"Status Code: {e.status_code}")
except PostieError as e:
    print(f"Client Error: {e}")

Requirements

• Python 3.7+
• requests

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Links

• Postmark API Documentation
• GitHub Repository