L'API
Non esiste un endpoint privato. Nemmeno per l'interfaccia.
La maggior parte dei prodotti ha due API: quella documentata che ti viene offerta, e quella interessante che i loro schermi usano. La seconda è sempre migliore, e non ti è mai permesso avvicinarti. Qui ce n'è una sola, e l'interfaccia ne è un client come qualsiasi altra cosa — il che è un vincolo per noi, ed è il motivo per cui tutto ciò che vuoi costruire è possibile.
Quanto costa davvero quella regola
Significa che uno schermo a volte deve aspettare che l'API sia corretta, invece di aggirarla per un campo comodo. Il giorno in cui uno schermo ha bisogno di qualcosa che l'API pubblica non può dargli è il giorno in cui l'API è sbagliata, e la correzione è l'API.
Il vantaggio è che tre client molto diversi non costano quasi nulla in più. Il server MCP è un client. Un tile di dash-b è un client. Il tuo script è un client. Nessuno di loro è un cittadino di seconda classe che aggira una superficie progettata per qualcun altro, perché non c'è un'altra superficie alla quale essere secondo.
Documentata, ed esercitata
OpenAPI è generato su /docs e ogni route ha un test che è l'esempio nella documentazione. Una documentazione scritta separatamente dal codice diverge entro un mese; una documentazione che fa fallire la build quando è sbagliata no.
Accesso
Il tuo account castomo, tramite il flusso authorization code con PKCE — lo stesso account che usi per dash-b e il resto della famiglia. Una pagina senza un server proprio esegue quel flusso benissimo; è per questo che il flusso è stato progettato. Per il lavoro macchina-a-macchina, una chiave API con ambito di progetto.
- 1Persone
/v1/contacts·/lists·/segments·/tags·/imports - 2Contenuto
/v1/creatives, con validazione, anteprima e render per destinazione - 3Automazione
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Trasmissione
/v1/campaigns, con audience, materializzazione, pianificazione e invio come passi distinti - 5Eventi in entrata
/v1/events— gli eventi della tua applicazione, come trigger - 6Consegna
/sender-identities·/domains·/apps·/webhooks - 7Numeri
/v1/reports/*e/track/*sull'host di tracciamento
OpenAPI su /docs/mcp sullo stesso processo
Convenzioni
La stessa forma di ogni altro servizio castomo
Il che conta più di quanto sembri. Se chiami già uno di questi, sai già come questo risponde, fallisce e impagina.
Una sola busta di errore
Ogni errore ha la stessa forma, un codice stabile e un messaggio pensato per una persona. Nessuna rotta inventa il proprio modo di essere infelice.
Paginazione a cursore
Non offset. Un elenco che cambia mentre lo scorri non salta né ripete righe in silenzio, cosa che la paginazione a offset fa costantemente e senza dirtelo.
Chiavi di idempotenza
Su ogni rotta di modifica. Riprova una richiesta di cui non sei sicuro che sia arrivata e ottieni la stessa risposta, non un secondo contatto, una seconda campagna o un secondo invio.
Ambito limitato a un progetto
Un token indirizza un tenant e un progetto, entrambi. La sicurezza a livello di riga è imposta dal database stesso, non ricordandosi di aggiungere una clausola.
Webhook in uscita
Firmati, ritentati con backoff e consegnati almeno una volta — quindi anche il tuo endpoint dovrebbe essere idempotente. Gli eventi usano lo stesso vocabolario dei report.
Cancellazione ed esportazione
Un contatto può essere esportato o cancellato tramite l'API, e una cancellazione raggiunge ogni servizio gemello che ne conservava una copia attraverso il canale interno della famiglia.
Tutto ciò che l'interfaccia può fare, una POST lo può fare.
Gli eventi sono la parte interessante
Tutto il resto in questa pagina è infrastruttura che ti aspetti. POST /v1/events è la rotta che cambia lo scopo del prodotto.
La tua applicazione sa già cose che nessuno strumento di marketing può osservare: chi ha completato l'onboarding, chi ha invitato un collega, chi ha raggiunto un limite, chi ha esportato i propri dati una domenica pomeriggio. Inviali come eventi con il tuo token, e ognuno diventa un trigger, una condizione e un segmento.
Il resto segue dal modello di contatto. Gli eventi vengono aggiunti, mai modificati; sono il log su cui pende l'intero prodotto. Una funnel che si attiva su un evento che hai definito non è un'integrazione — è lo stesso meccanismo che usa message_opened, con un nome diverso dentro.
- 1Tu lo invii
POST /v1/events— un nome, un contatto, un payload, una chiave di idempotenza. - 2Arriva a destinazioneAggiunto al log del contatto. Nessun altro deve sapere che esiste.
- 3Una funnel parteQualsiasi funnel la cui entrata nomina quell'evento, per qualsiasi contatto idoneo secondo la sua specifica di entrata.
- 4Altre funnel si diramano su di esso"Questo evento è avvenuto negli ultimi 14 giorni" è un normale predicato di segmento.
- iE termina le esecuzioniUn nodo obiettivo che nomina lo stesso evento interrompe una sequenza nel momento in cui la persona fa la cosa.
Il tuo vocabolarioIl tuo token
Confini che vale la pena conoscere prima di iniziare
ClickSomo conserva tre identificatori su di te — un tenant, un progetto e un utente, come id opachi — e nient'altro. Nessuna password, nessun profilo, nessuna carta, nessuna fattura. I limiti del piano arrivano come numeri: quanti contatti, quanti invii, quante generazioni. Il vocabolario dei pagamenti non attraversa quel confine in nessuna direzione.
I tuoi contatti sono tuoi. Tu sei il titolare del trattamento; noi siamo il responsabile. Non esiste alcun modo con cui un altro prodotto della famiglia possa leggere o scrivere la tua lista contatti, né un canale di ingestione per farlo.
Se lo stai valutando seriamente: leggi /docs prima di continuare a leggere questo sito. L'API è la descrizione onesta di ciò che il prodotto fa, e ogni affermazione in queste pagine corrisponde a una route o a un tipo di nodo che puoi trovare lì. Quando lo schema cambia, queste pagine cambiano.