sendbase-email 1.0.5

Official Python SDK for the SendBase Email API. Send transactional emails, manage domains, templates, and more.

SendBase Email Python SDK

Official Python SDK for the SendBase Email API. Send transactional emails, manage domains, templates, and more.

Installation

pip install sendbase-email

Quick Start

from sendbase_email import SendBaseClient, SendEmailRequest

# Initialize the client
client = SendBaseClient("your-api-key")

# Send an email
response = client.emails.send(SendEmailRequest(
    from_email="[e-mail]",
    to=["[e-mail]"],
    subject="Hello from SendBase!",
    html_body="<h1>Welcome!</h1><p>This is a test email.</p>"
))

print(f"Message ID: {response.message_id}")
print(f"Status: {response.status_text}")

Async Support

The SDK provides full async support:

import asyncio
from sendbase_email import AsyncSendBaseClient, SendEmailRequest

async def main():
    async with AsyncSendBaseClient("your-api-key") as client:
        response = await client.emails.send(SendEmailRequest(
            from_email="[e-mail]",
            to=["[e-mail]"],
            subject="Hello!",
            html_body="<h1>Welcome!</h1>"
        ))
        print(f"Message ID: {response.message_id}")

asyncio.run(main())

Features

Send Emails

from sendbase_email import SendBaseClient, SendEmailRequest, EmailRecipient

client = SendBaseClient("your-api-key")

# Simple email
response = client.emails.send(SendEmailRequest(
    from_email="[e-mail]",
    to=["[e-mail]"],
    subject="Hello!",
    html_body="<h1>Welcome!</h1>"
))

# With recipient names
response = client.emails.send(SendEmailRequest(
    from_email="[e-mail]",
    from_name="My App",
    to=[EmailRecipient(email="[e-mail]", name="John Doe")],
    subject="Hello John!",
    html_body="<h1>Welcome!</h1>",
    text_body="Welcome!"
))

# With CC, BCC, and reply-to
response = client.emails.send(SendEmailRequest(
    from_email="[e-mail]",
    to=["[e-mail]"],
    cc=["[e-mail]"],
    bcc=["[e-mail]"],
    reply_to="[e-mail]",
    subject="Important Update",
    html_body="<p>Please review...</p>"
))

Using Templates

# Send with a template
response = client.emails.send(SendEmailRequest(
    from_email="[e-mail]",
    to=["[e-mail]"],
    subject="Welcome!",
    template_id="your-template-id",
    template_variables={"name": "John", "company": "Acme Inc"}
))

Manage Domains

from sendbase_email import CreateDomainRequest

# Add a domain
domain = client.domains.create(CreateDomainRequest(
    domain_name="yourdomain.com"
))
print(f"Domain ID: {domain.id}")
print(f"DNS Records to configure: {len(domain.dns_records)}")

# List domains
domains = client.domains.list()

# Verify a domain
domain = client.domains.verify(domain.id)
print(f"Verification status: {domain.verification_status_text}")

Manage Templates

from sendbase_email import CreateTemplateRequest, UpdateTemplateRequest

# Create a template
template = client.templates.create(CreateTemplateRequest(
    name="Welcome Email",
    subject="Welcome {{name}}!",
    html_body="<h1>Hello {{name}}</h1><p>Welcome to {{company}}!</p>"
))

# Preview with variables
preview = client.templates.preview(
    template.id,
    {"name": "John", "company": "Acme Inc"}
)
print(preview.html_body)

# Update template
template = client.templates.update(
    template.id,
    UpdateTemplateRequest(subject="Updated: Welcome {{name}}!")
)

# Delete template
client.templates.delete(template.id)

Webhooks

from sendbase_email import CreateWebhookRequest

# Get available event types
event_types = client.webhooks.get_event_types()
for et in event_types:
    print(f"{et.name}: {et.description}")

# Create a webhook
result = client.webhooks.create(CreateWebhookRequest(
    name="My Webhook",
    url="https://yourapp.com/webhooks/sendbase",
    event_types=["email.delivered", "email.bounced"]
))
print(f"Webhook ID: {result.endpoint.id}")
print(f"Signing Secret: {result.secret}")  # Store this securely!

# Test webhook
test_result = client.webhooks.test(result.endpoint.id)
print(f"Test successful: {test_result.success}")

Billing

# Get current usage
usage = client.billing.get_usage()
print(f"Emails sent: {usage.emails_sent}/{usage.emails_limit}")

# Get usage history
history = client.billing.get_usage_history(months=3)
for period in history:
    print(f"{period.current_period_start}: {period.emails_sent} emails")

# Get account limits
limits = client.billing.get_limits()
print(f"Domains allowed: {limits.domains_allowed}")

Error Handling

from sendbase_email import (
    SendBaseError,
    SendBaseAuthenticationError,
    SendBaseValidationError,
    SendBaseNotFoundError,
    SendBaseRateLimitError,
)

try:
    response = client.emails.send(request)
except SendBaseAuthenticationError:
    print("Invalid API key")
except SendBaseValidationError as e:
    print(f"Validation error: {e.errors}")
except SendBaseNotFoundError:
    print("Resource not found")
except SendBaseRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except SendBaseError as e:
    print(f"API error: {e.message} (HTTP {e.status_code})")

Context Manager

Both sync and async clients support context managers for automatic cleanup:

# Sync
with SendBaseClient("your-api-key") as client:
    response = client.emails.send(request)

# Async
async with AsyncSendBaseClient("your-api-key") as client:
    response = await client.emails.send(request)

Configuration

client = SendBaseClient(
    api_key="your-api-key",
    base_url="https://api.sendbase.app/api/v1",  # Custom base URL
    timeout=60.0  # Request timeout in seconds
)

Requirements

• Python 3.9+
• httpx
• pydantic

License

MIT License - see LICENSE file for details.