用途
Klaviyo 技能用于通过 API 对 Klaviyo 电商营销自动化平台进行程序化操作，涵盖客户档案、列表、事件、活动与指标等核心对象。当用户提及 "Klaviyo"、"email marketing" 等场景时可使用。
认证与环境变量
所有请求需要三个请求头：
- Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN
- revision: 2026-04-15
- accept: application/vnd.api+json
写请求还需额外包含 content-type: application/vnd.api+json。revision 头用于固定 API 版本，仅在需要新功能时才升级到更新的日期，旧版本仍受支持。
环境变量 KLAVIYO_TOKEN 为 Klaviyo 私有 API 密钥，格式为 pk_...，共 37 个字符。
主要能力
基础 URL 为 https://a.klaviyo.com，所有请求体遵循 JSON:API 规范，即始终包裹在 {"data": {"type": "...", "attributes": {...}}} 中。
- 账户：获取账户信息用于连通性检查。
- 档案（Profiles）：分页获取档案，支持按 email、phone_number、created 等条件过滤；按 ID 获取单个档案；创建档案（返回 201 及新档案 ID，若邮箱已存在则返回 409）；更新档案（PATCH）。
- 事件（Events）：创建事件以触发流程，指标在首次使用时自动创建，返回 202 表示已入队；若档案不存在，Klaviyo 会根据提供的标识符创建。
- 列表（Lists）：获取列表、创建列表、将已知档案静默添加到列表（不改变订阅同意状态）。
- 订阅（Subscriptions）：通过 profile-subscription-bulk-create-jobs 端点批量订阅档案并授予营销同意，单次任务最多 1000 个档案，需要 lists:write、profiles:write、subscriptions:write 权限范围。
- 指标（Metrics）：获取指标列表；查询指标聚合，支持 count、sum_value 等测量值，可指定 interval 与时间过滤条件。
- 细分（Segments）：获取细分列表。
- 活动（Campaigns）：活动按渠道标记，查询时必须传入 messages.channel 过滤条件，例如 equals(messages.channel,'email') 或 equals(messages.channel,'sms')。
使用方式
请求通过 curl 发送，示例：
curl -s "https://a.klaviyo.com/api/accounts" --header "Authorization: Klaviyo-API-Key $KLAVIYO_TOKEN" --header "revision: 2026-04-15" --header "accept: application/vnd.api+json"
写请求通常先将请求体写入 /tmp/klaviyo_request.json，再通过 -d @/tmp/klaviyo_request.json 发送。
若请求失败，可运行 zero doctor check-connector --env-name KLAVIYO_TOKEN 或 zero doctor check-connector --url https://a.klaviyo.com/api/accounts --method GET 进行排查。
响应码
- 200：成功（GET / PATCH）
- 201：已创建（POST 档案 / 列表）
- 202：已接受（事件、批量任务，异步处理）
- 400：无效的 JSON:API 载荷
- 401：缺少或无效的 API 密钥
- 403：API 密钥缺少所需权限范围
- 404：资源未找到
- 409：档案重复（邮箱 / 电话已存在，返回的 ID 位于 errors[].meta.duplicate_profile_id）
- 429：触发速率限制，需遵循 Retry-After 头
适用场景
适用于电商营销自动化的程序化操作，例如同步客户档案、服务端追踪下单等事件以触发流程、管理列表与订阅同意、查询营销指标与活动数据等。
限制与准则
- 必须始终发送 revision 头，否则返回 400；除非需要新功能，否则使用 2026-04-15。
- 所有请求体必须使用 JSON:API 包裹，遗漏外层结构会返回 400。
- 速率限制：多数端点突发为 75 请求/秒，稳定为 700 请求/分钟；处理数千个档案时应使用批量任务。
- 同意状态：更改营销订阅同意应使用 POST /api/profile-subscription-bulk-create-jobs，而非仅添加列表成员；仅将档案加入列表并不代表其同意接收营销。
- 创建档案返回 409 时，重复档案的 ID 在错误载荷中返回，应改用 PATCH /api/profiles/{id}。
- 本技能仅使用私有密钥（pk_...）；6 位公开密钥（Site ID）用于客户端追踪，此处不需要。
API 参考
- 概览：https://developers.klaviyo.com/en/reference/api_overview
- 认证：https://developers.klaviyo.com/en/docs/authenticate_
- OpenAPI 规范：https://developers.klaviyo.com/en/reference/openapi
- 变更日志 / 版本：https://developers.klaviyo.com/en/docs/api_versioning_and_deprecation_policy