SDK-Einrichtung

Offizielle SDKs sind für Python und TypeScript verfügbar. Beide unterstützen die vollständige SubscribeFlow API.

Python

Installation

pip install subscribeflow

Oder in requirements.txt:

subscribeflow

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

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

Client initialisieren

Das Python-SDK ist asynchron und verwendet einen Context Manager für die HTTP-Verbindung:

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())

Sie können den Client-Lebenszyklus auch manuell verwalten:

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

Fehlerbehandlung

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

try:
    subscriber = await client.subscribers.get("non-existent-id")
except NotFoundError as e:
    print(f"Nicht gefunden: {e.detail}")
except ValidationError as e:
    print(f"Validierung fehlgeschlagen: {e.detail}")
    for error in e.errors:
        print(f"  - {error['loc']}: {error['msg']}")
except RateLimitError:
    print("Rate Limit überschritten, später erneut versuchen")
except AuthenticationError:
    print("Ungültiger API-Key")
except SubscribeFlowError as e:
    print(f"API-Fehler ({e.status}): {e.detail}")

Konfiguration

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

TypeScript

Installation

npm install @subscribeflow/sdk

Oder mit yarn:

yarn add @subscribeflow/sdk

Oder mit bun:

bun add @subscribeflow/sdk

Client initialisieren

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));

Fehlerbehandlung

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('Typ:', error.type);
    console.error('Detail:', error.detail);
  }
}

Konfiguration

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

Self-hosted Instanzen

Wenn Sie SubscribeFlow auf Ihrer eigenen Infrastruktur betreiben, konfigurieren Sie die API-URL im SDK:

PythonTypeScript

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

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

Das SDK hängt /api/v1/... automatisch an die Base-URL an.

Testen mit Test-Keys

Verwenden Sie sf_test_-Keys während der Entwicklung. Test-Keys arbeiten mit isolierten Sandbox-Daten und senden keine echten E-Mails.

PythonTypeScript

async with SubscribeFlowClient(api_key="sf_test_...") as client:
    # Dieser Subscriber existiert nur in der Testumgebung
    subscriber = await client.subscribers.create(
        email="test@example.com",
    )

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

// Dieser Subscriber existiert nur in der Testumgebung
const subscriber = await client.subscribers.create({
  email: 'test@example.com',
});

Tip

Verwenden Sie Test-Keys in CI/CD-Pipelines und bei der lokalen Entwicklung. Wechseln Sie erst in der Produktion zu sf_live_-Keys.