GET/api/v1/publikationen
Alle Publikationen (Newsletter) des Kontos mit Anzahl aktiver Leser.
MCP-Werkzeug publikationen_liste · liest nur · auch bei gesperrtem Konto
Keine Felder.
API und MCP
Alles, was Sie im Dashboard tun, geht auch über die REST-API oder einen KI-Agenten — mit einer Ausnahme: Senden entscheidet immer ein Mensch. Die Endpunkte auf dieser Seite sind aus dem Code erzeugt, in dem zugestellt sie ausführt.
Überblick
Jede Funktion von zugestellt ist eine Aktion mit Namen, Eingabe und Rechten. Dieselbe Aktion läuft im Dashboard, als REST-Endpunkt und als MCP-Werkzeug mit identischen Feldern und Prüfungen.
- REST-API
https://zugestellt.ch/api/v1- MCP-Server
https://zugestellt.ch/mcp- Anmeldeformular
https://zugestellt.ch/api/anmelden
Über API und MCP stehen 24 Aktionen bereit. 12 weitere — darunter senden, Versand fortsetzen, Importe und API-Schlüssel — gibt es nur im Dashboard. Ein Aufruf über die API beantwortet zugestellt dort mit 403 nur_mensch.
Authentifizierung
Einen API-Schlüssel erstellen Admins im Dashboard unter «API und KI-Agenten». Er beginnt mit zst_ und wird genau einmal angezeigt; zugestellt speichert nur einen Fingerabdruck. Ältere Schlüssel mit nsy_ gelten weiter.
Senden Sie den Schlüssel bei jeder Anfrage im Header:
Authorization: Bearer zst_…Jeder Schlüssel gehört zu einem Konto und hat eine von zwei Stufen:
- Entwürfe, Leser, Berichte (
voll): alle Aktionen, die nicht dem Dashboard vorbehalten sind. - Nur Anmeldungen (
anmeldungen): nur kontakt_hinzufuegen. Richtig für ein CRM oder ein eigenes Formular.
Widerrufene Schlüssel gelten sofort nicht mehr. Jede schreibende Aktion wird mit dem Präfix des Schlüssels protokolliert.
Anfragen und Antworten
- GET: Felder als Query-Parameter, zum Beispiel
?publikation_id=…&status=aktiv.limitundoffsetwerden als Zahl gelesen, alles andere als Text. - POST und PATCH: Felder als JSON im Körper, mit
Content-Type: application/json. - Die Antwort ist JSON: bei Erfolg direkt das Ergebnis, bei einem Fehler ein Objekt mit
fehlerundcode. - IDs sind UUIDs. Zeitpunkte schreiben Sie nach ISO 8601 mit Zeitzone, zum Beispiel
2026-11-12T08:00:00+01:00. - Unbekannte Felder werden ignoriert.
Fehler
Jeder Fehler hat einen HTTP-Status, einen festen code für Ihr Programm und eine Meldung auf Deutsch für Menschen:
{
"fehler": "publikation_id: Invalid UUID",
"code": "eingabe",
"details": [ { "path": ["publikation_id"], "message": "Invalid UUID", … } ]
}- 400 eingabe
- Der Körper einer POST- oder PATCH-Anfrage ist kein JSON.
- 401 nicht_angemeldet
- Schlüssel fehlt, ist widerrufen oder hat das falsche Format.
- 403 nur_mensch
- Die Aktion ist nur im Dashboard möglich, zum Beispiel senden. Fordern Sie stattdessen eine Freigabe an.
- 403 keine_rechte
- Der Schlüssel hat die Stufe «Nur Anmeldungen» und darf diese Aktion nicht.
- 404 unbekannt
- Diesen Pfad gibt es mit dieser Methode nicht.
- 404 nicht_gefunden
- Die ID gibt es in Ihrem Konto nicht.
- 409 konflikt
- Der Zustand lässt die Aktion nicht zu, etwa wenn eine Ausgabe kein Entwurf mehr ist. Die Meldung nennt den Grund.
- 422 eingabe
- Ein Feld fehlt oder ist ungültig. «details» enthält jede Abweichung mit Pfad.
- 422 adresse_…
- Die E-Mail-Adresse wurde abgelehnt: adresse_ungueltig, adresse_wegwerf oder adresse_tippfehler (mit Vorschlag in der Meldung). Mit «tippfehler_ok»: true übernehmen Sie die Adresse trotzdem.
- 423 konto_gesperrt
- Das Konto ist gesperrt. Lesen und Anhalten bleiben möglich.
- 500 fehler
- Unerwarteter Fehler. Er ist bei uns protokolliert.
- 503 ses_fehlt
- Der Mailversand ist für diese Umgebung noch nicht eingerichtet.
Einzelne Aktionen haben eigene Codes, etwa vorpruefung oder domain_nicht_bereit; die Meldung sagt dann, was fehlt. Wiederholen Sie Anfragen mit 4xx nicht unverändert. Bei 5xx lohnt ein späterer neuer Versuch.
Beispiele
curl https://zugestellt.ch/api/v1/publikationen \
-H "Authorization: Bearer zst_…"curl -X POST https://zugestellt.ch/api/v1/kontakte \
-H "Authorization: Bearer zst_…" \
-H "Content-Type: application/json" \
-d '{
"publikation_id": "…",
"email": "anna@beispiel.ch",
"vorname": "Anna",
"tags": ["kunde", "zug"],
"einwilligung": "Anmeldung am Messestand, 12.11.2026"
}'curl -X POST https://zugestellt.ch/api/v1/ausgaben \
-H "Authorization: Bearer zst_…" \
-H "Content-Type: application/json" \
-d '{
"publikation_id": "…",
"titel": "November",
"betreff": "Neue Öffnungszeiten ab Dezember",
"vorschautext": "Und ein Gutschein für Stammkunden.",
"inhalt": [
{ "typ": "ueberschrift", "text": "Neue Öffnungszeiten" },
{ "typ": "absatz", "text": "{{vorname|Guten Tag}}, ab 1. Dezember sind wir **samstags bis 16 Uhr** für Sie da." },
{ "typ": "knopf", "text": "Termin buchen", "url": "https://www.ihre-firma.ch/termin" }
]
}'curl -X POST https://zugestellt.ch/api/v1/ausgaben/vorpruefen \
-H "Authorization: Bearer zst_…" -H "Content-Type: application/json" \
-d '{ "ausgabe_id": "…" }'
curl -X POST https://zugestellt.ch/api/v1/ausgaben/freigabe-anfordern \
-H "Authorization: Bearer zst_…" -H "Content-Type: application/json" \
-d '{ "ausgabe_id": "…", "geplant_fuer": "2026-11-12T08:00:00+01:00" }'Danach sieht ein Mensch die Ausgabe im Dashboard als «zur Freigabe» und entscheidet, ob und wann sie gesendet wird. Ändert Ihr Programm die Ausgabe danach, wird die Freigabe zurückgesetzt.
curl "https://zugestellt.ch/api/v1/uebersicht" \
-H "Authorization: Bearer zst_…"Inhalt einer Ausgabe
Der Inhalt ist eine Liste von Blöcken, höchstens 300. Rohes HTML gibt es nicht; daraus entstehen Mail, Klartext und Webseite. Im Text gelten **fett**, *kursiv*, [Text](https://…) und {{vorname|Ersatz}}.
ueberschrift- text, stufe (1–3, Standard 2)
absatz- text
liste- punkte (Liste von Texten), nummeriert (Standard false)
bild- url, alt, optional link und bildunterschrift
knopf- text, url
zitat- text, optional quelle
trenner- keine Felder
Links sind nur mit https://, http:// oder mailto: erlaubt. Die gerenderte Mail darf höchstens 100 KB gross sein.
Alle Endpunkte
Pfade relativ zu https://zugestellt.ch/api/v1. Der Name des MCP-Werkzeugs ist jeweils der Name der Aktion.
Newsletter
POST/api/v1/publikationen
Neue Publikation mit Absender und Postadresse anlegen.
MCP-Werkzeug publikation_erstellen
namePflicht- string1–120 Zeichen
kuerzelPflicht- string
absender_namePflicht- string1–120 Zeichen
absender_adressePflicht- string (E-Mail)
antwort_an- string (E-Mail)
postadressePflicht- string5–300 Zeichen
double_opt_in- booleanStandard true
GET/api/v1/publikationen/lesen
Alle Einstellungen eines Newsletters (Absender, Design, Willkommensmail, Formular).
MCP-Werkzeug publikation_lesen · liest nur · auch bei gesperrtem Konto
publikation_idPflicht- string (uuid)
Nur im Dashboard
publikation_aendern— Einstellungen eines Newsletters ändern: Name, Absender, Postadresse, Design, Willkommensmail, erlaubte Websites fürs Formular.
Leser und Tags
GET/api/v1/kontakte
Leser einer Publikation, optional nach Status oder Adresse gefiltert.
MCP-Werkzeug kontakte_liste · liest nur · auch bei gesperrtem Konto
publikation_idPflicht- string (uuid)
status- "unbestaetigt" | "aktiv" | "abgemeldet" | "unzustellbar" | "beschwerde" | "ruhend"
suche- stringhöchstens 100 Zeichen
tag- stringhöchstens 50 Zeichen
limit- integer1 bis 500 · Standard 50
offset- integerab 0 · Standard 0
POST/api/v1/kontakte
Leser hinzufügen. Über API und MCP gilt immer Double-Opt-in: der Leser bestätigt per Mail. Bounces und Beschwerden bleiben gesperrt.
MCP-Werkzeug kontakt_hinzufuegen · auch mit Schlüssel «Nur Anmeldungen»
publikation_idPflicht- string (uuid)
emailPflicht- stringhöchstens 254 Zeichen
vorname- stringhöchstens 100 Zeichen
nachname- stringhöchstens 100 Zeichen
tags- string[]höchstens 20 Einträge
einwilligung- stringhöchstens 500 Zeichen
direkt_aktiv- boolean
tippfehler_ok- boolean
POST/api/v1/kontakte/abmelden
Einen Leser von seiner Publikation abmelden.
MCP-Werkzeug kontakt_abmelden · auch bei gesperrtem Konto
kontakt_idPflicht- string (uuid)
GET/api/v1/tags
Alle Tags einer Publikation mit der Zahl aktiver und aller Leser.
MCP-Werkzeug tags_liste · liest nur · auch bei gesperrtem Konto
publikation_idPflicht- string (uuid)
POST/api/v1/kontakte/tags
Tags bei bis zu 1000 Lesern setzen oder entfernen. Tags gelten ohne Gross/Klein.
MCP-Werkzeug kontakte_taggen
publikation_idPflicht- string (uuid)
kontakt_idsPflicht- string (uuid)[]1 bis 1000 Einträge
hinzufuegen- string[]höchstens 20 Einträge
entfernen- string[]höchstens 20 Einträge
Nur im Dashboard
kontakt_loeschen— Leser endgültig löschen (z. B. auf Wunsch nach nDSG). Abgemeldete, Bounces und Beschwerden bleiben als Adresse gesperrt.kontakte_export— Alle Leser einer Publikation (optional nach Status oder Tag) als Zeilen für eine CSV.
Ausgaben
GET/api/v1/ausgaben
Ausgaben (Beiträge) einer Publikation, neueste zuerst.
MCP-Werkzeug ausgaben_liste · liest nur · auch bei gesperrtem Konto
publikation_idPflicht- string (uuid)
status- "entwurf" | "freigabe_offen" | "geplant" | "sendet" | "pausiert" | "gesendet" | "abgebrochen"
GET/api/v1/ausgaben/lesen
Eine Ausgabe mit Inhalt und den Zahlen ihrer Versände.
MCP-Werkzeug ausgabe_lesen · liest nur · auch bei gesperrtem Konto
ausgabe_idPflicht- string (uuid)
POST/api/v1/ausgaben
Neuen Entwurf anlegen. Inhalt als Blöcke (ueberschrift, absatz mit **fett**/*kursiv*/[Link](url), liste, bild, knopf, zitat, trenner). Versendet nichts.
MCP-Werkzeug ausgabe_erstellen
publikation_idPflicht- string (uuid)
titel- stringhöchstens 200 Zeichen
betreff- stringhöchstens 200 Zeichen
vorschautext- stringhöchstens 300 Zeichen
inhalt- Block[]höchstens 300 Einträge
slug- string
PATCH/api/v1/ausgaben
Entwurf ändern. Eine offene Freigabe wird dabei zurückgesetzt — sie galt für den alten Inhalt.
MCP-Werkzeug ausgabe_aendern
ausgabe_idPflicht- string (uuid)
titel- stringhöchstens 200 Zeichen
betreff- stringhöchstens 200 Zeichen
vorschautext- stringhöchstens 300 Zeichen
inhalt- Block[]höchstens 300 Einträge
slug- string
zielgruppe- { mit, ohne }
POST/api/v1/ausgaben/vorpruefen
Prüft eine Ausgabe vor dem Versand: was blockiert, was nur eine Warnung ist, wie gross die Mail ist.
MCP-Werkzeug ausgabe_vorpruefen · liest nur · auch bei gesperrtem Konto
ausgabe_idPflicht- string (uuid)
POST/api/v1/ausgaben/freigabe-anfordern
Bittet einen Menschen, die Ausgabe freizugeben (optional mit Wunschzeit). Senden kann nur ein Mensch im Dashboard.
MCP-Werkzeug freigabe_anfordern
ausgabe_idPflicht- string (uuid)
geplant_fuer- string (ISO 8601 mit Zeitzone)
POST/api/v1/ausgaben/planung-aufheben
Einen geplanten Versand aufheben. Die Ausgabe wird wieder Entwurf und braucht eine neue Freigabe.
MCP-Werkzeug planung_aufheben · auch bei gesperrtem Konto
ausgabe_idPflicht- string (uuid)
PATCH/api/v1/ausgaben/absender
Für diese Ausgabe einen anderen Absendernamen, eine andere Antwortadresse oder einen eigenen UTM-Kampagnennamen setzen (leer = wie der Newsletter).
MCP-Werkzeug ausgabe_absender
ausgabe_idPflicht- string (uuid)
absender_name- stringhöchstens 120 Zeichen
antwort_an- string (E-Mail) | ""leer = wie beim Newsletter
utm_kampagne- string | ""leer = wie beim Newsletter
Nur im Dashboard
freigeben— Freigabe durch einen Menschen: sendet sofort oder plant den Versand. Senden lässt sich nicht rückgängig machen.testmail_senden— Die Ausgabe als Testmail an bis zu drei Adressen senden (Betreff mit [Test]). Nur im Dashboard.
Versand
POST/api/v1/versaende/pausieren
Laufenden Versand anhalten. Bereits gesendete Mails bleiben gesendet.
MCP-Werkzeug versand_pausieren · auch bei gesperrtem Konto
versand_idPflicht- string (uuid)
Nur im Dashboard
versand_fortsetzen— Pausierten Versand fortsetzen (nur Mensch). Nach einer Pause wegen Bounces stoppt danach nur noch die Sperr-Schwelle.
Übersicht und Berichte
GET/api/v1/uebersicht
Kennzahlen eines Zeitraums (Standard: letzte 30 Tage) im Vergleich zum gleich langen Zeitraum davor, optional für einen Newsletter.
MCP-Werkzeug uebersicht · liest nur · auch bei gesperrtem Konto
von- string (ISO 8601 mit Zeitzone)
bis- string (ISO 8601 mit Zeitzone)
publikation_id- string (uuid)
GET/api/v1/berichte
Alle Versände eines Newsletters mit Zustellung, Öffnungen, Klicks, Bounces und Abmeldungen.
MCP-Werkzeug berichte_liste · liest nur · auch bei gesperrtem Konto
publikation_idPflicht- string (uuid)
GET/api/v1/berichte/versand
Bericht eines Versands: Kennzahlen, geklickte Links (Leser pro Link), Öffnungen nach Stunden, Mail-Anbieter.
MCP-Werkzeug bericht · liest nur · auch bei gesperrtem Konto
versand_idPflicht- string (uuid)
Importe
GET/api/v1/importe
Die letzten Importe eines Newsletters mit Ergebnis.
MCP-Werkzeug importe_liste · liest nur · auch bei gesperrtem Konto
publikation_idPflicht- string (uuid)
Nur im Dashboard
import_starten— Einen Kontakt-Import beginnen. Pflicht: wie die Leser eingewilligt haben. Danach Zeilen mit import_teil senden und mit import_abschliessen beenden.import_teil— Bis zu 1000 Zeilen eines Imports. Status pro Zeile: aktiv, abgemeldet, unzustellbar oder beschwerde. Niemand wird über den Import wieder angemeldet; Abmeldungen und Bounces werden übernommen.import_abschliessen— Import beenden und das Ergebnis erhalten (neu, aktualisiert, abgemeldet, gesperrt, übersprungen).
Absender-Domains
GET/api/v1/domains
Absender-Domains des Kontos mit Stand von DKIM, MAIL FROM und DMARC.
MCP-Werkzeug domains_liste · liest nur · auch bei gesperrtem Konto
Keine Felder.
POST/api/v1/domains
Absender-Domain hinzufügen. Gibt die DNS-Einträge zurück, die beim Domain-Anbieter zu setzen sind.
MCP-Werkzeug domain_hinzufuegen
domainPflicht- stringhöchstens 253 Zeichen
POST/api/v1/domains/pruefen
DNS-Einträge einer Domain erneut prüfen und den Stand speichern.
MCP-Werkzeug domain_pruefen · auch bei gesperrtem Konto
domainPflicht- string
API-Schlüssel
Nur im Dashboard
schluessel_liste— Aktive API-Schlüssel des Kontos (ohne den Schlüssel selbst).schluessel_erstellen— Neuen API-Schlüssel erzeugen. Er wird genau einmal angezeigt.schluessel_widerrufen— API-Schlüssel sofort ungültig machen.
MCP-Server
Der MCP-Server spricht Streamable HTTP (Protokoll 2025-06-18), zustandslos und nur mit JSON-Antworten. Er nimmt POST-Anfragen unter https://zugestellt.ch/mcp entgegen, auch als Batch. Die Werkzeuge sind die 24 Aktionen oben, mit denselben Feldern; Hinweise wie «liest nur» gehen als Annotationen mit.
Angemeldet wird mit demselben API-Schlüssel als Bearer-Token.
claude mcp add --transport http zugestellt https://zugestellt.ch/mcp \
--header "Authorization: Bearer zst_…"{
"mcpServers": {
"zugestellt": {
"type": "http",
"url": "https://zugestellt.ch/mcp",
"headers": {
"Authorization": "Bearer zst_…"
}
}
}
}Connectors in claude.ai und ChatGPT melden sich über OAuth an. Das unterstützt zugestellt noch nicht; bis dahin verbinden Sie Claude Code, Cursor oder einen eigenen Agenten mit dem Schlüssel.
curl -X POST https://zugestellt.ch/mcp \
-H "Authorization: Bearer zst_…" \
-H "Content-Type: application/json" \
-d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'Ohne gültigen Schlüssel antwortet der Server mit HTTP 401 und dem JSON-RPC-Fehler -32001. Schlägt eine Aktion fehl, enthält das Ergebnis isError: true und Code und Meldung wie bei der REST-API.
Anmeldeformular
POST https://zugestellt.ch/api/anmelden nimmt Anmeldungen von Ihrer Website an. Es braucht keinen Schlüssel; der Newsletter wird über sein Kürzel bestimmt. Die Anleitung für Website-Betreiber steht im Hilfe-Artikel.
newsletter- Kürzel des Newsletters (Pflicht)
email- E-Mail-Adresse (Pflicht)
vorname- optional, höchstens 100 Zeichen
website- unsichtbares Feld gegen Roboter, muss leer bleiben
Als Formular (application/x-www-form-urlencoded) leitet zugestellt mit 303 auf die Archivseite/p/<kürzel>?anmeldung=… weiter. Mit Content-Type: application/json oder Accept: application/json kommt JSON zurück. CORS ist für alle Herkünfte offen.
curl -X POST https://zugestellt.ch/api/anmelden \
-H "Content-Type: application/json" \
-d '{ "newsletter": "ihr-kuerzel", "email": "anna@beispiel.ch", "vorname": "Anna" }'
{ "ok": true, "ergebnis": "bestaetigen" }- 200 bestaetigen
- Bestätigungsmail ist unterwegs (Double-Opt-in).
- 200 angemeldet
- Ohne Double-Opt-in direkt angemeldet.
- 422 fehler_adresse
- Adresse ungültig, Wegwerf-Adresse oder Tippfehler.
- 429 fehler_zu_viele
- Mehr als 5 Versuche pro IP in 10 Minuten oder Flut auf den Newsletter.
- 403 fehler_seite
- Die Website steht nicht in der Liste der erlaubten Websites.
- 404 fehler_unbekannt
- Kürzel unbekannt.
Ob eine Adresse neu, schon angemeldet oder gesperrt ist, verrät die Antwort absichtlich nicht. Die erlaubten Websites prüft zugestellt am Origin-Header; Anfragen von einem Server ohne diesen Header werden bei gefüllter Liste abgelehnt. Von einem Server aus nehmen Sie darum besser kontakt_hinzufuegen mit einem Schlüssel der Stufe «Nur Anmeldungen».