Resletter Python SDK

Official Python SDK for the Resletter newsletter platform API.

Installation

pip install resletter
# or
poetry add resletter
# or
uv add resletter

Quick Start

from resletter import Resletter

client = Resletter("rsl_your_api_key")

# Create a subscriber
subscriber = client.subscribers.create(
    email="user@example.com",
    name="John Doe",
    metadata={"source": "website"},
)

print(f"Created subscriber: {subscriber['id']}")

Requirements

• Python >= 3.9
• A Resletter account with Starter plan or above (API access required)

Authentication

Get your API key from your Resletter project settings:

1. Navigate to your project settings
2. Go to the "API Access" section
3. Click "Create API Key"
4. Select the required scopes for your use case
5. Copy your API key (starts with rsl_)

API Reference

Subscribers

# List subscribers
result = client.subscribers.list(
    page=1,
    limit=50,
    status="subscribed",
    group_id="uuid",
    email="search@example.com",
)
subscribers = result["subscribers"]
pagination = result["pagination"]

# Get a subscriber
subscriber = client.subscribers.get("subscriber-id")

# Create a subscriber
new_subscriber = client.subscribers.create(
    email="user@example.com",
    name="John Doe",
    metadata={"plan": "pro"},
    group_ids=["group-id"],
    bypass_double_opt_in=True,
)

# Create multiple subscribers
result = client.subscribers.create_bulk(
    subscribers=[
        {"email": "user1@example.com", "name": "User 1"},
        {"email": "user2@example.com", "name": "User 2"},
    ],
    group_ids=["group-id"],
    skip_duplicates=True,
    bypass_double_opt_in=True,
)

# Update a subscriber
updated = client.subscribers.update(
    "subscriber-id",
    name="Jane Doe",
    metadata={"plan": "enterprise"},
    group_ids=["new-group-id"],
)

# Unsubscribe (soft delete)
client.subscribers.delete("subscriber-id")

# Hard delete
client.subscribers.delete("subscriber-id", hard=True)

Groups

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

# Get a group
group = client.groups.get("group-id")

# Create a group
new_group = client.groups.create(
    name="Product Updates",
    description="Subscribers interested in product news",
    color="#3B82F6",
)

# Update a group
updated = client.groups.update(
    "group-id",
    name="New Name",
)

# Delete a group
client.groups.delete("group-id")

# Add subscribers to a group
client.groups.add_subscribers(
    "group-id",
    subscriber_ids=["sub-1", "sub-2"],
)

# Remove subscribers from a group
client.groups.remove_subscribers(
    "group-id",
    subscriber_ids=["sub-1"],
)

Campaigns

# List campaigns
campaigns = client.campaigns.list(status="active")

# Get a campaign
campaign = client.campaigns.get("campaign-id")

# Create a campaign
new_campaign = client.campaigns.create(
    name="Product Launch Campaign",
    description="Campaign for new product announcement",
    subscriber_group_ids=["group-1", "group-2"],
)

# Update a campaign
updated = client.campaigns.update(
    "campaign-id",
    name="Updated Campaign Name",
    status="paused",
)

# Delete a campaign
client.campaigns.delete("campaign-id")

Events

# Track a custom event to trigger automations
result = client.events.track(
    name="purchase_completed",
    email="user@example.com",
    data={
        "product": "Premium Plan",
        "amount": 99.0,
    },
)

print(f"Triggered {result['automationsTriggered']} automations")

Configuration Options

client = Resletter(
    "rsl_your_api_key",
    base_url="https://app.resletter.com",  # Custom base URL
    timeout=30.0,  # Request timeout in seconds
)

Context Manager

The client supports context manager protocol for automatic cleanup:

with Resletter("rsl_your_api_key") as client:
    subscriber = client.subscribers.create(email="user@example.com")
    # Connection is automatically closed when exiting the block

Error Handling

from resletter import Resletter, ResletterError

try:
    client.subscribers.create(email="invalid")
except ResletterError as e:
    print(f"Status: {e.status}")
    print(f"Message: {e.message}")
    print(f"Code: {e.code}")

Type Hints

This SDK includes full type hints for all methods and responses:

from resletter import (
    Subscriber,
    SubscriberGroup,
    Campaign,
    SubscriberStatus,
    CampaignStatus,
)

License

MIT