unsent 1.0.2

Python SDK for the Unsent API - Send transactional emails with ease

unsent Python SDK

The official Python library for the unsent API.

Prerequisites

• Python 3.8+
• unsent API Key
• Verified Domain

Installation

pip

pip install unsent

poetry

poetry add unsent

Usage

Configuration

Initialize the client with your API key.

from unsent import unsent

client = unsent("res_123456789")

Environment Variables

You can omit the API key if you set the UNSENT_API_KEY environment variable.

# With UNSENT_API_KEY set in environment
client = unsent()

Custom Session

For advanced usage (e.g., proxies, connection pooling), you can pass a custom requests.Session.

import requests
from unsent import unsent

session = requests.Session()
client = unsent("res_123...", session=session)

Emails

Send Email

data, error = client.emails.send({
    "from": "[e-mail]",
    "to": "[e-mail]",
    "subject": "Hello World",
    "html": "<p>It works!</p>"
})

if error:
    print(error)
else:
    print(data["id"])

Batch Emails

Send up to 100 emails in a single request.

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

Get Email

Retrieve details about a sent email.

data, error = client.emails.get("email_id")

Update Scheduled Email

Update the schedule of a pending email.

data, error = client.emails.update("email_id", {
    "scheduledAt": "2024-12-25T12:00:00Z"
})

Cancel Scheduled Email

Cancel a scheduled email before it is sent.

data, error = client.emails.cancel("email_id")

List Emails

Retrieve a list of sent emails with optional filters.

data, error = client.emails.list(
    page=1,
    limit=20,
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-01-31T23:59:59Z",
    domain_id="domain_id"
)

Get Complaints

Retrieve email complaints with pagination.

data, error = client.emails.get_complaints(page=1, limit=20)

Get Bounces

Retrieve email bounces with pagination.

data, error = client.emails.get_bounces(page=1, limit=20)

Get Unsubscribes

Retrieve email unsubscribes with pagination.

data, error = client.emails.get_unsubscribes(page=1, limit=20)

Contacts

List Contacts

Retrieve contacts from a contact book with optional filters.

data, error = client.contacts.list(
    "contact_book_id",
    page=1,
    limit=20,
    emails="[e-mail],[e-mail]",
    ids="contact_id_1,contact_id_2"
)

Create Contact

Add a contact to a contact book.

data, error = client.contacts.create("contact_book_id", {
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe",
    "subscribed": True,
    "properties": {
        "source": "signup_form"
    }
})

Get Contact

Retrieve a contact by ID from a specific book.

data, error = client.contacts.get("contact_book_id", "contact_id")

Update Contact

Update an existing contact's information.

data, error = client.contacts.update("contact_book_id", "contact_id", {
    "firstName": "Jane",
    "properties": {
        "status": "active"
    }
})

Upsert Contact

Create a contact if they don't exist, or update them if they do (matched by email).

data, error = client.contacts.upsert("contact_book_id", "contact_id_optional", {
    "email": "[e-mail]",
    "firstName": "John"
})

Delete Contact

Remove a contact from a book.

data, error = client.contacts.delete("contact_book_id", "contact_id")

Contact Books

List Contact Books

Retrieve all your contact books.

data, error = client.contact_books.list()

Create Contact Book

Create a new list to organize contacts.

data, error = client.contact_books.create({
    "name": "Newsletter Subscribers",
    "emoji": "📧"
})

Get Contact Book

Retrieve details of a specific contact book.

data, error = client.contact_books.get("book_id")

Update Contact Book

Rename or update settings of a contact book.

data, error = client.contact_books.update("book_id", {
    "name": "Active Users"
})

Delete Contact Book

Delete a contact book and all its contacts.

data, error = client.contact_books.delete("book_id")

Campaigns

Create Campaign

Draft a new email campaign.

data, error = client.campaigns.create({
    "name": "Monthly Newsletter",
    "subject": "What's new in January",
    "from": "[e-mail]",
    "contactBookId": "book_id",
    "html": "<h1>News...</h1>"
})

Get Campaign

Retrieve campaign details and stats.

data, error = client.campaigns.get("campaign_id")

Schedule Campaign

Schedule a campaign to be sent.

