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 服务相同的形态
这一点比听起来更重要。如果你已经在调用其中某个服务，你就已经知道这个服务如何响应、如何报错、如何分页。
统一的错误封装
每种失败都有相同的结构：一个稳定的错误码和一条面向人的消息。没有任何路由自创一套表达不满的方式。
游标分页
不是偏移量。一个在你遍历期间还在变化的列表不会悄悄跳过或重复行——而偏移量分页会一直悄悄地这么做。
幂等键
在每个会修改数据的路由上。重试一个你不确定是否成功的请求，会得到同样的结果，而不是多出一个联系人、一个活动或一次发送。
限定于项目
一个令牌同时指向一个租户和一个项目。行级安全由数据库本身强制执行，而不是靠记得加一个条件。
Webhook 输出
带签名、按退避策略重试、至少送达一次——所以你的端点也应当是幂等的。事件所用的词汇与报告相同。
删除与导出
联系人可以通过 API 导出或删除，删除操作会通过家族内部的专用通道传达到每一个持有副本的兄弟服务。
界面上能做的一切，一个 POST 都能做。
事件才是有意思的部分
这个页面上的其他内容都是你意料之中的管道。 POST /v1/events 才是改变产品定位的那条路由。
你的应用已经知道一些任何营销工具都观察不到的事情：谁完成了新手引导，谁邀请了同事，谁触发了限制，谁在周日下午导出了自己的数据。用你自己的令牌把这些作为事件发布，每一个都会变成触发器、条件和细分。
其余的一切都源于联系人模型。事件只追加，从不编辑；它们是整个产品赖以运转的日志。一个由你定义的事件触发的漏斗不是什么集成——它和 message_opened 用的是同一套机制，只是名字不同。
- 1你发布它
POST /v1/events—— 一个名称、一个联系人、一个载荷、一个幂等键。 - 2它落地追加到联系人的日志中。其他任何东西都不需要知道它的存在。
- 3漏斗启动任何入口指定了该事件的漏斗，都会对该入口规则下符合条件的联系人启动。
- 4其他漏斗基于它分支“该事件在过去 14 天内是否发生过”是一个普通的细分谓词。
- i而且它会结束流程一个指定了同一事件的目标节点，会在用户完成该动作的那一刻停止一个序列。
你的词汇表你的令牌
在动手之前值得了解的边界
ClickSomo 只存储关于你的三个标识符——一个租户、一个项目和一个用户，都是不透明的 id——仅此而已。没有密码，没有个人资料，没有银行卡，没有发票。套餐限制以数字形式到达：多少联系人、多少发送量、多少生成次数。支付相关的词汇不会越过这条线，双向都不会。
你的联系人属于你。你是数据控制者；我们是处理者。不存在任何途径让家族中的另一个产品读取或写入你的联系人列表，也没有供它使用的接入通道。
如果你在认真评估这个产品：在继续阅读本网站的任何内容之前，先读 /docs。API 才是对产品功能的诚实描述，这些页面上的每一个说法都对应着你在那里能找到的一条路由或一种节点类型。当模式变更时，这些页面也会随之变更。