API
没有私有端点。连界面用的也没有。
大多数产品有两套 API：一套是提供给你、有文档的那套，另一套是他们自己的界面在用的那套“有意思的”。第二套总是更好，而你永远不被允许靠近它。这里只有一套，界面和其他任何东西一样只是它的一个客户端——这对我们是一种约束，也是你想构建的一切都能实现的原因。
这条规则真正的代价
它意味着界面偶尔必须等 API 做对，而不是绕过它去取一个方便的字段。当某个界面需要的东西公开 API 给不了的那一天，就是 API 错了的那一天，而修复的对象是 API。
回报是：三个截然不同的客户端几乎不需要额外成本。MCP 服务器是一个客户端。dash-b 的一个磁贴是一个客户端。你自己的脚本也是一个客户端。它们都不是在围绕一个为别人设计的接口打转的二等公民，因为根本不存在另一个可供屈居其下的接口。
有文档，且经过实测
OpenAPI 在 /docs 自动生成，每条路由都有一个测试，而这个测试就是文档里的示例。与代码分开编写的文档一个月内就会漂移；写错了就会让构建失败的文档不会。
登录
你的 castomo 账户，走带 PKCE 的授权码流程——和你在 dash-b 以及家族其他产品里用的是同一个账户。一个没有自己服务器的页面完全可以跑通这个流程；这个流程本来就是为此设计的。对于机器对机器的场景，则使用项目级 API 密钥。
- 1人员
/v1/contacts·/lists·/segments·/tags·/imports - 2內容
/v1/creatives，含针对每个投放目标的验证、预览和渲染 - 3自动化
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4广播
/v1/campaigns，受众、实体化、排期和发送是各自独立的步骤 - 5事件接入
/v1/events—— 你自己应用的事件，作为触发器 - 6投递
/sender-identities·/domains·/apps·/webhooks - 7数据
/v1/reports/*，以及跟踪主机上的/track/*
OpenAPI 文档在 /docs/mcp，运行在同一进程上
约定
与其他所有 castomo 服务相同的形态
这一点比听起来更重要。如果你已经调用过其中某个服务，你就已经知道这个服务如何响应、如何报错、如何分页。
统一的错误封装
每种失败都有相同的结构：一个稳定的错误码和一条面向人的消息。没有任何路由自创一套表达不满的方式。
游标分页
不用偏移量。一个在你遍历期间还在变化的列表不会悄悄跳过或重复行——而偏移量分页会安静且持续地这么做。
幂等键
在每个会修改数据的路由上。重试一个你不确定是否到达的请求，会得到相同的答案，而不是第二个联系人、第二场营销活动或第二次发送。
限定于项目
一个令牌同时指向一个租户和一个项目。行级安全由数据库本身强制执行，而不是靠记得加一个条件。
Webhooks 输出
已签名、带退避重试、至少送达一次——所以你的端点也应当是幂等的。这些事件与报表使用的是同一套词汇。
删除与导出
联系人可以通过 API 导出或删除，删除操作会通过产品家族自己的内部通道，触达每一个持有副本的兄弟服务。
界面能做的一切，一个 POST 都能做。
事件才是有意思的部分
这个页面上的其他一切都是你意料之中的管道。POST /v1/events 才是改变产品用途的那条路由。
你的应用已经知道营销工具无法观察到的事情：谁完成了新手引导，谁邀请了同事，谁撞上了限额，谁在周日下午导出了自己的数据。用你自己的令牌把这些作为事件发布，每一个都会变成触发器、条件和细分。
其余一切都源于联系人模型。事件只追加、永不编辑；它们是整个产品赖以挂靠的日志。一个由你定义的事件触发的漏斗并不是什么集成——它和 message_opened 用的是同一套机制，只是名字不同。
- 1你发布它
POST /v1/events——一个名称、一个联系人、一个载荷、一个幂等键。 - 2它落地追加到联系人的日志中。其他任何东西都不需要知道它的存在。
- 3一个漏斗启动任何入口指定了该事件的漏斗，都会对其入口条件下的任何联系人启动。
- 4其他漏斗据此分支“该事件在过去 14 天内是否发生过”是一个普通的细分谓词。
- i而且它能结束流程一个指定了同一事件的目标节点，会在用户完成该动作的那一刻停止一个序列。
你的词汇你的令牌
动手之前值得了解的边界
ClickSomo 只存储关于你的三个标识符——一个租户、一个项目和一个用户，都是不透明的 id——仅此而已。没有密码，没有资料，没有银行卡，没有发票。套餐限额以数字形式出现：多少联系人、多少发送量、多少生成次数。支付相关的词汇不会越过这条线，双向都不行。
你的联系人属于你。你是数据控制者；我们是处理者。不存在任何路由能让家族中的另一个产品读写你的联系人列表，也没有供它使用的摄取通道。
如果你在认真评估：在继续阅读本网站的更多内容之前，先读 /docs。API 是对产品实际功能的诚实描述，这些页面上的每一项声明都对应着你在那里能找到的一条路由或一种节点类型。模式变了，这些页面也会变。