mailbreeze 0.2.3

Official Python SDK for MailBreeze email platform

MailBreeze Python SDK

The official Python SDK for the MailBreeze email platform.

Features

• Full async support - Built on httpx for modern async/await patterns
• Type-safe - Complete type hints with Pydantic models
• Automatic retries - Built-in retry logic with exponential backoff
• Python 3.10+ - Modern Python with native type syntax

Installation

pip install mailbreeze

Quick Start

import asyncio
from mailbreeze import MailBreeze

async def main():
    client = MailBreeze(api_key="sk_live_xxx")

    # Send an email
    result = await client.emails.send(
        from_="[e-mail]",
        to="[e-mail]",
        subject="Welcome!",
        html="<h1>Welcome to our platform!</h1>",
    )
    print(result.id)

asyncio.run(main())

Resources

Emails

# Send an email
result = await client.emails.send(
    from_="[e-mail]",
    to="[e-mail]",
    subject="Hello",
    html="<p>Hello World!</p>",
)

# Send with a template
result = await client.emails.send(
    from_="[e-mail]",
    to=["[e-mail]", "[e-mail]"],
    template_id="welcome-template",
    variables={"name": "John", "plan": "Pro"},
)

# List emails
emails = await client.emails.list(status="delivered", page=1, limit=20)

# Get email details
email = await client.emails.get("email_xxx")

# Get statistics
stats = await client.emails.stats()
print(stats.success_rate)  # 100.0
print(stats.total)  # 71

Contact Lists

# Create a list
list_ = await client.lists.create(
    name="Newsletter Subscribers",
    description="Weekly newsletter recipients",
)

# List all lists
lists = await client.lists.list()

# Get list stats
stats = await client.lists.stats("list_xxx")

Contacts

# Get contacts for a list
contacts = client.contacts("list_xxx")

# Create a contact
contact = await contacts.create(
    email="[e-mail]",
    first_name="John",
    last_name="Doe",
    custom_fields={"company": "Acme Inc"},
)

# List contacts
result = await contacts.list(status="active", page=1, limit=50)

# Update a contact
updated = await contacts.update("contact_xxx", first_name="Jane")

# Delete a contact
await contacts.delete("contact_xxx")

Email Verification

# Verify a single email
result = await client.verification.verify({"email": "[e-mail]"})
print(result.is_valid)  # True

# Batch verification
batch = await client.verification.batch(
    emails=["[e-mail]", "[e-mail]"]
)

# Check batch status
status = await client.verification.get(batch.verification_id)

# Get verification statistics
stats = await client.verification.stats()
print(stats.total_valid)  # 150
print(stats.valid_percentage)  # 95.5

Error Handling

from mailbreeze import (
    MailBreeze,
    MailBreezeError,
    AuthenticationError,
    ValidationError,
    NotFoundError,
    RateLimitError,
    ServerError,
)

try:
    await client.emails.send(...)
except ValidationError as e:
    print(f"Validation failed: {e.message}")
    print(f"Details: {e.details}")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except NotFoundError:
    print("Resource not found")
except ServerError as e:
    print(f"Server error: {e.status_code}")
except MailBreezeError as e:
    print(f"API error: {e.code} - {e.message}")

Requirements

• Python 3.10 or higher
• A MailBreeze API key (get one here)

License

MIT