# Resletter Python SDK

Official Python SDK for the [Resletter](https://resletter.com) newsletter platform API.

## Installation

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

## Quick Start

```python
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

```python
# 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

```python
# 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

```python
# 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

```python
# 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

```python
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:

```python
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

```python
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:

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

## License

MIT
