API-Dokumentation

Die NewsletterKit API ist eine interne Middleware zwischen Kundenplattformen und Postmark: dein Portal schickt einfache, immer gleiche Requests — wir rendern die Mail aus MJML-Blöcken im Design des Kunden und übergeben den Versand an Postmark. Verschickt wird immer ein Template: transaktional einzeln und synchron, Newsletter als Versandjob. Jede Mail bekommt eine ID von uns; Auswertung und Sperren liegen hier, das Portal fragt ab. Empfängeradressen werden nach dem Versand gelöscht.

Maschinenlesbar

Ein schmaler Wrapper, dann fünf Abläufe, die jedes Kundenportal braucht: transaktionale Mail, Newsletter aus fertigem Template, Newsletter aus dem Builder, Sperren ins CRM, Auswertungsseite. Beispiele sind auf Next.js (TypeScript, fetch) ausgelegt — der API-Key lebt ausschließlich serverseitig.

0 · API-Key hinterlegen und Verbindung prüfen

// .env.local
NEWSLETTERKIT_API_KEY=nk_live_xxxxxxxxxxxxxxxx

// lib/newsletterkit.ts — schmaler Server-Wrapper (nur serverseitig nutzen)
const BASE = "https://api.newsletterkit.ventureon.io/v1";

export async function newsletterkit<T>(
  path: string,
  init: RequestInit = {},
): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.NEWSLETTERKIT_API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  if (!res.ok) throw new Error(`NewsletterKit ${res.status}: ${await res.text()}`);
  return res.json() as Promise<T>;
}

// app/api/check/route.ts  (Next.js Route Handler)
import { newsletterkit } from "@/lib/newsletterkit";

export async function GET() {
  const health = await newsletterkit("/health");
  return Response.json(health); // { data: { status: "ok", api_version: "v1" }, … }
}

// Server Action / Route Handler
import { newsletterkit } from "@/lib/newsletterkit";

const { data } = await newsletterkit<{ data: { message_id: string; status: string } }>(
  "/templates/00000000-0000-4000-8000-0000000000f3/send",
  {
    method: "POST",
    headers: { "Idempotency-Key": crypto.randomUUID() },
    body: JSON.stringify({
      to: "mira@example.com",
      params: {
        titel: "Dein Zugang zum Dashboard",
        name: "Mira",
        text: "Du bist als Redaktion eingetragen.",
        link: "https://kunde.de/einladung?token=…",
        screenshot: "https://kunde.de/bilder/dashboard.jpg",
      },
    }),
  },
);
// data.status: accepted | suppressed | invalid — data.message_id am Nutzer speichern
await db.user.update({ where: { id: userId }, data: { inviteMailId: data.message_id } });

import { newsletterkit } from "@/lib/newsletterkit";

// 1) Job anlegen
const job = await newsletterkit<{ data: { id: string } }>("/send-jobs", {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ template_id: templateId, params: { titel: "Sommerprogramm" } }),
});

// 2) Empfänger aus dem CRM: Einwilligung UND keine Sperre — nie nur eins davon
const contacts = await db.contact.findMany({
  where: { marketingConsent: true, emailSuppressed: false },
  select: { id: true, email: true, firstName: true },
});
for (let i = 0; i < contacts.length; i += 5000) {
  const chunk = contacts.slice(i, i + 5000);
  const res = await newsletterkit<{ data: { recipients: { email: string; message_id: string }[] } }>(
    `/send-jobs/${job.data.id}/recipients`,
    {
      method: "POST",
      headers: { "Idempotency-Key": `${job.data.id}:${i}` },
      body: JSON.stringify({
        recipients: chunk.map((c) => ({ email: c.email, data: { vorname: c.firstName } })),
      }),
    },
  );
  // Mail-IDs an die Kontakte schreiben — der Schlüssel für Status und Auswertung
  for (const r of res.data.recipients) await db.newsletterMail.create({ data: { contactEmail: r.email, messageId: r.message_id, jobId: job.data.id } });
}

// 3) Starten und abwarten
await newsletterkit(`/send-jobs/${job.data.id}/start`, { method: "POST" });

import { newsletterkit } from "@/lib/newsletterkit";

