Skip to main content

​
Installation

pip install unosend

​
Requirements

  • Python 3.8 or higher
  • httpx (automatically installed)

​
Environment Variables

Never hardcode your API key. Use environment variables instead.
.env
UNOSEND_API_KEY=un_your_api_key
main.py
import os
from unosend import Unosend

unosend = Unosend(os.environ["UNOSEND_API_KEY"])

​
Basic Usage

main.py
from unosend import Unosend

# Initialize with your API key
unosend = Unosend("un_your_api_key")

# Send an email
response = unosend.emails.send(
    from_address="[email protected]",
    to="[email protected]",
    subject="Welcome!",
    html="<h1>Hello!</h1><p>Welcome to our platform.</p>"
)

if response.error:
    print(f"Failed to send: {response.error.message}")
else:
    print(f"Email sent: {response.data.id}")

​
Response Format

All SDK methods return an ApiResponse object with data and error attributes:
response.py
# Successful response
response.data  # Contains the result
response.error  # None on success

# Example successful data
{
    "id": "em_xxxxxxxxxxxxxxxxxxxxxxxx",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Welcome!",
    "status": "queued",
    "created_at": "2024-01-15T10:30:00Z"
}

# Error response
response.data   # None on error
response.error  # ApiError object
response.error.message  # "Invalid API key"
response.error.code     # 401

​
Send to Multiple Recipients

multiple.py
from unosend import Unosend

unosend = Unosend("un_your_api_key")

# Send to multiple recipients
response = unosend.emails.send(
    from_address="[email protected]",
    to=["[email protected]", "[email protected]"],
    subject="Team Update",
    html="<h1>Important Update</h1>",
    cc=["[email protected]"],
    bcc=["[email protected]"],
    reply_to="[email protected]"
)

​
Working with Domains

domains.py
from unosend import Unosend

unosend = Unosend("un_your_api_key")

# Add a domain
response = unosend.domains.create("yourdomain.com")
print(f"Domain added: {response.data.id}")
print(f"DNS Records to add: {response.data.records}")

# List all domains
response = unosend.domains.list()
for domain in response.data:
    print(f"{domain.name} - {domain.status}")

# Verify domain DNS
response = unosend.domains.verify(domain_id)
print(f"Domain status: {response.data.status}")

# Delete a domain
unosend.domains.delete(domain_id)

​
Working with Audiences & Contacts

audiences.py
from unosend import Unosend

unosend = Unosend("un_your_api_key")

# Create an audience
response = unosend.audiences.create("Newsletter Subscribers")
audience_id = response.data.id
print(f"Audience created: {audience_id}")

# Add contacts to the audience
response = unosend.contacts.create(
    audience_id,
    email="[email protected]",
    first_name="John",
    last_name="Doe"
)
print(f"Contact added: {response.data.id}")

# List contacts
response = unosend.contacts.list(audience_id)
for contact in response.data:
    print(f"{contact.email} - {contact.first_name}")

# Update a contact
unosend.contacts.update(
    contact_id,
    first_name="Jane",
    unsubscribed=False
)

# Delete a contact
unosend.contacts.delete(contact_id)

​
Error Handling

errors.py
from unosend import Unosend

unosend = Unosend("un_your_api_key")

response = unosend.emails.send(
    from_address="[email protected]",
    to="[email protected]",
    subject="Test",
    html="<p>Hello</p>"
)

# Check for errors
if response.error:
    print(f"Error {response.error.code}: {response.error.message}")
else:
    print(f"Success! Email ID: {response.data.id}")

# Or use tuple unpacking
data, error = unosend.emails.send(...)
if error:
    print(f"Failed: {error.message}")

​
Context Manager

Use the SDK as a context manager for automatic resource cleanup:
context.py
from unosend import Unosend

with Unosend("un_your_api_key") as unosend:
    response = unosend.emails.send(
        from_address="[email protected]",
        to="[email protected]",
        subject="Hello!",
        html="<p>World</p>"
    )
# Client is automatically closed

​
Custom Headers & Tags

advanced.py
from unosend import Unosend

unosend = Unosend("un_your_api_key")

# Send with custom headers and tags
response = unosend.emails.send(
    from_address="[email protected]",
    to="[email protected]",
    subject="Order Confirmation",
    html="<h1>Order #12345</h1>",
    headers={
        "X-Order-ID": "12345",
        "X-Customer-ID": "cust_abc"
    },
    tags=[
        {"name": "campaign", "value": "order-confirmation"},
        {"name": "order_id", "value": "12345"}
    ]
)

​
Available Methods

MethodDescription
emails.send()Send an email
emails.get(id)Get email details by ID
emails.list()List all emails
domains.create(name)Add a domain
domains.verify(id)Verify domain DNS
domains.list()List all domains
domains.delete(id)Delete a domain
audiences.create(name)Create an audience
audiences.list()List all audiences
contacts.create(audience_id, data)Add a contact to audience
contacts.list(audience_id)List contacts in audience
contacts.update(contact_id, data)Update a contact
contacts.delete(contact_id)Delete a contact
View on PyPI: pypi.org/project/unosend

View full API reference

Explore all available API endpoints