Blöcke · NewsletterKit API Docs

GET

/v1/blocks

Listet die für den Kunden freigeschalteten, aktiven Blöcke. Jeder Eintrag enthält die stabile id (UUID — der unveränderliche Referenzschlüssel), den slug (menschenlesbares Label) und das Parameter-Schema (name, type, required, fallback, hide_if_missing, example). Diese Liste sagt einem Client, welche Blöcke er in einem Template verwenden darf und welche Werte jeder Block erwartet. tags sind die vom Admin gepflegten Kategorien des Blocks — für Logik zählt der slug, label ist nur die Anzeige. series nennt die Familie, aus der ein Block stammt (höchstens eine, sonst null): Blöcke derselben Serie sind zusammen entworfen und passen optisch zueinander — rein zum Gruppieren, ein Template darf Serien mischen. Ein Template referenziert einen Block über seine id, nicht über den slug — Slugs und Namen können sich ändern, die id bleibt stabil und schützt gespeicherte Templates vor Brüchen. Read-only, Scope reporting genügt.

Request · Next.js

const res = await fetch(`https://api.newsletterkit.ventureon.io/v1/blocks`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.NEWSLETTERKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": [
    {
      "id": "b1a2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
      "slug": "hero-text",
      "name": "Hero-Text",
      "tags": [{ "slug": "content", "label": "Inhalt" }],
      "series": { "slug": "journal", "label": "Journal" },
      "description": "Große Überschrift mit Fließtext.",
      "version": 1,
      "params": [
        { "name": "headline", "label": "Überschrift", "type": "string", "required": true,  "fallback": null, "hide_if_missing": false, "example": "Willkommen zum Sommer-Update" },
        { "name": "body",     "label": "Fließtext",   "type": "text",   "required": true,  "fallback": null, "hide_if_missing": false, "example": "Hier kommen die wichtigsten Neuigkeiten." }
      ]
    }
  ],
  "request_id": "…"
}

tile_url zeigt auf die fertig gerenderte Kachel des Blocks (GET /v1/blocks/{id}/tile). Ein Template referenziert Blöcke über die unveränderliche id (UUID), nicht über den slug — so brechen gespeicherte Kompositionen nicht, wenn ein Admin Slug oder Name eines Blocks umbenennt. Welche Blöcke freigeschaltet sind, steuert ein Admin pro Kunde (customer_blocks). MJML-Templates unterstützen bedingte Abschnitte: {{#param}}…{{/param}} rendert nur, wenn param einen nicht-leeren Wert hat (optionale Elemente wie ein Logo oder ein AGB-Link verschwinden, wenn nicht gesetzt) — zusätzlich zum einfachen {{param}}. Die Detail-Doku je Block (alle Parameter + Beispielwerte) liefert die Seite „Block-Parameter“.

GET

/v1/blocks/{id}/tile

Die Kachel für die Blockauswahl im Builder: der Block mit seinen Beispielwerten, gerendert im Design und mit den Marken-Werten des Kunden — fertiges HTML für ein iframe mit srcdoc. Gecacht; ändert sich, sobald Block oder Design-Regeln sich ändern. Ändert der Admin eine Farbe, zeigt die nächste Kachel sie ohne Zutun des Portals. Scope reporting.

Path-Parameter

Name	Typ	Pflicht	Beschreibung
id	string (UUID)	erforderlich	Die block_id aus GET /v1/blocks. `z. B. 0d384008-1a29-4fbb-bfa8-a2509e426396`

Request · Next.js

const id = "0d384008-1a29-4fbb-bfa8-a2509e426396";

const res = await fetch(`https://api.newsletterkit.ventureon.io/v1/blocks/${id}/tile`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.NEWSLETTERKIT_API_KEY}`,
    },
});
const data = await res.json();

Response 200

{
  "data": { "block_id": "0d384008-…", "slug": "beyond-hero", "html": "<!doctype html>…" },
  "request_id": "…"
}

html ist null, wenn ein Pflichtwert des Blocks kein Beispiel hat — dann gibt es kein Bild, sondern eine Lücke.