SDK Setup

Official SDKs are available for Python and TypeScript. Both support the full SubscribeFlow API.

Python

Install

pip install subscribeflow

Or in requirements.txt:

subscribeflow

Or in pyproject.toml (uv, Poetry, PDM):

[project.dependencies]
subscribeflow = ">=0.1.0"

Initialize the client

The Python SDK is async and uses a context manager to manage the HTTP connection:

import asyncio
from subscribeflow import SubscribeFlowClient

async def main():
    async with SubscribeFlowClient(api_key="sf_live_...") as client:
        subscribers = await client.subscribers.list(limit=10)
        for s in subscribers:
            print(s.email)

asyncio.run(main())

You can also manage the client lifecycle manually:

client = SubscribeFlowClient(api_key="sf_live_...")
try:
    subscriber = await client.subscribers.get("subscriber-id")
finally:
    await client.close()

Error handling

from subscribeflow import (
    SubscribeFlowClient,
    SubscribeFlowError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    RateLimitError,
)

try:
    subscriber = await client.subscribers.get("non-existent-id")
except NotFoundError as e:
    print(f"Not found: {e.detail}")
except ValidationError as e:
    print(f"Validation failed: {e.detail}")
    for error in e.errors:
        print(f"  - {error['loc']}: {error['msg']}")
except RateLimitError:
    print("Rate limit exceeded, retry later")
except AuthenticationError:
    print("Invalid API key")
except SubscribeFlowError as e:
    print(f"API error ({e.status}): {e.detail}")

Configuration

client = SubscribeFlowClient(
    api_key="sf_live_...",
    base_url="https://api.subscribeflow.net",  # default
    timeout=30.0,                               # seconds, default: 30
)

TypeScript

Install

npm install @subscribeflow/sdk

Or with yarn:

yarn add @subscribeflow/sdk

Or with bun:

bun add @subscribeflow/sdk

Initialize the client

import { SubscribeFlowClient } from '@subscribeflow/sdk';

const client = new SubscribeFlowClient({
  apiKey: process.env.SUBSCRIBEFLOW_API_KEY!,
});

const { items } = await client.subscribers.list({ limit: 10 });
items.forEach((s) => console.log(s.email));

Error handling

import { SubscribeFlowClient, SubscribeFlowError } from '@subscribeflow/sdk';

try {
  await client.subscribers.get('non-existent-id');
} catch (error) {
  if (error instanceof SubscribeFlowError) {
    console.error('Status:', error.status);
    console.error('Type:', error.type);
    console.error('Detail:', error.detail);
  }
}

Configuration

const client = new SubscribeFlowClient({
  apiKey: 'sf_live_...',
  baseUrl: 'https://api.subscribeflow.net', // default
});

Self-hosted instances

If you run SubscribeFlow on your own infrastructure, point the SDK at your API URL:

PythonTypeScript

client = SubscribeFlowClient(
    api_key="sf_live_...",
    base_url="https://api.your-domain.com",
)

const client = new SubscribeFlowClient({
  apiKey: 'sf_live_...',
  baseUrl: 'https://api.your-domain.com',
});

The SDK appends /api/v1/... to the base URL automatically.

Testing with test keys

Use sf_test_ keys during development. Test keys operate on isolated sandbox data and never send real emails.

PythonTypeScript

async with SubscribeFlowClient(api_key="sf_test_...") as client:
    # This subscriber only exists in the test environment
    subscriber = await client.subscribers.create(
        email="test@example.com",
    )

const client = new SubscribeFlowClient({
  apiKey: 'sf_test_...',
});

// This subscriber only exists in the test environment
const subscriber = await client.subscribers.create({
  email: 'test@example.com',
});

Tip

Use test keys in CI/CD pipelines and local development. Switch to sf_live_ keys only in production.