The API
There is no private endpoint.Not even for the interface.
Most products have two APIs: the documented one you are offered, and the interesting one their own screens use. The second is always better, and you are never allowed near it. Here there is one, and the interface is a client of it like anything else — which is a constraint on us, and the reason everything you want to build is possible.
What that rule actually costs.
It means a screen occasionally has to wait for the API to be right, rather than reaching around it for one convenient field. The day a screen needs something the public API cannot give it is the day the API is wrong, and the fix is the API.
The payoff is that three very different clients cost almost nothing extra. The MCP server is a client. A dash-b tile is a client. Your own script is a client. None of them is a second-class citizen working around a surface designed for somebody else, because there is no other surface to be second to.
Documented, and exercised
OpenAPI is generated at /docs and every route has a test that is the example in the documentation. Documentation that is written separately from the code drifts within a month; documentation that fails the build when it is wrong does not.
Signing in
Your castomo account, over the authorization code flow with PKCE — the same account you use for dash-b and the rest of the family. A page with no server of its own runs that flow perfectly well; it is what the flow was designed for. For machine-to-machine work, a project-scoped API key.
- 1People
/v1/contacts·/lists·/segments·/tags·/imports - 2Content
/v1/creatives, with validation, preview and render per target - 3Automation
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Broadcast
/v1/campaigns, with audience, materialise, schedule and send as distinct steps - 5Events in
/v1/events— your own application's events, as triggers - 6Delivery
/sender-identities·/domains·/apps·/webhooks - 7Numbers
/v1/reports/*, and/track/*on the tracking host
OpenAPI at /docs/mcp on the same process
Conventions
The same shape as every other castomo service.
Which matters more than it sounds. If you already call one of these, you already know how this one answers, fails and paginates.
One error envelope
Every failure has the same shape, a stable code and a message meant for a person. No route invents its own way of being unhappy.
Cursor pagination
Not offsets. A list that changes while you are walking it does not silently skip or repeat rows, which offset pagination does quietly and constantly.
Idempotency keys
On every mutating route. Retry a request you are not sure landed and get the same answer rather than a second contact, a second campaign or a second send.
Scoped to a project
A token addresses one tenant and one project, both. Row-level security is enforced in the database itself, not by remembering to add a clause.
Webhooks out
Signed, retried with backoff, and delivered at least once — so your endpoint should be idempotent too. The events are the same vocabulary the reports use.
Erasure and export
A contact can be exported or erased through the API, and an erasure reaches every sibling service that held a copy through the family's own internal lane.
Everything the interface can do,
a POST can do.
Events are the interesting part.
Everything else on this page is plumbing you would expect. POST /v1/events is the route that changes what the product is for.
Your application already knows things no marketing tool can observe: who finished onboarding, who invited a colleague, who hit a limit, who exported their data on a Sunday afternoon. Post those as events with your own token, and each one becomes a trigger, a condition and a segment.
The rest follows from the contact model. Events are appended, never edited; they are the log the whole product hangs off. A funnel triggering on an event you defined is not an integration — it is the same mechanism message_opened uses, with a different name in it.
- 1You post it
POST /v1/events— a name, a contact, a payload, an idempotency key. - 2It landsAppended to the contact's log. Nothing else needs to know it exists.
- 3A funnel startsAny funnel whose entry names that event, for any contact eligible under its entry spec.
- 4Other funnels branch on it"Has this event happened in the last 14 days" is an ordinary segment predicate.
- iAnd it ends runsA goal node naming the same event stops a sequence the moment the person does the thing.
Your vocabularyYour token
Boundaries worth knowing before you build.
ClickSomo stores three identifiers about you — a tenant, a project and a user, as opaque ids — and nothing else. No password, no profile, no card, no invoice. Plan limits arrive as numbers: how many contacts, how many sends, how many generations. Payment vocabulary does not cross that line in either direction.
Your contacts are yours. You are the data controller; we are the processor. There is no route by which another product in the family can read or write your contact list, and no ingest lane for one to use.
If you are evaluating this seriously: read /docs before you read any more of this website. The API is the honest description of what the product does, and every claim on these pages maps to a route or a node kind you can find there. When the schema changes, these pages change.
Tell us what you send today,
and to how many.
We will show you what it looks like here — usually with the funnel drawn, because that is faster than a paragraph about it.
Open ClickSomo Talk to a person