data, error = client.campaigns.schedule("campaign_id", {
    "scheduledAt": "2024-02-01T09:00:00Z"
})

Pause/Resume Campaign

Control the delivery of a running campaign.

# Pause
client.campaigns.pause("campaign_id")

# Resume
client.campaigns.resume("campaign_id")

Templates

List Templates

Retrieve all your email templates.

data, error = client.templates.list()

Create Template

Create a reusable email template.

data, error = client.templates.create({
    "name": "Welcome Email",
    "subject": "Welcome to Unsent",
    "html": "<h1>Welcome {{name}}</h1>"
})

Get Template

Retrieve a specific template.

data, error = client.templates.get("template_id")

Update Template

Modify an existing template.

data, error = client.templates.update("template_id", {
    "subject": "New Welcome Subject"
})

Delete Template

Remove a template.

data, error = client.templates.delete("template_id")

Domains

List Domains

View all registered sending domains.

data, error = client.domains.list()

Create Domain

Add a new domain for sending.

data, error = client.domains.create({
    "domain": "mail.example.com",
    "region": "us-east-1"
})

Verify Domain

Trigger verification checks for DNS records.

data, error = client.domains.verify("domain_id")

Get Domain

Retrieve DNS records and verification status.

data, error = client.domains.get("domain_id")

Delete Domain

Remove a domain.

data, error = client.domains.delete("domain_id")

Webhooks

Note: Webhooks functionality is currently under development in the API. The SDK includes placeholder methods to ensure compatibility when the feature becomes available.

List Webhooks

View configured webhooks.

data, error = client.webhooks.list()

Create Webhook

Subscribe to email events.

data, error = client.webhooks.create({
    "url": "https://api.myapp.com/webhooks/resend",
    "events": ["email.sent", "email.delivered", "email.bounced"]
})

Get Webhook

Retrieve webhook details.

data, error = client.webhooks.get("webhook_id")

Update Webhook

Modify webhook URL or events.

data, error = client.webhooks.update("webhook_id", {
    "url": "https://new-api.myapp.com/hooks"
})

Delete Webhook

Stop receiving events.

data, error = client.webhooks.delete("webhook_id")

Suppressions

List Suppressions

View email addresses on the suppression list (bounces, complaints).

# List all suppressions
data, error = client.suppressions.list()

# Filter by reason
data, error = client.suppressions.list(
    reason="HARD_BOUNCE",  # Options: HARD_BOUNCE, COMPLAINT, MANUAL, UNSUBSCRIBE
    page=1,
    limit=20,
    search="example.com"
)

Add Suppression

Manually suppress an email address.

data, error = client.suppressions.add({
    "email": "[e-mail]",
    "reason": "MANUAL"  # Options: HARD_BOUNCE, COMPLAINT, MANUAL, UNSUBSCRIBE
})

Delete Suppression

Remove an email from the suppression list to allow sending again.

data, error = client.suppressions.delete("[e-mail]")

Analytics

Get Usage

Check your daily email usage and limits.

data, error = client.analytics.get_usage()

Get Daily Stats

Retrieve aggregate statistics for a date range.

data, error = client.analytics.get_daily_stats(
    start_date="2024-01-01",
    end_date="2024-01-31"
)

Get Domain Reputation

Check the reputation score of a domain.

data, error = client.analytics.get_domain_reputation("domain_id")

API Keys

List API Keys

View all active API keys.

data, error = client.api_keys.list()

Create API Key

Generate a new API key.

data, error = client.api_keys.create({
    "name": "Production Key"
})

Revoke API Key

Invalidate an API key.

data, error = client.api_keys.revoke("api_key_id")

Settings

Get Settings

Retrieve account settings and quota information.

data, error = client.settings.get()

Error Handling

By default, the SDK raises unsentHTTPError for non-2xx responses. You can change this behavior to return the error object instead.

# Raise exception on error (Default)
try:
    client.emails.send(...)
except unsentHTTPError as e:
    print(e.status_code, e.message)

# Return error dictionary instead of raising
client = unsent("key", raise_on_error=False)
data, error = client.emails.send(...)
if error:
    print("Failed:", error)

License

MIT License