// Live-Vorschau: der Stapel des Builders, unverändert, an die API
export async function preview(blocks: { block_id: string; values: Record<string, unknown> }[]) {
  const { data } = await newsletterkit<{ data: { html: string | null; errors: string[] } }>(
    "/render/preview",
    { method: "POST", body: JSON.stringify({ blocks }) },
  );
  return data.html; // <iframe srcDoc={html} sandbox="" />
}

// Bild hochladen: drei Aufrufe hinter einer Funktion
export async function uploadAsset(file: File) {
  const created = await newsletterkit<{ data: { id: string; upload: { url: string; headers: Record<string, string> } } }>(
    "/assets",
    { method: "POST", body: JSON.stringify({ filename: file.name, content_type: file.type }) },
  );
  await fetch(created.data.upload.url, { method: "PUT", headers: created.data.upload.headers, body: file });
  const done = await newsletterkit<{ data: { url: string; width: number; height: number } }>(
    `/assets/${created.data.id}/complete`,
    { method: "POST" },
  );
  return done.data; // { url, width, height } — url in bild.url setzen
}

// Speichern als Template
const template = await newsletterkit<{ data: { id: string } }>("/templates", {
  method: "POST",
  headers: { "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    name: "Sommer-Newsletter",
    subject: "Hallo {{vorname}}, das Sommerprogramm ist da",
    blocks, // derselbe Stapel wie in der Vorschau
    status: "active",
  }),
});

// app/api/cron/suppressions/route.ts — alle 5 Minuten (Vercel Cron)
import { newsletterkit } from "@/lib/newsletterkit";

type Suppression = { email: string; active: boolean; reason?: string; changed_at: string };

export async function GET() {
  let since = (await kv.get<string>("nk:suppressions_since")) ?? "1970-01-01T00:00:00Z";
  let after: string | null = null;
  do {
    const page = await newsletterkit<{ data: Suppression[]; paging: { after: string | null; has_next: boolean } }>(
      `/suppressions?since=${since}${after ? `&after=${after}` : ""}`,
    );
    for (const s of page.data) {
      // Nur das Sperrfeld — die Einwilligung fasst der Abgleich nie an.
      await db.contact.updateMany({
        where: { email: s.email },
        data: { emailSuppressed: s.active, emailSuppressedReason: s.active ? s.reason : null },
      });
      since = s.changed_at;
    }
    after = page.paging.has_next ? page.paging.after : null;
  } while (after);
  await kv.set("nk:suppressions_since", since);
  return Response.json({ ok: true });
}

import { newsletterkit } from "@/lib/newsletterkit";

export async function newsletterReport(jobId: string) {
  const [job, bounced, links] = await Promise.all([
    newsletterkit<{ data: { status: string; recipients: Record<string, number>; stats: Record<string, number>; timeline: unknown[] } }>(`/send-jobs/${jobId}`),
    newsletterkit<{ data: { message_id: string; bounce_type: string | null }[] }>(`/send-jobs/${jobId}/messages?status=bounced`),
    newsletterkit<{ data: { url: string; clicks: number; unique_clicks: number }[] }>(`/send-jobs/${jobId}/links`),
  ]);
  return { job: job.data, bounced: bounced.data, links: links.data };
}

Jeder API-Call trägt den API-Key im Authorization-Header als Bearer-Token. Der Key bestimmt den Kunden — dahinter liegt der Postmark-Server-Token, den das Portal nie sieht. Scopes: full (lesen + schreiben/versenden) oder reporting (read-only).

Authorization: Bearer nk_live_xxxxxxxxxxxxxxxx

Standard-Header

Zugang zur Doku

Gelten für alle Endpunkte: einheitlicher { data, request_id }-Envelope, Cursor-Pagination bei Listen, Rate-Limits und Idempotenz.

Pagination (Cursor)

Listen mit Cursor (Sperren, Mails eines Jobs) liefern data[] + paging.after. Den Cursor an die nächste Anfrage als after übergeben, bis has_next false ist.

{
  "data": [ { "…": "…" } ],
  "paging": { "after": "QVFIUm...", "has_next": true }
}

// nächste Seite:
GET /v1/suppressions?since=…&after=QVFIUm...&limit=500

Rate-Limits

1.000 Anfragen je Minute und Kunde. Jede Antwort trägt X-RateLimit-*. Bei 429 die Sekundenzahl aus Retry-After abwarten (exponentielles Backoff empfohlen). Ein 429 mit quota_exceeded ist etwas anderes: eine Sicherung des Kunden (Monatslimit, Höchstzahl je Job), die ein Admin anhebt.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
Retry-After: 12

