网淘吧来吧，欢迎您！

返回首页 微信
微信
手机版
手机版
  • 当前位置：
  • 网淘吧
  • >
  • openclaw小龙虾
    • Klaviyo

    Klaviyo

    2026-03-25 新闻来源：网淘吧 围观:68
    电脑广告
    手机广告

    Klaviyo

    通过托管的OAuth认证访问Klaviyo API。管理用于电子邮件营销和客户互动的用户档案、列表、细分、营销活动、流程、事件、指标、模板、目录和Webhook。

    快速开始

    # 列出用户档案
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', '2026-01-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：

    export MATON_API_KEY="YOUR_API_KEY"

    获取您的API密钥

    1. 登录或创建账户，访问maton.ai
    2. 前往maton.ai/settings
    3. 复制您的API密钥

    API版本控制

    Klaviyo采用基于日期的API版本控制。请在所有请求中包含revision请求头：

    revision: 2026-01-15

    连接管理

    管理您的Klaviyo OAuth连接，请访问https://ctrl.maton.ai。

    列出连接

    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

    创建连接

    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

    获取连接

    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

    响应：

    {
  "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 授权。

    删除连接

    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请求头指定要使用哪一个：

    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', '2026-01-15')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    如果省略，网关将使用默认（最早创建的）活跃连接。

    API 参考

    用户档案

    管理客户数据和同意。

    获取用户档案

    GET /klaviyo/api/profiles

    查询参数：

    • filter- 筛选用户资料（例如：filter=equals(email,"test@example.com")）
    • fields[profile]- 要包含的字段列表，以逗号分隔
    • page[cursor]- 用于分页的光标
    • page[size]- 每页结果数量（最多100条）
    • sort- 排序字段（前缀加-表示降序）

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    响应：

    {
  "data": [
    {
      "type": "profile",
      "id": "01GDDKASAP8TKDDA2GRZDSVP4H",
      "attributes": {
        "email": "alice@example.com",
        "first_name": "Alice",
        "last_name": "Johnson"
      }
    }
  ],
  "links": {
    "self": "https://a.klaviyo.com/api/profiles",
    "next": "https://a.klaviyo.com/api/profiles?page[cursor]=..."
  }
}

    获取用户资料

    GET /klaviyo/api/profiles/{profile_id}

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    创建用户资料

    POST /klaviyo/api/profiles
Content-Type: application/json

{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "newuser@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone_number": "+15551234567",
      "properties": {
        "custom_field": "value"
      }
    }
  }
}

    示例：

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'type': 'profile', 'attributes': {'email': 'newuser@example.com', '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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    更新用户资料

    PATCH /klaviyo/api/profiles/{profile_id}

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    合并用户资料

    POST /klaviyo/api/profile-merge

    获取用户资料列表

    GET /klaviyo/api/profiles/{profile_id}/lists

    获取用户资料细分

    GET /klaviyo/api/profiles/{profile_id}/segments

    列表

    将订阅者组织到静态列表中。

    获取列表

    GET /klaviyo/api/lists

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    响应：

    {
  "data": [
    {
      "type": "list",
      "id": "Y6nRLr",
      "attributes": {
        "name": "新闻稿订阅者",
        "created": "2024-01-15T10:30:00Z",
        "updated": "2024-03-01T14:22:00Z"
      }
    }
  ]
}

    获取单个列表

    GET /klaviyo/api/lists/{list_id}

    创建列表

    POST /klaviyo/api/lists

    示例：

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'type': 'list', 'attributes': {'name': 'VIP客户'}}}).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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    更新列表

    PATCH /klaviyo/api/lists/{list_id}

    删除列表

    DELETE /klaviyo/api/lists/{list_id}

    向列表添加用户档案

    POST /klaviyo/api/lists/{list_id}/relationships/profiles

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    从列表中移除用户档案

    DELETE /klaviyo/api/lists/{list_id}/relationships/profiles

    获取列表用户档案

    GET /klaviyo/api/lists/{list_id}/profiles

    细分

    基于条件创建动态受众。

    获取细分

    GET /klaviyo/api/segments

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    获取单个细分

    GET /klaviyo/api/segments/{segment_id}

    创建细分

    POST /klaviyo/api/segments

    更新细分

    PATCH /klaviyo/api/segments/{segment_id}

    删除细分

    DELETE /klaviyo/api/segments/{segment_id}

    获取细分用户档案

    GET /klaviyo/api/segments/{segment_id}/profiles

    营销活动

    设计和发送电子邮件营销活动。

    获取营销活动

    GET /klaviyo/api/campaigns

    注意：必须使用渠道过滤器。请使用filter=equals(messages.channel,"email")或filter=equals(messages.channel,"sms")。

    查询参数：

    • filter-必需。按渠道过滤（例如，filter=equals(messages.channel,"email")）
    • fields[campaign]- 包含的字段
    • 排序- 按字段排序

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    响应：

    {
  "data": [
    {
      "type": "campaign",
      "id": "01GDDKASAP8TKDDA2GRZDSVP4I",
      "attributes": {
        "name": "春季促销 2024",
        "status": "草稿",
        "audiences": {
          "included": ["Y6nRLr"],
          "excluded": []
        },
        "send_options": {
          "use_smart_sending": true
        }
      }
    }
  ]
}

    获取一个营销活动

    GET /klaviyo/api/campaigns/{campaign_id}

    创建一个营销活动

    POST /klaviyo/api/campaigns

    示例：

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'type': 'campaign', 'attributes': {'name': '夏季通讯', '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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    更新一个营销活动

    PATCH /klaviyo/api/campaigns/{campaign_id}

    删除一个营销活动

    DELETE /klaviyo/api/campaigns/{campaign_id}

    发送一个营销活动

    POST /klaviyo/api/campaign-send-jobs

    获取收件人估算

    POST /klaviyo/api/campaign-recipient-estimations

    流程

    构建自动化客户旅程。

    获取流程列表

    GET /klaviyo/api/flows

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    响应：

    {
  "data": [
    {
      "type": "flow",
      "id": "VJvBNr",
      "attributes": {
        "name": "欢迎系列",
        "status": "已上线",
        "created": "2024-01-10T08:00:00Z",
        "updated": "2024-02-15T12:30:00Z"
      }
    }
  ]
}

    获取单个流程

    GET /klaviyo/api/flows/{flow_id}

    创建流程

    POST /klaviyo/api/flows

    注意：通过API创建流程可能受限。流程通常通过Klaviyo用户界面创建，然后通过API进行管理。请使用GET、PATCH和DELETE操作来处理现有流程。

    更新流程状态

    PATCH /klaviyo/api/flows/{flow_id}

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    删除一个流程

    DELETE /klaviyo/api/flows/{flow_id}

    获取流程操作

    GET /klaviyo/api/flows/{flow_id}/flow-actions

    获取流程消息

    GET /klaviyo/api/flows/{flow_id}/flow-messages

    事件

    跟踪客户互动和行为。

    获取事件

    GET /klaviyo/api/events

    查询参数：

    • filter- 过滤事件（例如，filter=equals(metric_id,"ABC123")）
    • fields[event]- 包含的字段
    • 排序- 按字段排序（默认：-日期时间）

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    响应：

    {
  "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": "跑鞋"
        }
      }
    }
  ]
}

    获取事件

    GET /klaviyo/api/events/{事件ID}

    创建事件

    POST /klaviyo/api/events

    示例：

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'type': 'event', 'attributes': {'profile': {'data': {'type': 'profile', 'attributes': {'email': 'customer@example.com'}}}, 'metric': {'data': {'type': 'metric', 'attributes': {'name': '浏览产品'}}}, 'properties': {'product_id': 'SKU123', 'product_name': '蓝色T恤', '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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    批量创建事件

    POST /klaviyo/api/event-bulk-create-jobs

    指标

    访问性能数据和分析。

    获取指标

    GET /klaviyo/api/metrics

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    响应：

    {
  "data": [
    {
      "type": "metric",
      "id": "TxVpCr",
      "attributes": {
        "name": "下单",
        "created": "2024-01-01T00:00:00Z",
        "updated": "2024-03-01T00:00:00Z",
        "integration": {
          "object": "integration",
          "id": "shopify",
          "name": "Shopify"
        }
      }
    }
  ]
}

    获取单个指标

    GET /klaviyo/api/metrics/{metric_id}

    查询指标聚合数据

    POST /klaviyo/api/metric-aggregates

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    模板

    管理电子邮件模板。

    获取模板

    GET /klaviyo/api/templates

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    获取模板

    GET /klaviyo/api/templates/{template_id}

    创建模板

    POST /klaviyo/api/templates

    示例：

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'type': 'template', 'attributes': {'name': '欢迎邮件', 'editor_type': 'CODE', 'html': '<html><body><h1>欢迎！</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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    更新模板

    PATCH /klaviyo/api/templates/{template_id}

    删除模板

    DELETE /klaviyo/api/templates/{template_id}

    渲染模板

    POST /klaviyo/api/template-render

    克隆模板

    POST /klaviyo/api/template-clone

    产品目录

    管理产品目录。

    获取目录项

    GET /klaviyo/api/catalog-items

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    响应：

    {
  "data": [
    {
      "type": "catalog-item",
      "id": "$custom:::$default:::PROD-001",
      "attributes": {
        "title": "蓝色跑鞋",
        "price": 129.99,
        "url": "https://store.example.com/products/blue-running-shoes"
      }
    }
  ]
}

    获取目录项

    GET /klaviyo/api/catalog-items/{catalog_item_id}

    创建目录项

    POST /klaviyo/api/catalog-items

    更新目录项

    PATCH /klaviyo/api/catalog-items/{catalog_item_id}

    删除目录项

    DELETE /klaviyo/api/catalog-items/{catalog_item_id}

    获取目录变体

    GET /klaviyo/api/catalog-variants

    获取目录类别

    GET /klaviyo/api/catalog-categories

    标签

    使用标签组织资源。

    获取标签

    GET /klaviyo/api/tags

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    创建标签

    POST /klaviyo/api/tags

    更新标签

    PATCH /klaviyo/api/tags/{tag_id}

    删除标签

    DELETE /klaviyo/api/tags/{tag_id}

    为营销活动添加标签

    POST /klaviyo/api/tag-campaign-relationships

    为流程添加标签

    POST /klaviyo/api/tag-flow-relationships

    获取标签组

    GET /klaviyo/api/tag-groups

    示例：

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/tag-groups')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('revision', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    创建标签组

    POST /klaviyo/api/tag-groups

    更新标签组

    PATCH /klaviyo/api/tag-groups/{tag_group_id}

    删除标签组

    DELETE /klaviyo/api/tag-groups/{tag_group_id}

    优惠券

    管理折扣码。

    获取优惠券

    GET /klaviyo/api/coupons

    创建优惠券

    POST /klaviyo/api/coupons

    示例：

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'type': 'coupon', 'attributes': {'external_id': 'SUMMER_SALE_2024', 'description': '夏季促销折扣券'}}}).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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    注意：`external_id`必须匹配正则表达式`^[0-9_A-z]+$`（仅限字母数字和下划线，不能使用连字符）。获取优惠券码

    Get Coupon Codes

    GET /klaviyo/api/coupon-codes

    注意：此端点需要一个过滤参数。您必须通过优惠券ID或用户档案ID进行过滤。

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    创建优惠券代码

    POST /klaviyo/api/coupon-codes

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    Webhooks

    配置事件通知。

    获取Webhooks

    GET /klaviyo/api/webhooks

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    创建Webhook

    POST /klaviyo/api/webhooks

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    获取 Webhook

    GET /klaviyo/api/webhooks/{webhook_id}

    更新 Webhook

    PATCH /klaviyo/api/webhooks/{webhook_id}

    删除 Webhook

    DELETE /klaviyo/api/webhooks/{webhook_id}

    获取 Webhook 主题

    GET /klaviyo/api/webhook-topics

    账户

    检索账户信息。

    获取账户

    GET /klaviyo/api/accounts

    示例：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    图片

    管理已上传的图片。

    获取图片

    GET /klaviyo/api/images

    示例：

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/images')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('revision', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    获取图片

    GET /klaviyo/api/images/{image_id}

    从 URL 上传图片

    POST /klaviyo/api/images

    示例：

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({'data': {'type': 'image', 'attributes': {'import_from_url': 'https://example.com/image.jpg', 'name': 'Product Image'}}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/images', 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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    表单

    管理注册表单。

    获取表单

    GET /klaviyo/api/forms

    示例：

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/forms')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('revision', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    获取单个表单

    GET /klaviyo/api/forms/{form_id}

    获取表单版本

    GET /klaviyo/api/forms/{form_id}/form-versions

    评价

    管理产品评价。

    获取评价

    GET /klaviyo/api/reviews

    示例：

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/reviews')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('revision', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    获取单个评价

    GET /klaviyo/api/reviews/{review_id}

    更新评价

    PATCH /klaviyo/api/reviews/{review_id}

    通用内容

    管理可重复使用的电子邮件内容块。

    获取通用内容

    GET /klaviyo/api/template-universal-content

    示例：

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/template-universal-content')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('revision', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    创建通用内容

    POST /klaviyo/api/template-universal-content

    更新通用内容

    PATCH /klaviyo/api/template-universal-content/{content_id}

    删除通用内容

    DELETE /klaviyo/api/template-universal-content/{content_id}

    批量管理用户订阅

    批量管理电子邮件/短信订阅。

    批量订阅用户

    POST /klaviyo/api/profile-subscription-bulk-create-jobs

    示例：

    python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    'data': {
        'type': 'profile-subscription-bulk-create-job',
        'attributes': {
            'profiles': {
                'data': [{
                    'type': 'profile',
                    'attributes': {
                        'email': 'newsubscriber@example.com',
                        'subscriptions': {
                            'email': {'marketing': {'consent': 'SUBSCRIBED'}}
                        }
                    }
                }]
            }
        },
        'relationships': {
            'list': {'data': {'type': 'list', 'id': 'LIST_ID'}}
        }
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profile-subscription-bulk-create-jobs', 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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    批量取消订阅用户

    POST /klaviyo/api/profile-subscription-bulk-delete-jobs

    批量屏蔽用户

    POST /klaviyo/api/profile-suppression-bulk-create-jobs

    批量取消屏蔽用户

    POST /klaviyo/api/profile-suppression-bulk-delete-jobs

    用户批量导入

    批量导入用户。

    获取批量导入任务

    GET /klaviyo/api/profile-bulk-import-jobs

    示例：

    python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profile-bulk-import-jobs')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('revision', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    创建批量导入任务

    POST /klaviyo/api/profile-bulk-import-jobs

    筛选

    Klaviyo使用JSON:API筛选语法。常用运算符：

    运算符示例
    等于filter=equals(email,"test@example.com")
    包含filter=contains(name,"newsletter")
    大于filter=greater-than(datetime,2024-01-01T00:00:00Z)
    小于filter=less-than(created,2024-03-01)
    大于或等于filter=greater-or-equal(updated,2024-01-01)
    任何filter=any(status,["draft","scheduled"])

    使用和组合筛选条件：

    filter=and(equals(status,"active"),greater-than(created,2024-01-01))

    分页

    Klaviyo 使用基于游标的分页：

    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', '2026-01-15')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

    响应中包含分页链接：

    {
  "data": [...],
  "links": {
    "self": "https://a.klaviyo.com/api/profiles",
    "next": "https://a.klaviyo.com/api/profiles?page[cursor]=WzE2..."
  }
}

    稀疏字段集

    仅请求特定字段以减少响应大小：

    # 仅请求配置文件的 email 和 first_name 字段
?fields[profile]=email,first_name

# 为包含的关系请求特定字段
?include=lists&fields[list]=name,created

    代码示例

    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

    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 版本控制（推荐版本：2026-01-15）
    • 部分 POST 端点对于成功的创建操作返回200而非201 优惠券
    • external_id必须匹配正则表达式^[0-9_A-z]+$（不能包含连字符）优惠券代码端点需要一个过滤器（例如，
    • filter=equals(coupon.id,"...")）通过 API 创建流程可能受限；流程通常在 Klaviyo 用户界面中创建
    • 重要提示：使用 curl 命令时，若 URL 包含方括号（
    • fields[]、page[]），请使用curl -g以禁用通配符解析重要提示：将 curl 输出通过管道传递给
    • jq或其他命令时，像$MATON_API_KEY$MATON_API_KEY在某些Shell环境中可能无法正确展开。通过管道传递时，您可能会遇到"无效API密钥"的错误。

    错误处理

    状态码含义
    400请求错误或缺少Klaviyo连接
    401无效或缺少Maton API密钥
    403禁止访问 - 权限不足
    404资源未找到
    429请求频率受限（固定窗口算法）
    4xx/5xx来自Klaviyo API的透传错误

    故障排除：API密钥问题

    1. 请检查MATON_API_KEY环境变量是否已设置：
    echo $MATON_API_KEY
    1. 通过列出连接来验证API密钥是否有效：
    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

    资源

    免责申明
    部分文章来自各大搜索引擎，如有侵权，请与我联系删除。
    打赏
    文章底部电脑广告
    手机广告位-内容正文底部
    标签
    上一篇：OpenClaw Backup 下一篇：Security Auditor

    相关文章

    推荐文章
    图片测量软件工具下载链接

    图片测量软件工具下载链接

    图片测量工具使用帮助

    图片测量工具使用帮助

    热门浏览
    标签列表

    您是本站第235251名访客 今日有35篇新文章/评论