Zum Inhalt

TypeScript SDK-Referenz

Das offizielle TypeScript-SDK für die SubscribeFlow API. Synchrone Client-Initialisierung, volle Typsicherheit.

Installation

npm install @subscribeflow/sdk

Oder mit bun:

bun add @subscribeflow/sdk

Client-Initialisierung

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

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

Ressourcen

subscribers

create(params)

Neuen Subscriber erstellen.

const subscriber = await client.subscribers.create({
  email: 'alice@example.com',
  tags: ['newsletter'],
  metadata: { source: 'website' },
});

get(subscriberId)

Subscriber per ID abrufen.

const subscriber = await client.subscribers.get('subscriber-id');

getByEmail(email)

Subscriber per E-Mail-Adresse abrufen.

const subscriber = await client.subscribers.getByEmail('alice@example.com');

list(params?)

Subscriber mit Cursor-basierter Pagination auflisten.

const { items, cursor, total } = await client.subscribers.list({
  limit: 50,
  status: 'active',
});

update(subscriberId, params)

Subscriber-Felder aktualisieren.

const updated = await client.subscribers.update('subscriber-id', {
  metadata: { plan: 'professional' },
});

delete(subscriberId)

Subscriber und alle zugehörigen Daten dauerhaft löschen.

await client.subscribers.delete('subscriber-id');

addTags(subscriberId, params)

Tags zu einem Subscriber hinzufügen.

await client.subscribers.addTags('subscriber-id', {
  tags: ['beta-testers'],
});

removeTag(subscriberId, tagSlug)

Einzelnen Tag von einem Subscriber entfernen.

await client.subscribers.removeTag('subscriber-id', 'beta-testers');

generatePreferenceToken(subscriberId)

Preference-Center-Token generieren.

const tokenResponse = await client.subscribers.generatePreferenceToken(
  'subscriber-id',
);
console.log(tokenResponse.token);

tags

create(params)

Neuen Tag erstellen.

const tag = await client.tags.create({
  name: 'Product Updates',
  description: 'Neue Features und Verbesserungen',
  category: 'product',
  is_public: true,
});

get(tagId)

Tag per ID abrufen.

const tag = await client.tags.get('tag-id');

getByName(name)

Tag per Name abrufen.

const tag = await client.tags.getByName('Product Updates');

list(params?)

Alle Tags auflisten, optional nach Kategorie filtern.

const { items } = await client.tags.list({ category: 'product' });

update(tagId, params)

Tag-Felder aktualisieren.

await client.tags.update('tag-id', { description: 'Aktualisierte Beschreibung' });

delete(tagId)

Tag löschen und alle Subscriber-Zuordnungen entfernen.

await client.tags.delete('tag-id');

templates

create(params)

E-Mail-Template erstellen.

const template = await client.templates.create({
  name: 'Welcome Email',
  subject: 'Willkommen bei {{company}}!',
  mjml_content: '<mjml><mj-body>...</mj-body></mjml>',
  category: 'transactional',
});

get(templateId)

Template per ID abrufen.

const template = await client.templates.get('template-id');

getBySlug(slug)

Template per Slug abrufen.

const template = await client.templates.getBySlug('welcome-email');

list(params?)

Templates auflisten, optional nach Kategorie filtern.

const { items } = await client.templates.list({ category: 'transactional' });

update(templateId, params)

Template-Felder aktualisieren.

await client.templates.update('template-id', { subject: 'Neuer Betreff' });

delete(templateId)

Template löschen.

await client.templates.delete('template-id');

preview(templateId, variables?)

Template mit Variablen rendern und HTML-Ausgabe zurückgeben.

const preview = await client.templates.preview('template-id', {
  company: 'Acme Inc',
});
console.log(preview.html);

campaigns

create(params)

Campaign-Entwurf erstellen.

const campaign = await client.campaigns.create({
  name: 'Maerz-Newsletter',
  template_id: 'template-uuid',
  tag_filter: { include_tags: ['newsletter'], match: 'any' },
});

get(campaignId)

Campaign per ID abrufen.

const campaign = await client.campaigns.get('campaign-id');

list(params?)

Campaigns auflisten, optional nach Status filtern.

const campaigns = await client.campaigns.list({ status: 'draft' });

update(campaignId, params)

Campaign-Felder aktualisieren.

await client.campaigns.update('campaign-id', { name: 'Aktualisierter Name' });

send(campaignId)

Campaign an alle passenden Subscriber senden.

const result = await client.campaigns.send('campaign-id');
console.log(`Versand an ${result.total_recipients} Empfaenger`);

cancel(campaignId)

Laufende Campaign abbrechen.

await client.campaigns.cancel('campaign-id');

duplicate(campaignId)

Campaign als neuen Entwurf duplizieren.

const newCampaign = await client.campaigns.duplicate('campaign-id');

retry(campaignId)

Fehlgeschlagene Campaign erneut versuchen.

await client.campaigns.retry('campaign-id');

countRecipients(campaignId)

Vorschau der Empfängeranzahl für den Tag-Filter der Campaign.

const count = await client.campaigns.countRecipients('campaign-id');
console.log(`${count.count} Subscriber`);

emails

send(params)

Transaktionale E-Mail an einen einzelnen Empfänger senden.

const result = await client.emails.send({
  template_slug: 'welcome-email',
  to: 'alice@example.com',
  variables: { company: 'Acme Inc' },
  idempotency_key: 'welcome-alice-2024',
});

