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-Uebersicht

Subscribers

Methode Pfad Beschreibung
POST /subscribers Subscriber erstellen
GET /subscribers Subscriber auflisten
GET /subscribers/{id} Subscriber per ID abrufen
GET /subscribers/by-email Subscriber per E-Mail abrufen
PATCH /subscribers/{id} Subscriber aktualisieren
DELETE /subscribers/{id} Subscriber löschen
POST /subscribers/{id}/tags Tags zu einem Subscriber hinzufuegen
DELETE /subscribers/{id}/tags/{slug} Tag von einem Subscriber entfernen
POST /subscribers/{id}/preference-token Preference-Center-Token generieren

Tags

Methode Pfad Beschreibung
POST /tags Tag erstellen
GET /tags Tags auflisten
GET /tags/{id} Tag per ID abrufen
GET /tags/by-name Tag per Name abrufen
PATCH /tags/{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
PATCH /templates/{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
PATCH /campaigns/{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
GET /campaigns/{id}/recipient-count Passende Empfaenger zaehlen

Triggers

Methode Pfad Beschreibung
POST /triggers Trigger erstellen
GET /triggers Triggers auflisten
GET /triggers/{id} Trigger per ID abrufen
PATCH /triggers/{id} Trigger aktualisieren
DELETE /triggers/{id} Trigger löschen

Webhooks

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

Preference Center

Methode Pfad Beschreibung
GET /preference-center Subscriber-Praeferenzen abrufen
POST /preference-center/tags/{id}/subscribe Tag abonnieren
POST /preference-center/tags/{id}/unsubscribe Tag abbestellen
GET /preference-center/export Subscriber-Daten exportieren
DELETE /preference-center/account Subscriber-Konto löschen

Billing

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

Tip

Erkunden Sie die vollstaendige 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 ungueltiger 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 Eintraege pro Seite (max. 100)

Die Antwort enthaelt einen X-Total-Count-Header mit der Gesamtanzahl der passenden Ressourcen.

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

Uebergeben Sie den cursor-Wert an die naechste 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 pruefen:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 998
# X-RateLimit-Reset: 1710000060