Zum Inhalt

API-Referenz

Die SubscribeFlow REST API folgt einem ressourcenorientierten Design mit einheitlichen Mustern über alle Endpoints hinweg.

Base URL

https://api.subscribeflow.net/api/v1

Authentifizierung

Fügen Sie Ihren API-Key in jede Anfrage ein. Siehe Authentifizierung für Details.

X-API-Key: sf_live_...

Authorization: Bearer sf_live_...

Endpoints-Übersicht

Subscribers

Methode Pfad Beschreibung
POST /subscribers Subscriber erstellen
GET /subscribers Subscriber auflisten
GET /subscribers/{id} Subscriber per ID abrufen
GET /subscribers/by-email/{email} Subscriber per E-Mail abrufen
PUT /subscribers/{subscriber_id} Subscriber aktualisieren
DELETE /subscribers/{id} Subscriber löschen
POST /subscribers/{id}/tags Tags zu einem Subscriber hinzufügen
DELETE /subscribers/{subscriber_id}/tags/{tag_id} Tag von einem Subscriber entfernen

Tags

Methode Pfad Beschreibung
POST /tags Tag erstellen
GET /tags Tags auflisten
GET /tags/{id} Tag per ID abrufen
GET /tags/by-name/{name} Tag per Name abrufen
PUT /tags/{tag_id} Tag aktualisieren
DELETE /tags/{id} Tag löschen

Templates

Methode Pfad Beschreibung
POST /templates Template erstellen
GET /templates Templates auflisten
GET /templates/{id} Template per ID abrufen
PUT /templates/{template_id} Template aktualisieren
DELETE /templates/{id} Template löschen
POST /templates/{id}/preview Template mit Variablen rendern

Emails

Methode Pfad Beschreibung
POST /emails/send Transaktionale E-Mail senden

Campaigns

Methode Pfad Beschreibung
POST /campaigns Campaign erstellen
GET /campaigns Campaigns auflisten
GET /campaigns/{id} Campaign per ID abrufen
PUT /campaigns/{campaign_id} Campaign aktualisieren
POST /campaigns/{id}/send Campaign senden
POST /campaigns/{id}/cancel Campaign abbrechen
POST /campaigns/{id}/duplicate Campaign duplizieren
POST /campaigns/{id}/retry Fehlgeschlagene Campaign wiederholen
POST /campaigns/count-recipients Passende Empfänger zählen

Triggers

Methode Pfad Beschreibung
POST /email-triggers Trigger erstellen
GET /email-triggers Triggers auflisten
GET /email-triggers/{trigger_id} Trigger per ID abrufen
PUT /email-triggers/{trigger_id} Trigger aktualisieren
DELETE /email-triggers/{trigger_id} Trigger löschen

Webhooks

Methode Pfad Beschreibung
POST /webhooks Webhook erstellen
GET /webhooks Webhooks auflisten
GET /webhooks/{endpoint_id} Webhook per ID abrufen
PUT /webhooks/{endpoint_id} Webhook aktualisieren
DELETE /webhooks/{endpoint_id} Webhook löschen
POST /webhooks/{endpoint_id}/test Webhook testen
POST /webhooks/{endpoint_id}/regenerate-secret Signing Secret rotieren
GET /webhooks/{endpoint_id}/deliveries Zustellungen auflisten
POST /webhooks/{endpoint_id}/deliveries/{did}/retry Zustellung wiederholen
GET /webhooks/{endpoint_id}/stats Zustellungsstatistiken abrufen

Preference Center

Methode Pfad Beschreibung
GET /preference-center Subscriber-Präferenzen abrufen
PUT /preference-center/tags/{tag_id} Tag abonnieren
DELETE /preference-center/tags/{tag_id} Tag abbestellen
GET /preference-center/data-export Subscriber-Daten exportieren
DELETE /preference-center/account Subscriber-Konto löschen

Billing

Methode Pfad Beschreibung
GET /billing/subscription Aktuelles Abonnement abrufen
POST /billing/create-checkout-session Stripe-Checkout-Session erstellen
POST /billing/customer-portal Stripe-Billing-Portal-Session erstellen
POST /billing/sync-subscription Abonnement mit Stripe synchronisieren

Tip

Erkunden Sie die vollständige API interaktiv unter /docs (Swagger UI) oder /redoc (ReDoc).

Fehlerformat

SubscribeFlow gibt Fehler im RFC 7807 Problem Details-Format zurück:

{
  "type": "https://docs.subscribeflow.net/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Subscriber with ID 'abc-123' not found.",
  "instance": "/api/v1/subscribers/abc-123"
}

Fehlercodes

Status Name Beschreibung
400 Bad Request Fehlerhafte Anfrage-Syntax
401 Unauthorized Fehlender oder ungültiger API-Key
402 Payment Required Plan-Limit überschritten (Upgrade erforderlich)
404 Not Found Ressource existiert nicht
409 Conflict Ressource existiert bereits (z.B. doppelte E-Mail)
422 Unprocessable Entity Validierung des Request-Bodys fehlgeschlagen
429 Too Many Requests Rate Limit überschritten
500 Internal Server Error Unerwarteter Server-Fehler

Pagination

Listen-Endpoints verwenden Cursor-basierte Pagination mit zwei Query-Parametern:

Parameter Typ Standard Beschreibung
cursor string null Cursor aus einer vorherigen Antwort
limit integer 50 Anzahl der Einträge pro Seite (max. 100)

Die Antwort enthält einen X-Total-Count-Header mit der Gesamtanzahl der passenden Ressourcen.

{
  "items": [...],
  "cursor": "eyJpZCI6IjEyMyJ9",
  "total": 1250
}

Übergeben Sie den cursor-Wert an die nächste Anfrage, um die folgende Seite abzurufen. Wenn cursor den Wert null hat, haben Sie die letzte Seite erreicht.

Rate Limiting

Alle API-Keys sind auf 1.000 Anfragen pro Minute begrenzt. Der Rate-Limit-Status ist in jeder Antwort enthalten:

Header Beschreibung
X-RateLimit-Limit Maximale Anfragen pro Minute (1000)
X-RateLimit-Remaining Verbleibende Anfragen im aktuellen Zeitfenster
X-RateLimit-Reset Unix-Zeitstempel, wann das Zeitfenster zurückgesetzt wird

Bei Überschreitung des Limits gibt die API HTTP 429 mit einem Retry-After-Header zurück, der die Wartezeit in Sekunden angibt.

from subscribeflow import RateLimitError

try:
    await client.subscribers.list()
except RateLimitError:
    print("Rate Limit erreicht -- warten und erneut versuchen")

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

try {
  await client.subscribers.list();
} catch (error) {
  if (error instanceof SubscribeFlowError && error.status === 429) {
    console.log('Rate Limit erreicht -- warten und erneut versuchen');
  }
}

# Rate-Limit-Header in der Antwort prüfen:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 998
# X-RateLimit-Reset: 1710000060