L'API
Il n'existe aucun point d'accès privé. Pas même pour l'interface.
La plupart des produits ont deux API : celle qui est documentée et qui vous est proposée, et celle, plus intéressante, qu'utilisent leurs propres écrans. La seconde est toujours meilleure, et vous n'avez jamais le droit de l'approcher. Ici, il n'y en a qu'une, et l'interface en est un client comme les autres — ce qui est une contrainte pour nous, et la raison pour laquelle tout ce que vous voulez construire est possible.
Ce que cette règle coûte réellement
Cela signifie qu'un écran doit parfois attendre que l'API soit correcte, plutôt que de la contourner pour obtenir un champ pratique. Le jour où un écran a besoin de quelque chose que l'API publique ne peut pas lui donner, c'est le jour où l'API est fausse, et la correction, c'est l'API.
Le bénéfice, c'est que trois clients très différents ne coûtent presque rien de plus. Le serveur MCP est un client. Une tuile dash-b est un client. Votre propre script est un client. Aucun d'eux n'est un citoyen de seconde zone qui contourne une surface conçue pour quelqu'un d'autre, car il n'existe aucune autre surface dont être le second.
Documentée, et exercée
OpenAPI est généré sur /docs et chaque route possède un test qui constitue l'exemple de la documentation. Une documentation rédigée séparément du code se décale en un mois ; une documentation qui fait échouer la build lorsqu'elle est fausse, non.
Connexion
Votre compte castomo, via le flux de code d'autorisation avec PKCE — le même compte que vous utilisez pour dash-b et le reste de la famille. Une page sans serveur propre exécute ce flux parfaitement bien ; c'est exactement ce pour quoi il a été conçu. Pour les échanges machine à machine, une clé API limitée au projet.
- 1Personnes
/v1/contacts·/lists·/segments·/tags·/imports - 2Contenu
/v1/creatives, avec validation, aperçu et rendu par cible - 3Automatisation
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Diffusion
/v1/campaigns, avec audience, matérialisation, planification et envoi comme étapes distinctes - 5Événements entrants
/v1/events— les événements de votre propre application, comme déclencheurs - 6Diffusion
/sender-identities·/domains·/apps·/webhooks - 7Chiffres
/v1/reports/*, et/track/*sur l'hôte de suivi
OpenAPI sur /docs/mcp sur le même processus
Conventions
La même forme que pour tout autre service castomo
Ce qui compte plus qu'il n'y paraît. Si vous appelez déjà l'une de ces routes, vous savez déjà comment celle-ci répond, échoue et pagine.
Une seule enveloppe d'erreur
Chaque échec a la même forme : un code stable et un message destiné à un humain. Aucune route n'invente sa propre façon d'être mécontente.
Pagination par curseur
Pas de décalages. Une liste qui change pendant que vous la parcourez ne saute ni ne répète silencieusement de lignes, ce que la pagination par décalage fait discrètement et en permanence.
Clés d'idempotence
Sur chaque route de modification. Réessayez une requête dont vous n'êtes pas sûr qu'elle soit arrivée et obtenez la même réponse plutôt qu'un second contact, une seconde campagne ou un second envoi.
Limité à un projet
Un jeton désigne un tenant et un projet, les deux. La sécurité au niveau des lignes est appliquée dans la base de données elle-même, pas en se rappelant d'ajouter une clause.
Webhooks sortants
Signés, réessayés avec backoff et livrés au moins une fois — votre point de terminaison doit donc aussi être idempotent. Les événements utilisent le même vocabulaire que les rapports.
Effacement et export
Un contact peut être exporté ou effacé via l'API, et un effacement atteint chaque service frère qui détenait une copie, par le canal interne propre à la famille.
Tout ce que l'interface peut faire, un POST peut le faire.
Les événements sont la partie intéressante
Tout le reste sur cette page est de la plomberie à laquelle vous vous attendez. POST /v1/events est la route qui change ce pour quoi le produit existe.
Votre application sait déjà des choses qu'aucun outil marketing ne peut observer : qui a terminé l'onboarding, qui a invité un collègue, qui a atteint une limite, qui a exporté ses données un dimanche après-midi. Publiez-les comme événements avec votre propre jeton, et chacun devient un déclencheur, une condition et un segment.
Le reste découle du modèle de contact. Les événements sont ajoutés, jamais modifiés ; ils sont le journal sur lequel tout le produit repose. Un tunnel déclenché par un événement que vous avez défini n'est pas une intégration — c'est le même mécanisme que celui de message_opened, avec un autre nom dedans.
- 1Vous le publiez
POST /v1/events— un nom, un contact, une charge utile, une clé d'idempotence. - 2Il arriveAjouté au journal du contact. Rien d'autre n'a besoin de savoir qu'il existe.
- 3Un tunnel démarreTout tunnel dont l'entrée nomme cet événement, pour tout contact éligible selon sa spécification d'entrée.
- 4D'autres tunnels s'en branchent« Cet événement s'est-il produit au cours des 14 derniers jours » est un prédicat de segment ordinaire.
- iEt il termine des exécutionsUn nœud d'objectif nommant le même événement arrête une séquence dès que la personne fait la chose.
Votre vocabulaireVotre jeton
Des limites à connaître avant de construire
ClickSomo stocke trois identifiants vous concernant — un tenant, un projet et un utilisateur, sous forme d'ids opaques — et rien d'autre. Pas de mot de passe, pas de profil, pas de carte, pas de facture. Les limites du plan arrivent sous forme de nombres : combien de contacts, combien d'envois, combien de générations. Le vocabulaire du paiement ne franchit pas cette ligne dans aucun sens.
Vos contacts sont les vôtres. Vous êtes le responsable du traitement ; nous sommes le sous-traitant. Il n'existe aucune route par laquelle un autre produit de la famille peut lire ou écrire votre liste de contacts, et aucun canal d'ingestion à sa disposition.
Si vous évaluez ce produit sérieusement : lisez /docs avant de lire la suite de ce site. L'API est la description honnête de ce que fait le produit, et chaque affirmation sur ces pages correspond à une route ou à un type de nœud que vous y trouverez. Quand le schéma change, ces pages changent.