Idempotenz

Bei POST einen Idempotency-Key (UUID) mitsenden. Der erste Aufruf wird ausgeführt und seine Antwort 24 Stunden gespeichert; Wiederholungen mit gleichem Key bekommen dieselbe Antwort (Idempotent-Replayed: true) — vor allem kein doppelter Versand bei Netzwerk-Retries. Gleicher Key mit anderem Body: 409. Antwortet Postmark nicht (500 mit message_id), bleibt der Key belegt: Die Wiederholung bekommt dieselbe Antwort und sendet nicht erneut — den Ausgang zeigt GET /v1/messages/{id}.

Personalisierung

{{platzhalter}} in Betreff und festen Texten eines Templates werden je Empfänger gefüllt — aus den Job-Parametern und den data des Empfängers, der Empfänger gewinnt. Im HTML maskiert, unbekannte Platzhalter verschwinden. Gerendert wird einmal je Job, danach nur noch ersetzt.

Einheitliches Fehler-Objekt mit stabilem code, lesbarer message und request_id für den Support. 4xx = dein Request, 5xx = wir/Postmark.

{
  "error": {
    "code": "validation_error",
    "message": "Pflichtfelder fehlen: link.",
    "details": [
      { "path": "link", "message": "link ist erforderlich." }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Es gibt keinen buchbaren Plan und kein Kontingent. Abgerechnet wird, was Postmark angenommen hat — nach einer Staffel, die in Stripe hinterlegt ist. Im Sandbox-Modus des Kunden nimmt Postmark an, stellt nichts zu und es wird nichts berechnet.

NewsletterKit meldet täglich die Zahl der angenommenen E-Mails an Stripe. Dort entsteht daraus die Rechnung — gemeinsam mit den anderen Produkten, die derselbe Kunde nutzt. Beträge, Stufen und Rechnungen stehen deshalb ausschließlich in Stripe; GET /v1/usage liefert Mengen, das Monatslimit und den Rest.

Der Zugang ist davon getrennt und ein rein administrativer Schalter. Ist er gesperrt, antworten versendende Endpunkte (/v1/templates/{id}/send, /v1/send-jobs/…/start) mit 403 forbidden, während lesende Endpunkte erreichbar bleiben. Dazu kommt die Freischaltung des Versands je Kunde: Erst wenn Postmark-Server, Broadcast-Stream, verifizierte Absender und beide Footer im Admin grün sind, geht etwas raus.

Geplant. Heute holt das Portal ab: Job-Status über GET /v1/send-jobs/{id}, Mail-Status über GET /v1/messages/{id}, Sperren über GET /v1/suppressions — idempotent, ohne Zustand bei uns. Die Zustellung ans Portal (job.completed, message.bounced, suppression.changed) kommt später als Zusatz auf dieselben Daten; die Registrierung einer URL ist schon möglich.

Signatur verifizieren (so wird es aussehen)

Header X-NewsletterKit-Signature hat die Form t=<unix>,v1=<hmac>. Der HMAC-SHA256 wird über "<t>.<roher Body>" mit deinem Webhook-Secret gebildet. Immer verifizieren, bevor du das Event verarbeitest.

// app/api/webhooks/newsletterkit/route.ts — geplant, so wird es aussehen
import crypto from "node:crypto";

export async function POST(req: Request) {
  const raw = await req.text();
  // Header-Form: t=<unix>,v1=<hmac>
  const header = req.headers.get("X-NewsletterKit-Signature") ?? "";
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("=")),
  );
  const expected = crypto
    .createHmac("sha256", process.env.NEWSLETTERKIT_WEBHOOK_SECRET!)
    .update(`${parts.t}.${raw}`) // HMAC über "<t>.<roher Body>"
    .digest("hex");
  if (parts.v1 !== expected) return new Response("invalid signature", { status: 401 });

  const event = JSON.parse(raw); // { event: "job.completed", … }
  // … schnell 200 zurückgeben, Verarbeitung asynchron
  return new Response("ok");
}

Event-Payload

{
  "event": "job.completed",
  "delivery_id": "wd_2026_0001",
  "send_job_id": "f90c0326-…",
  "recipients": { "total": 12000, "accepted": 11812, "suppressed": 188 },
  "occurred_at": "2026-09-05T08:04:00Z"
}

Zwei Fakten, zwei Systeme: Die Werbeeinwilligung liegt im Kundensystem, die Sperre (Abmeldung, Bounce, Beschwerde) bei Postmark. NewsletterKit spiegelt die Sperren zum Abholen — und das Kundensystem leitet daraus ab, wer eine Mail bekommen darf. Das Beispiel dazu steht oben im Ablauf „Sperren ins CRM“.

• Die Einwilligung liegt im Kundensystem. Die Werbeeinwilligung ist ein dokumentierter Akt: Double-Opt-in mit Zeitpunkt, Text und Herkunft. NewsletterKit und Postmark kennen sie nicht und fragen nie danach. Das Feld gehört dem Kundensystem, und nur das Kundensystem schreibt es.
• Die Sperre liegt bei Postmark. Abmeldung, Hard Bounce und Spam-Beschwerde entstehen bei Postmark und werden dort durchgesetzt: Ein gesperrter Empfänger wird je Nachricht abgewiesen, egal was das Kundensystem über ihn glaubt. NewsletterKit spiegelt Sperren und gibt sie weiter; übersteuern kann sie niemand.
• „Darf E-Mails empfangen“ ist eine Ableitung, kein Feld. Einwilligung vorhanden UND keine aktive Sperre. Im CRM sind das zwei getrennte Felder: marketing_consent schreibt nur das Kundensystem, email_suppressed schreibt nur der Abgleich mit NewsletterKit. Wer beide zu einem Boolean verschmilzt, verliert die Wiederkehr: Ein Abgemeldeter, der sich neu einträgt, hätte wieder Einwilligung, bliebe aber bei Postmark gesperrt.
• Abgleich durch Abholen. Das Kundensystem ruft regelmäßig GET /v1/suppressions?since=<letzter Stand> und schreibt die Antwort in sein Sperrfeld — gesetzte wie aufgehobene Sperren. Ein Cron alle paar Minuten reicht: Beim Versand sperrt Postmark ohnehin zuletzt, ein verspäteter Abgleich kostet höchstens eine abgewiesene Nachricht.
• Wiederkehr nur nach neuem Double-Opt-in. Wer sich abgemeldet hat und später neu einträgt, bleibt bei Postmark gesperrt, bis das Kundensystem POST /v1/suppressions/reactivate ruft. Das geschieht nach der Bestätigung, nie beim Setzen eines Hakens. Nach einer Spam-Beschwerde gibt es keine Reaktivierung; die Adresse bleibt dauerhaft gesperrt.
• Der Abmeldelink kommt von Postmark. Newsletter enthalten den Abmeldelink über den Footer des Kunden; die Adresse dahinter setzt Postmark je Empfänger ein, und die Abmeldung führt auf Postmarks Abmeldeseite. Der Aufrufer übergibt keinen unsubscribe_url. Eine Abmeldung gilt für alle Newsletter dieses Kunden — Listen und Segmente kennt Postmark nicht.
• Transaktionale Mails bleiben erreichbar. Sperren gelten je Stream. Ein abgemeldeter Empfänger bekommt weiterhin transaktionale Mails wie Double-Opt-in, Bestellbestätigung oder Passwort-Reset; gesperrt sind nur Newsletter.
• Listen und Segmente gehören dem Kundensystem. NewsletterKit kennt keine Listen. Welche Kontakte einen Newsletter bekommen, entscheidet das Kundensystem beim Zusammenstellen der Empfänger — gefiltert nach Einwilligung und Sperre. Adressen reisen nur mit dem Versandjob und werden nach dessen Abschluss gelöscht; es bleibt der Hash und die Mail-ID.

Die Version steckt im Pfad-Präfix (/v1). Innerhalb von v1 sind nur additive, nicht-brechende Änderungen erlaubt — neue Felder/Endpunkte kommen hinzu, bestehende verschwinden nicht.

• Pinnen: optionaler Header NewsletterKit-Version: v1 fixiert das Verhalten unabhängig vom Account-Default.
• Breaking Changes erscheinen nur in einer neuen Major-Version (/v2) — niemals in /v1.
• Deprecation: abgekündigte Versionen laufen mind. 6 Monate weiter; Hinweise via Sunset-Header + Changelog.