tosend 1.0.0

Official Python SDK for the ToSend email API

ToSend Python SDK

Official Python SDK for the ToSend email API.

Installation

pip install tosend

Examples

See the examples folder for complete working examples:

• Send Email - Send a single email
• Batch Send - Send multiple emails in one request
• Account Info - Get account information and domains

export TOSEND_API_KEY=tsend_your_api_key
python examples/send_email.py

Quick Start

from tosend import ToSend

client = ToSend("tsend_your_api_key")

response = client.send(
    from_address={"email": "[e-mail]", "name": "Your App"},
    to=[{"email": "[e-mail]"}],
    subject="Welcome!",
    html="<h1>Hello!</h1><p>Thanks for signing up.</p>",
)

print(response.message_id)

Usage

Send an Email

response = client.send(
    from_address={"email": "[e-mail]", "name": "Your App"},
    to=[
        {"email": "[e-mail]"},
        {"email": "[e-mail]", "name": "John Doe"},
    ],
    subject="Hello!",
    html="<h1>Welcome</h1>",
    text="Welcome",  # optional
)

With CC, BCC, and Reply-To

response = client.send(
    from_address={"email": "[e-mail]"},
    to=[{"email": "[e-mail]"}],
    cc=[{"email": "[e-mail]"}],
    bcc=[{"email": "[e-mail]"}],
    reply_to={"email": "[e-mail]", "name": "Support"},
    subject="Hello",
    html="<p>Hello World</p>",
)

With Attachments

import base64

with open("invoice.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode()

response = client.send(
    from_address={"email": "[e-mail]"},
    to=[{"email": "[e-mail]"}],
    subject="Your Invoice",
    html="<p>Please find your invoice attached.</p>",
    attachments=[
        {
            "type": "application/pdf",
            "name": "invoice.pdf",
            "content": content,
        }
    ],
)

Batch Sending

Send multiple emails in a single request:

response = client.batch([
    {
        "from": {"email": "[e-mail]"},
        "to": [{"email": "[e-mail]"}],
        "subject": "Hello User 1",
        "html": "<p>Welcome!</p>",
    },
    {
        "from": {"email": "[e-mail]"},
        "to": [{"email": "[e-mail]"}],
        "subject": "Hello User 2",
        "html": "<p>Welcome!</p>",
    },
])

for result in response.results:
    if result.status == "success":
        print(f"Sent: {result.message_id}")
    else:
        print(f"Failed: {result.message}")

Get Account Info

info = client.get_account_info()

print(info.account.title)
print(info.account.emails_usage_this_month)
print(info.account.emails_sent_last_24hrs)

for domain in info.domains:
    print(f"{domain.domain_name}: {domain.verification_status}")

Configuration

With Options

client = ToSend(
    api_key="tsend_your_api_key",
    base_url="https://api.tosend.com",  # optional
    timeout=60,  # optional, in seconds
)

Error Handling

from tosend import ToSend, ToSendError

client = ToSend("tsend_your_api_key")

try:
    response = client.send(
        from_address={"email": "[e-mail]"},
        to=[{"email": "[e-mail]"}],
        subject="Hello",
        html="<p>Hello</p>",
    )
except ToSendError as e:
    print(f"Error: {e.message}")
    print(f"Status: {e.status_code}")
    print(f"Type: {e.error_type}")
    print(f"Details: {e.errors}")

    if e.is_validation_error:
        # Handle validation error (422)
        pass

    if e.is_authentication_error:
        # Handle auth error (401/403)
        pass

    if e.is_rate_limit_error:
        # Handle rate limit (429)
        pass

Type Hints

The SDK includes full type hints. You can also use the provided dataclasses:

from tosend import ToSend, Address, SendEmailRequest

client = ToSend("tsend_your_api_key")

# Using Address dataclass
from_addr = Address(email="[e-mail]", name="Your App")
to_addr = Address(email="[e-mail]")

response = client.send(
    from_address=from_addr,
    to=[to_addr],
    subject="Hello!",
    html="<h1>Welcome!</h1>",
)

Requirements

• Python 3.8 or higher
• No external dependencies (uses only standard library)

License

MIT