Die API
Es gibt keinen privaten Endpunkt. Nicht einmal für die Oberfläche.
Die meisten Produkte haben zwei APIs: die dokumentierte, die Ihnen angeboten wird, und die interessantere, die ihre eigenen Bildschirme verwenden. Die zweite ist immer besser, und Sie kommen nie an sie heran. Hier gibt es genau eine, und die Oberfläche ist ein Client davon wie alles andere – das ist eine Einschränkung für uns und der Grund, warum alles, was Sie bauen wollen, möglich ist.
Was diese Regel tatsächlich kostet
Sie bedeutet, dass ein Bildschirm gelegentlich warten muss, bis die API stimmt, statt für ein bequemes Feld an ihr vorbeizugreifen. Der Tag, an dem ein Bildschirm etwas braucht, das die öffentliche API nicht liefern kann, ist der Tag, an dem die API falsch ist – und die Korrektur ist die API.
Der Gewinn ist, dass drei sehr unterschiedliche Clients fast nichts extra kosten. Der MCP-Server ist ein Client. Eine dash-b-Kachel ist ein Client. Ihr eigenes Skript ist ein Client. Keiner von ihnen ist Bürger zweiter Klasse, der sich um eine für jemand anderen entworfene Oberfläche herumarbeitet – denn es gibt keine andere Oberfläche, hinter die man zurückfallen könnte.
Dokumentiert und ausgeübt
OpenAPI wird unter /docs generiert, und jede Route hat einen Test, der das Beispiel in der Dokumentation ist. Dokumentation, die getrennt vom Code geschrieben wird, driftet innerhalb eines Monats auseinander; Dokumentation, die den Build scheitern lässt, wenn sie falsch ist, tut das nicht.
Anmeldung
Ihr castomo-Konto über den Authorization-Code-Flow mit PKCE – dasselbe Konto, das Sie für dash-b und den Rest der Familie verwenden. Eine Seite ohne eigenen Server führt diesen Flow problemlos aus; genau dafür wurde er entworfen. Für Maschine-zu-Maschine-Aufgaben: ein projektbezogener API-Schlüssel.
- 1Personen
/v1/contacts·/lists·/segments·/tags·/imports - 2Inhalt
/v1/creatives, mit Validierung, Vorschau und Rendern pro Ziel - 3Automatisierung
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Rundfunk
/v1/campaigns, mit Zielgruppe, Materialisierung, Planung und Versand als getrennte Schritte - 5Eingehende Ereignisse
/v1/events– die Ereignisse Ihrer eigenen Anwendung, als Auslöser - 6Zustellung
/sender-identities·/domains·/apps·/webhooks - 7Zahlen
/v1/reports/*und/track/*auf dem Tracking-Host
OpenAPI unter /docs/mcp im selben Prozess
Konventionen
Dieselbe Form wie bei jedem anderen castomo-Dienst
Was wichtiger ist, als es klingt. Wenn Sie bereits einen dieser Dienste aufrufen, wissen Sie bereits, wie dieser antwortet, scheitert und paginiert.
Ein einziger Fehler-Umschlag
Jeder Fehlschlag hat dieselbe Form: ein stabiler Code und eine Meldung für Menschen. Keine Route erfindet ihre eigene Art, unglücklich zu sein.
Cursor-Paginierung
Keine Offsets. Eine Liste, die sich ändert, während Sie sie durchlaufen, überspringt oder wiederholt still keine Zeilen – was Offset-Paginierung still und ständig tut.
Idempotenzschlüssel
Auf jeder verändernden Route. Wiederholen Sie eine Anfrage, bei der Sie sich nicht sicher sind, ob sie ankam, und Sie erhalten dieselbe Antwort statt eines zweiten Kontakts, einer zweiten Kampagne oder eines zweiten Versands.
Auf ein Projekt beschränkt
Ein Token adressiert sowohl einen Tenant als auch ein Projekt. Sicherheit auf Zeilenebene wird in der Datenbank selbst durchgesetzt, nicht durch das Erinnern an eine zusätzliche Klausel.
Webhooks nach außen
Signiert, mit Backoff wiederholt und mindestens einmal zugestellt — Ihr Endpunkt sollte daher ebenfalls idempotent sein. Die Ereignisse verwenden denselben Wortschatz wie die Berichte.
Löschung und Export
Ein Kontakt kann über die API exportiert oder gelöscht werden, und eine Löschung erreicht über die interne Lane der Produktfamilie jeden Schwesterdienst, der eine Kopie vorhält.
Alles, was die Oberfläche kann, kann ein POST.
Ereignisse sind der interessante Teil
Alles andere auf dieser Seite ist Installationsarbeit, die Sie erwarten würden. POST /v1/events ist die Route, die ändert, wofür das Produkt da ist.
Ihre Anwendung weiß bereits Dinge, die kein Marketing-Tool beobachten kann: wer das Onboarding abgeschlossen hat, wer eine Kollegin eingeladen hat, wer ein Limit erreicht hat, wer an einem Sonntagnachmittag seine Daten exportiert hat. Senden Sie diese als Ereignisse mit Ihrem eigenen Token, und jedes davon wird zu einem Auslöser, einer Bedingung und einem Segment.
Der Rest folgt aus dem Kontaktmodell. Ereignisse werden angehängt, nie bearbeitet; sie sind das Protokoll, an dem das gesamte Produkt hängt. Ein Trichter, der auf einem von Ihnen definierten Ereignis auslöst, ist keine Integration — er verwendet denselben Mechanismus wie message_opened, nur mit einem anderen Namen darin.
- 1Sie senden es
POST /v1/events— ein Name, ein Kontakt, eine Nutzlast, ein Idempotenzschlüssel. - 2Es trifft einAngehängt an das Protokoll des Kontakts. Niemand anderes muss wissen, dass es existiert.
- 3Ein Trichter startetJeder Trichter, dessen Eintritt dieses Ereignis nennt, für jeden Kontakt, der gemäß seiner Eintrittsspezifikation infrage kommt.
- 4Andere Trichter verzweigen daran„Ist dieses Ereignis in den letzten 14 Tagen eingetreten“ ist ein gewöhnliches Segmentprädikat.
- iUnd es beendet DurchläufeEin Zielknoten, der dasselbe Ereignis nennt, stoppt eine Sequenz in dem Moment, in dem die Person die Handlung ausführt.
Ihr WortschatzIhr Token
Grenzen, die Sie vor dem Aufbau kennen sollten
ClickSomo speichert drei Kennungen über Sie — einen Tenant, ein Projekt und einen Benutzer, als opake IDs — und nichts weiter. Kein Passwort, kein Profil, keine Karte, keine Rechnung. Planlimits kommen als Zahlen an: wie viele Kontakte, wie viele Sendungen, wie viele Generierungen. Zahlungsbezogene Daten überschreiten diese Linie in keine Richtung.
Ihre Kontakte gehören Ihnen. Sie sind der Datenverantwortliche; wir sind der Auftragsverarbeiter. Es gibt keinen Weg, über den ein anderes Produkt der Familie Ihre Kontaktliste lesen oder schreiben könnte, und keine Ingest-Lane, die es dafür nutzen könnte.
Wenn Sie dies ernsthaft prüfen: Lesen Sie /docs, bevor Sie weitere Teile dieser Website lesen. Die API ist die ehrliche Beschreibung dessen, was das Produkt tut, und jede Aussage auf diesen Seiten entspricht einer Route oder einer Knotenart, die Sie dort finden. Wenn sich das Schema ändert, ändern sich diese Seiten.