介绍
# Klaviyo
通过托管 OAuth 身份验证访问 Klaviyo API。管理用于电子邮件营销和客户互动的用户画像、列表、细分、活动、流、事件、指标、模板、目录和 Webhook。
## 快速开始
```bash # List profiles python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 基础 URL
``` https://gateway.maton.ai/klaviyo/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Klaviyo API 端点路径。网关将请求代理到 `a.klaviyo.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 标头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## API 版本控制
Klaviyo 使用基于日期的 API 版本控制。在所有请求中包含 `revision` 标头：
``` revision: 2024-10-15 ```
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Klaviyo OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=klaviyo&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'klaviyo'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "klaviyo", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 Klaviyo 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最早）的活动连接。
## API 参考
### 用户画像
管理客户数据和同意设置。
#### 获取用户画像
```bash GET /klaviyo/api/profiles ```
查询参数： - `filter` - 过滤用户画像（例如，`filter=equals(email,"[email protected]")`） - `fields[profile]` - 要包含的字段逗号分隔列表 - `page[cursor]` - 用于分页的游标 - `page[size]` - 每页结果数（最多 100） - `sort` - 排序字段（前缀 `-` 表示降序）
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles?fields[profile]=email,first_name,last_name&page[size]=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "type": "profile", "id": "01GDDKASAP8TKDDA2GRZDSVP4H", "attributes": { "email": "[email protected]", "first_name": "Alice", "last_name": "Johnson" } } ], "links": { "self": "https://a.klaviyo.com/api/profiles", "next": "https://a.klaviyo.com/api/profiles?page[cursor]=..." } } ```
#### 获取单个用户画像
```bash GET /klaviyo/api/profiles/{profile_id} ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 创建用户画像
```bash POST /klaviyo/api/profiles Content-Type: application/json
{ "data": { "type": "profile", "attributes": { "email": "[email protected]", "first_name": "John", "last_name": "Doe", "phone_number": "+15551234567", "properties": { "custom_field": "value" } } } } ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'profile', 'attributes': {'email': '[email protected]', 'first_name': 'John', 'last_name': 'Doe'}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 更新用户画像
```bash PATCH /klaviyo/api/profiles/{profile_id} ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'profile', 'id': '01GDDKASAP8TKDDA2GRZDSVP4H', 'attributes': {'first_name': 'Jane'}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H', data=data, method='PATCH') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 合并用户画像
```bash POST /klaviyo/api/profile-merge ```
#### 获取用户画像列表
```bash GET /klaviyo/api/profiles/{profile_id}/lists ```
#### 获取用户画像细分
```bash GET /klaviyo/api/profiles/{profile_id}/segments ```
### 列表
将订阅者组织到静态列表中。
#### 获取列表
```bash GET /klaviyo/api/lists ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/lists?fields[list]=name,created,updated') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "type": "list", "id": "Y6nRLr", "attributes": { "name": "Newsletter Subscribers", "created": "2024-01-15T10:30:00Z", "updated": "2024-03-01T14:22:00Z" } } ] } ```
#### 获取单个列表
```bash GET /klaviyo/api/lists/{list_id} ```
#### 创建列表
```bash POST /klaviyo/api/lists ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'list', 'attributes': {'name': 'VIP Customers'}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/lists', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 更新列表
```bash PATCH /klaviyo/api/lists/{list_id} ```
#### 删除列表
```bash DELETE /klaviyo/api/lists/{list_id} ```
#### 向列表添加用户画像
```bash POST /klaviyo/api/lists/{list_id}/relationships/profiles ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': [{'type': 'profile', 'id': '01GDDKASAP8TKDDA2GRZDSVP4H'}]}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/lists/Y6nRLr/relationships/profiles', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 从列表中移除用户画像
```bash DELETE /klaviyo/api/lists/{list_id}/relationships/profiles ```
#### 获取列表用户画像
```bash GET /klaviyo/api/lists/{list_id}/profiles ```
### 细分
根据条件创建动态受众。
#### 获取细分
```bash GET /klaviyo/api/segments ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/segments?fields[segment]=name,created,updated') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 获取单个细分
```bash GET /klaviyo/api/segments/{segment_id} ```
#### 创建细分
```bash POST /klaviyo/api/segments ```
#### 更新细分
```bash PATCH /klaviyo/api/segments/{segment_id} ```
#### 删除细分
```bash DELETE /klaviyo/api/segments/{segment_id} ```
#### 获取细分用户画像
```bash GET /klaviyo/api/segments/{segment_id}/profiles ```
### 活动
设计和发送电子邮件活动。
#### 获取活动
```bash GET /klaviyo/api/campaigns ```
查询参数： - `filter` - 过滤活动（例如，`filter=equals(messages.channel,'email')`） - `fields[campaign]` - 要包含的字段 - `sort` - 按字段排序
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/campaigns?filter=equals(messages.channel,"email")') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "type": "campaign", "id": "01GDDKASAP8TKDDA2GRZDSVP4I", "attributes": { "name": "Spring Sale 2024", "status": "Draft", "audiences": { "included": ["Y6nRLr"], "excluded": [] }, "send_options": { "use_smart_sending": true } } } ] } ```
#### 获取单个活动
```bash GET /klaviyo/api/campaigns/{campaign_id} ```
#### 创建活动
```bash POST /klaviyo/api/campaigns ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'campaign', 'attributes': {'name': 'Summer Newsletter', 'audiences': {'included': ['Y6nRLr']}, 'campaign-messages': {'data': [{'type': 'campaign-message', 'attributes': {'channel': 'email'}}]}}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/campaigns', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 更新活动
```bash PATCH /klaviyo/api/campaigns/{campaign_id} ```
#### 删除活动
```bash DELETE /klaviyo/api/campaigns/{campaign_id} ```
#### 发送活动
```bash POST /klaviyo/api/campaign-send-jobs ```
#### 获取收件人估算
```bash POST /klaviyo/api/campaign-recipient-estimations ```
### 流
构建自动化客户旅程。
#### 获取流
```bash GET /klaviyo/api/flows ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/flows?fields[flow]=name,status,created,updated') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "type": "flow", "id": "VJvBNr", "attributes": { "name": "Welcome Series", "status": "live", "created": "2024-01-10T08:00:00Z", "updated": "2024-02-15T12:30:00Z" } } ] } ```
#### 获取单个流
```bash GET /klaviyo/api/flows/{flow_id} ```
#### 创建流
```bash POST /klaviyo/api/flows ```
> **注意：** 通过 API 创建流可能会受到限制。流通常通过 Klaviyo UI 创建，然后通过 API 进行管理。对现有流使用 GET、PATCH 和 DELETE 操作。
#### 更新流状态
```bash PATCH /klaviyo/api/flows/{flow_id} ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'flow', 'id': 'VJvBNr', 'attributes': {'status': 'draft'}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/flows/VJvBNr', data=data, method='PATCH') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 删除流
```bash DELETE /klaviyo/api/flows/{flow_id} ```
#### 获取流操作
```bash GET /klaviyo/api/flows/{flow_id}/flow-actions ```
#### 获取流消息
```bash GET /klaviyo/api/flows/{flow_id}/flow-messages ```
### 事件
跟踪客户互动和行为。
#### 获取事件
```bash GET /klaviyo/api/events ```
查询参数： - `filter` - 过滤事件（例如，`filter=equals(metric_id,"ABC123")`） - `fields[event]` - 要包含的字段 - `sort` - 按字段排序（默认：`-datetime`）
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/events?filter=greater-than(datetime,2024-01-01T00:00:00Z)&page[size]=50') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "type": "event", "id": "4vRpBT", "attributes": { "metric_id": "TxVpCr", "profile_id": "01GDDKASAP8TKDDA2GRZDSVP4H", "datetime": "2024-03-15T14:30:00Z", "event_properties": { "value": 99.99, "product_name": "Running Shoes" } } } ] } ```
#### 获取单个事件
```bash GET /klaviyo/api/events/{event_id} ```
#### 创建事件
```bash POST /klaviyo/api/events ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'event', 'attributes': {'profile': {'data': {'type': 'profile', 'attributes': {'email': '[email protected]'}}}, 'metric': {'data': {'type': 'metric', 'attributes': {'name': 'Viewed Product'}}}, 'properties': {'product_id': 'SKU123', 'product_name': 'Blue T-Shirt', 'price': 29.99}}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/events', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 批量创建事件
```bash POST /klaviyo/api/event-bulk-create-jobs ```
### 指标
访问性能数据和分析。
#### 获取指标
```bash GET /klaviyo/api/metrics ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/metrics') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "type": "metric", "id": "TxVpCr", "attributes": { "name": "Placed Order", "created": "2024-01-01T00:00:00Z", "updated": "2024-03-01T00:00:00Z", "integration": { "object": "integration", "id": "shopify", "name": "Shopify" } } } ] } ```
#### 获取单个指标
```bash GET /klaviyo/api/metrics/{metric_id} ```
#### 查询指标聚合
```bash POST /klaviyo/api/metric-aggregates ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'metric-aggregate', 'attributes': {'metric_id': 'TxVpCr', 'measurements': ['count', 'sum_value'], 'interval': 'day', 'filter': ['greater-or-equal(datetime,2024-01-01)', 'less-than(datetime,2024-04-01)']}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/metric-aggregates', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 模板
管理电子邮件模板。
#### 获取模板
```bash GET /klaviyo/api/templates ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/templates?fields[template]=name,created,updated') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 获取单个模板
```bash GET /klaviyo/api/templates/{template_id} ```
#### 创建模板
```bash POST /klaviyo/api/templates ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'template', 'attributes': {'name': 'Welcome Email', 'editor_type': 'CODE', 'html': '<html><body><h1>Welcome!</h1></body></html>'}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/templates', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 更新模板
```bash PATCH /klaviyo/api/templates/{template_id} ```
#### 删除模板
```bash DELETE /klaviyo/api/templates/{template_id} ```
#### 渲染模板
```bash POST /klaviyo/api/template-render ```
#### 克隆模板
```bash POST /klaviyo/api/template-clone ```
### 目录
管理产品目录。
#### 获取目录项目
```bash GET /klaviyo/api/catalog-items ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/catalog-items?fields[catalog-item]=title,price,url') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "type": "catalog-item", "id": "$custom:::$default:::PROD-001", "attributes": { "title": "Blue Running Shoes", "price": 129.99, "url": "https://store.example.com/products/blue-running-shoes" } } ] } ```
#### 获取单个目录项目
```bash GET /klaviyo/api/catalog-items/{catalog_item_id} ```
#### 创建目录项目
```bash POST /klaviyo/api/catalog-items ```
#### 更新目录项目
```bash PATCH /klaviyo/api/catalog-items/{catalog_item_id} ```
#### 删除目录项目
```bash DELETE /klaviyo/api/catalog-items/{catalog_item_id} ```
#### 获取目录变体
```bash GET /klaviyo/api/catalog-variants ```
#### 获取目录类别
```bash GET /klaviyo/api/catalog-categories ```
### 标签
使用标签组织资源。
#### 获取标签
```bash GET /klaviyo/api/tags ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/tags') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 创建标签
```bash POST /klaviyo/api/tags ```
#### 更新标签
```bash PATCH /klaviyo/api/tags/{tag_id} ```
#### 删除标签
```bash DELETE /klaviyo/api/tags/{tag_id} ```
#### 标记活动
```bash POST /klaviyo/api/tag-campaign-relationships ```
#### 标记流
```bash POST /klaviyo/api/tag-flow-relationships ```
### 优惠券
管理折扣代码。
#### 获取优惠券
```bash GET /klaviyo/api/coupons ```
#### 创建优惠券
```bash POST /klaviyo/api/coupons ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'coupon', 'attributes': {'external_id': 'SUMMER_SALE_2024', 'description': 'Summer sale discount coupon'}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/coupons', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
> **注意：** `external_id` 必须匹配正则表达式 `^[0-9_A-z]+$`（仅限字母数字和下划线，不能包含连字符）。
#### 获取优惠券代码
```bash GET /klaviyo/api/coupon-codes ```
> **注意：** 此端点需要过滤参数。您必须按优惠券 ID 或用户画像 ID 进行过滤。
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/coupon-codes?filter=equals(coupon.id,"SUMMER_SALE_2024")') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 创建优惠券代码
```bash POST /klaviyo/api/coupon-codes ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'coupon-code', 'attributes': {'unique_code': 'SAVE20NOW', 'expires_at': '2025-12-31T23:59:59Z'}, 'relationships': {'coupon': {'data': {'type': 'coupon', 'id': 'SUMMER_SALE_2024'}}}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/coupon-codes', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Webhook
配置事件通知。
#### 获取 Webhook
```bash GET /klaviyo/api/webhooks ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/webhooks') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 创建 Webhook
```bash POST /klaviyo/api/webhooks ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'webhook', 'attributes': {'name': 'Order Placed Webhook', 'endpoint_url': 'https://example.com/webhooks/klaviyo', 'enabled': True}, 'relationships': {'webhook-topics': {'data': [{'type': 'webhook-topic', 'id': 'campaign:sent'}]}}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/webhooks', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 获取单个 Webhook
```bash GET /klaviyo/api/webhooks/{webhook_id} ```
#### 更新 Webhook
```bash PATCH /klaviyo/api/webhooks/{webhook_id} ```
#### 删除 Webhook
```bash DELETE /klaviyo/api/webhooks/{webhook_id} ```
#### 获取 Webhook 主题
```bash GET /klaviyo/api/webhook-topics ```
### 账户
检索账户信息。
#### 获取账户
```bash GET /klaviyo/api/accounts ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/accounts') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 过滤
Klaviyo 使用 JSON:API 过滤语法。常用运算符：
| 运算符 | 示例 | |----------|---------| | `equals` | `filter=equals(email,"[email protected]")` | | `contains` | `filter=contains(name,"newsletter")` | | `greater-than` | `filter=greater-than(datetime,2024-01-01T00:00:00Z)` | | `less-than` | `filter=less-than(created,2024-03-01)` | | `greater-or-equal` | `filter=greater-or-equal(updated,2024-01-01)` | | `any` | `filter=any(status,["draft","scheduled"])` |
使用 `and` 组合过滤器： ``` filter=and(equals(status,"active"),greater-than(created,2024-01-01)) ```
## 分页
Klaviyo 使用基于游标的分页：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles?page[size]=50&page[cursor]=CURSOR_TOKEN') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
响应包含分页链接：
```json { "data": [...], "links": { "self": "https://a.klaviyo.com/api/profiles", "next": "https://a.klaviyo.com/api/profiles?page[cursor]=WzE2..." } } ```
## 稀疏字段集
仅请求特定字段以减小响应大小：
```bash # Request only email and first_name for profiles ?fields[profile]=email,first_name
# Request specific fields for included relationships ?include=lists&fields[list]=name,created ```
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/klaviyo/api/profiles?fields[profile]=email,first_name', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}`, 'revision': '2024-10-15' } } ); const data = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/klaviyo/api/profiles', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'revision': '2024-10-15' }, params={'fields[profile]': 'email,first_name'} ) data = response.json() ```
## 注意事项
- 所有请求均使用 JSON:API 规范 - 时间戳采用 ISO 8601 RFC 3339 格式（例如，`2024-01-16T23:20:50.52Z`） - 资源 ID 是字符串（通常为 base64 编码） - 使用稀疏字段集以优化响应大小 - 包含 `revision` 标头以进行 API 版本控制（推荐：`2024-10-15`） - 某些 POST 端点在成功创建时返回 `200` 而不是 `201` - 优惠券的 `external_id` 必须匹配正则表达式 `^[0-9_A-z]+$`（不能包含连字符） - 优惠券代码端点需要过滤器（例如，`filter=equals(coupon.id,"...")`） - 通过 API 创建流可能会受到限制；通常在 Klaviyo UI 中创建流 - 重要：使用 curl 命令时，如果 URL 包含方括号（`fields[]`、`page[]`），请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，像 `$MATON_API_KEY` 这样的环境变量可能无法正确展开。通过管道传输时，您可能会收到“Invalid API key”错误。
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 请求错误或缺少 Klaviyo 连接 | | 401 | Maton API 密钥无效或缺失 | | 403 | 禁止访问 - 权限不足 | | 404 | 资源未找到 | | 429 | 请求速率受限（固定窗口算法） | | 4xx/5xx | 来自 Klaviyo API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 故障排除：无效的应用名称
1. 确保您的 URL 路径以 `klaviyo` 开头。例如：
- 正确：`https://gateway.maton.ai/klaviyo/api/profiles` - 错误：`https://gateway.maton.ai/api/profiles`
## 资源
- [Klaviyo API Documentation](https://developers.klaviyo.com) - [API Reference](https://developers.klaviyo.com/en/reference/api_overview) - [Klaviyo Developer Portal](https://developers.klaviyo.com/en) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])