webhooks

create(params)

Webhook-Endpoint erstellen. Gibt das Signing Secret zurück.

const webhook = await client.webhooks.create({
  url: 'https://your-app.com/webhooks/subscribeflow',
  events: ['subscriber.created', 'tag.subscribed'],
});
console.log('Secret:', webhook.signing_secret);

get(webhookId)

Webhook per ID abrufen.

const webhook = await client.webhooks.get('webhook-id');

list()

Alle Webhook-Endpoints auflisten.

const { items } = await client.webhooks.list();

update(webhookId, params)

Webhook-Felder aktualisieren.

await client.webhooks.update('webhook-id', {
  events: ['subscriber.created'],
});

delete(webhookId)

Webhook-Endpoint löschen.

await client.webhooks.delete('webhook-id');

test(webhookId, eventType?)

Testereignis an einen Webhook-Endpoint senden.

const result = await client.webhooks.test('webhook-id', 'subscriber.created');
console.log('Erfolgreich:', result.success);

listDeliveries(webhookId)

Zustellungsverlauf eines Webhooks auflisten.

const deliveries = await client.webhooks.listDeliveries('webhook-id');

retryDelivery(webhookId, deliveryId)

Fehlgeschlagene Zustellung wiederholen.

await client.webhooks.retryDelivery('webhook-id', 'delivery-id');

getDeliveryStats(webhookId)

Zustellungsstatistiken eines Webhooks abrufen.

const stats = await client.webhooks.getDeliveryStats('webhook-id');
console.log(`Erfolgsrate: ${stats.success_rate}%`);

rotateSecret(webhookId)

Signing Secret rotieren.

const rotated = await client.webhooks.rotateSecret('webhook-id');
console.log('Neues Secret:', rotated.signing_secret);

triggers

create(params)

Ereignisbasierten E-Mail-Trigger erstellen.

const trigger = await client.triggers.create({
  event_type: 'subscriber.created',
  template_id: 'welcome-template-uuid',
  description: 'Willkommens-E-Mail bei Registrierung senden',
});

get(triggerId)

Trigger per ID abrufen.

const trigger = await client.triggers.get('trigger-id');

list()

Alle Triggers auflisten.

const triggers = await client.triggers.list();

update(triggerId, params)

Trigger-Felder aktualisieren.

await client.triggers.update('trigger-id', { is_active: false });

delete(triggerId)

Trigger löschen.

await client.triggers.delete('trigger-id');

billing

getSubscription()

Aktuelles Billing-Abonnement abrufen.

const subscription = await client.billing.getSubscription();

createCheckoutSession(plan)

Stripe-Checkout-Session für Plan-Upgrade erstellen.

const session = await client.billing.createCheckoutSession('starter');
console.log('Checkout-URL:', session.url);

createPortalSession()

Stripe-Billing-Portal-Session erstellen.

const session = await client.billing.createPortalSession();
console.log('Portal-URL:', session.url);

syncSubscription()

Abonnement-Status mit Stripe synchronisieren.

await client.billing.syncSubscription();

preferenceCenter

Preference-Center-Operationen mit einem Subscriber-Token ausführen.

const prefCenter = client.preferenceCenter(token);

getInfo()

Präferenzen und verfügbare Tags des Subscribers abrufen.

const info = await prefCenter.getInfo();

subscribeTag(tagId)

Tag abonnieren.

await prefCenter.subscribeTag('tag-id');

unsubscribeTag(tagId)

Tag abbestellen.

await prefCenter.unsubscribeTag('tag-id');

exportData()

Alle Subscriber-Daten als JSON exportieren (DSGVO Art. 20).

const exportData = await prefCenter.exportData();

deleteAccount()

Subscriber-Konto dauerhaft löschen (DSGVO Art. 17).

await prefCenter.deleteAccount();

TypeScript-Typen

Das SDK bietet vollständige Typdefinitionen. Sie können Component-Schemas direkt importieren:

import type { paths, components } from '@subscribeflow/sdk';

type Subscriber = components['schemas']['SubscriberResponse'];
type Tag = components['schemas']['TagResponse'];
type Campaign = components['schemas']['CampaignResponse'];

const subscriber: Subscriber = await client.subscribers.get('id');

Fehlerbehandlung

Alle Fehler erweitern SubscribeFlowError:

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

try {
  await client.subscribers.get('non-existent-id');
} catch (error) {
  if (error instanceof SubscribeFlowError) {
    console.error('Status:', error.status);   // HTTP-Statuscode
    console.error('Typ:', error.type);         // Fehlertyp-Kennung
    console.error('Detail:', error.detail);    // Menschenlesbare Nachricht
  }
}

Spezifische Fehlertypen per Statuscode prüfen:

try {
  await client.subscribers.create({ email: 'alice@example.com' });
} catch (error) {
  if (error instanceof SubscribeFlowError) {
    switch (error.status) {
      case 401:
        console.error('Ungueltiger API-Key');
        break;
      case 402:
        console.error('Plan-Limit überschritten:', error.detail);
        break;
      case 404:
        console.error('Nicht gefunden');
        break;
      case 422:
        console.error('Validierung fehlgeschlagen:', error.detail);
        break;
      case 429:
        console.error('Rate Limit überschritten');
        break;
      default:
        console.error('API-Fehler:', error.detail);
    }
  }
}