{
  "schemaVersion": "1.0",
  "item": {
    "slug": "klaviyo",
    "name": "Klaviyo",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/byungkyu/klaviyo",
    "canonicalUrl": "https://clawhub.ai/byungkyu/klaviyo",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/klaviyo",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=klaviyo",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "LICENSE.txt"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/klaviyo"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/klaviyo",
    "agentPageUrl": "https://openagent3.xyz/skills/klaviyo/agent",
    "manifestUrl": "https://openagent3.xyz/skills/klaviyo/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/klaviyo/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Klaviyo",
        "body": "Access the Klaviyo API with managed OAuth authentication. Manage profiles, lists, segments, campaigns, flows, events, metrics, templates, catalogs, and webhooks for email marketing and customer engagement."
      },
      {
        "title": "Quick Start",
        "body": "# List profiles\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF"
      },
      {
        "title": "Base URL",
        "body": "https://gateway.maton.ai/klaviyo/{native-api-path}\n\nReplace {native-api-path} with the actual Klaviyo API endpoint path. The gateway proxies requests to a.klaviyo.com and automatically injects your OAuth token."
      },
      {
        "title": "Authentication",
        "body": "All requests require the Maton API key in the Authorization header:\n\nAuthorization: Bearer $MATON_API_KEY\n\nEnvironment Variable: Set your API key as MATON_API_KEY:\n\nexport MATON_API_KEY=\"YOUR_API_KEY\""
      },
      {
        "title": "Getting Your API Key",
        "body": "Sign in or create an account at maton.ai\nGo to maton.ai/settings\nCopy your API key"
      },
      {
        "title": "API Versioning",
        "body": "Klaviyo uses date-based API versioning. Include the revision header in all requests:\n\nrevision: 2026-01-15"
      },
      {
        "title": "Connection Management",
        "body": "Manage your Klaviyo OAuth connections at https://ctrl.maton.ai."
      },
      {
        "title": "List Connections",
        "body": "python <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections?app=klaviyo&status=ACTIVE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF"
      },
      {
        "title": "Create Connection",
        "body": "python <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'app': 'klaviyo'}).encode()\nreq = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF"
      },
      {
        "title": "Get Connection",
        "body": "python <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nResponse:\n\n{\n  \"connection\": {\n    \"connection_id\": \"21fd90f9-5935-43cd-b6c8-bde9d915ca80\",\n    \"status\": \"ACTIVE\",\n    \"creation_time\": \"2025-12-08T07:20:53.488460Z\",\n    \"last_updated_time\": \"2026-01-31T20:03:32.593153Z\",\n    \"url\": \"https://connect.maton.ai/?session_token=...\",\n    \"app\": \"klaviyo\",\n    \"metadata\": {}\n  }\n}\n\nOpen the returned url in a browser to complete OAuth authorization."
      },
      {
        "title": "Delete Connection",
        "body": "python <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF"
      },
      {
        "title": "Specifying Connection",
        "body": "If you have multiple Klaviyo connections, specify which one to use with the Maton-Connection header:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nreq.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nIf omitted, the gateway uses the default (oldest) active connection."
      },
      {
        "title": "Profiles",
        "body": "Manage customer data and consent.\n\nGet Profiles\n\nGET /klaviyo/api/profiles\n\nQuery parameters:\n\nfilter - Filter profiles (e.g., filter=equals(email,\"test@example.com\"))\nfields[profile] - Comma-separated list of fields to include\npage[cursor] - Cursor for pagination\npage[size] - Number of results per page (max 100)\nsort - Sort field (prefix with - for descending)\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles?fields[profile]=email,first_name,last_name&page[size]=10')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"profile\",\n      \"id\": \"01GDDKASAP8TKDDA2GRZDSVP4H\",\n      \"attributes\": {\n        \"email\": \"alice@example.com\",\n        \"first_name\": \"Alice\",\n        \"last_name\": \"Johnson\"\n      }\n    }\n  ],\n  \"links\": {\n    \"self\": \"https://a.klaviyo.com/api/profiles\",\n    \"next\": \"https://a.klaviyo.com/api/profiles?page[cursor]=...\"\n  }\n}\n\nGet a Profile\n\nGET /klaviyo/api/profiles/{profile_id}\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate a Profile\n\nPOST /klaviyo/api/profiles\nContent-Type: application/json\n\n{\n  \"data\": {\n    \"type\": \"profile\",\n    \"attributes\": {\n      \"email\": \"newuser@example.com\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"phone_number\": \"+15551234567\",\n      \"properties\": {\n        \"custom_field\": \"value\"\n      }\n    }\n  }\n}\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'profile', 'attributes': {'email': 'newuser@example.com', 'first_name': 'John', 'last_name': 'Doe'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nUpdate a Profile\n\nPATCH /klaviyo/api/profiles/{profile_id}\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'profile', 'id': '01GDDKASAP8TKDDA2GRZDSVP4H', 'attributes': {'first_name': 'Jane'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H', data=data, method='PATCH')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nMerge Profiles\n\nPOST /klaviyo/api/profile-merge\n\nGet Profile Lists\n\nGET /klaviyo/api/profiles/{profile_id}/lists\n\nGet Profile Segments\n\nGET /klaviyo/api/profiles/{profile_id}/segments"
      },
      {
        "title": "Lists",
        "body": "Organize subscribers into static lists.\n\nGet Lists\n\nGET /klaviyo/api/lists\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/lists?fields[list]=name,created,updated')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"list\",\n      \"id\": \"Y6nRLr\",\n      \"attributes\": {\n        \"name\": \"Newsletter Subscribers\",\n        \"created\": \"2024-01-15T10:30:00Z\",\n        \"updated\": \"2024-03-01T14:22:00Z\"\n      }\n    }\n  ]\n}\n\nGet a List\n\nGET /klaviyo/api/lists/{list_id}\n\nCreate a List\n\nPOST /klaviyo/api/lists\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'list', 'attributes': {'name': 'VIP Customers'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/lists', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nUpdate a List\n\nPATCH /klaviyo/api/lists/{list_id}\n\nDelete a List\n\nDELETE /klaviyo/api/lists/{list_id}\n\nAdd Profiles to List\n\nPOST /klaviyo/api/lists/{list_id}/relationships/profiles\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': [{'type': 'profile', 'id': '01GDDKASAP8TKDDA2GRZDSVP4H'}]}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/lists/Y6nRLr/relationships/profiles', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nRemove Profiles from List\n\nDELETE /klaviyo/api/lists/{list_id}/relationships/profiles\n\nGet List Profiles\n\nGET /klaviyo/api/lists/{list_id}/profiles"
      },
      {
        "title": "Segments",
        "body": "Create dynamic audiences based on conditions.\n\nGet Segments\n\nGET /klaviyo/api/segments\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/segments?fields[segment]=name,created,updated')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet a Segment\n\nGET /klaviyo/api/segments/{segment_id}\n\nCreate a Segment\n\nPOST /klaviyo/api/segments\n\nUpdate a Segment\n\nPATCH /klaviyo/api/segments/{segment_id}\n\nDelete a Segment\n\nDELETE /klaviyo/api/segments/{segment_id}\n\nGet Segment Profiles\n\nGET /klaviyo/api/segments/{segment_id}/profiles"
      },
      {
        "title": "Campaigns",
        "body": "Design and send email campaigns.\n\nGet Campaigns\n\nGET /klaviyo/api/campaigns\n\nNote: A channel filter is required. Use filter=equals(messages.channel,\"email\") or filter=equals(messages.channel,\"sms\").\n\nQuery parameters:\n\nfilter - Required. Filter by channel (e.g., filter=equals(messages.channel,\"email\"))\nfields[campaign] - Fields to include\nsort - Sort by field\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/campaigns?filter=equals(messages.channel,\"email\")')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"campaign\",\n      \"id\": \"01GDDKASAP8TKDDA2GRZDSVP4I\",\n      \"attributes\": {\n        \"name\": \"Spring Sale 2024\",\n        \"status\": \"Draft\",\n        \"audiences\": {\n          \"included\": [\"Y6nRLr\"],\n          \"excluded\": []\n        },\n        \"send_options\": {\n          \"use_smart_sending\": true\n        }\n      }\n    }\n  ]\n}\n\nGet a Campaign\n\nGET /klaviyo/api/campaigns/{campaign_id}\n\nCreate a Campaign\n\nPOST /klaviyo/api/campaigns\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'campaign', 'attributes': {'name': 'Summer Newsletter', 'audiences': {'included': ['Y6nRLr']}, 'campaign-messages': {'data': [{'type': 'campaign-message', 'attributes': {'channel': 'email'}}]}}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/campaigns', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nUpdate a Campaign\n\nPATCH /klaviyo/api/campaigns/{campaign_id}\n\nDelete a Campaign\n\nDELETE /klaviyo/api/campaigns/{campaign_id}\n\nSend a Campaign\n\nPOST /klaviyo/api/campaign-send-jobs\n\nGet Recipient Estimation\n\nPOST /klaviyo/api/campaign-recipient-estimations"
      },
      {
        "title": "Flows",
        "body": "Build automated customer journeys.\n\nGet Flows\n\nGET /klaviyo/api/flows\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/flows?fields[flow]=name,status,created,updated')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"flow\",\n      \"id\": \"VJvBNr\",\n      \"attributes\": {\n        \"name\": \"Welcome Series\",\n        \"status\": \"live\",\n        \"created\": \"2024-01-10T08:00:00Z\",\n        \"updated\": \"2024-02-15T12:30:00Z\"\n      }\n    }\n  ]\n}\n\nGet a Flow\n\nGET /klaviyo/api/flows/{flow_id}\n\nCreate a Flow\n\nPOST /klaviyo/api/flows\n\nNote: Flow creation via API may be limited. Flows are typically created through the Klaviyo UI, then managed via API. Use GET, PATCH, and DELETE operations for existing flows.\n\nUpdate Flow Status\n\nPATCH /klaviyo/api/flows/{flow_id}\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'flow', 'id': 'VJvBNr', 'attributes': {'status': 'draft'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/flows/VJvBNr', data=data, method='PATCH')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nDelete a Flow\n\nDELETE /klaviyo/api/flows/{flow_id}\n\nGet Flow Actions\n\nGET /klaviyo/api/flows/{flow_id}/flow-actions\n\nGet Flow Messages\n\nGET /klaviyo/api/flows/{flow_id}/flow-messages"
      },
      {
        "title": "Events",
        "body": "Track customer interactions and behaviors.\n\nGet Events\n\nGET /klaviyo/api/events\n\nQuery parameters:\n\nfilter - Filter events (e.g., filter=equals(metric_id,\"ABC123\"))\nfields[event] - Fields to include\nsort - Sort by field (default: -datetime)\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/events?filter=greater-than(datetime,2024-01-01T00:00:00Z)&page[size]=50')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"event\",\n      \"id\": \"4vRpBT\",\n      \"attributes\": {\n        \"metric_id\": \"TxVpCr\",\n        \"profile_id\": \"01GDDKASAP8TKDDA2GRZDSVP4H\",\n        \"datetime\": \"2024-03-15T14:30:00Z\",\n        \"event_properties\": {\n          \"value\": 99.99,\n          \"product_name\": \"Running Shoes\"\n        }\n      }\n    }\n  ]\n}\n\nGet an Event\n\nGET /klaviyo/api/events/{event_id}\n\nCreate an Event\n\nPOST /klaviyo/api/events\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'event', 'attributes': {'profile': {'data': {'type': 'profile', 'attributes': {'email': 'customer@example.com'}}}, 'metric': {'data': {'type': 'metric', 'attributes': {'name': 'Viewed Product'}}}, 'properties': {'product_id': 'SKU123', 'product_name': 'Blue T-Shirt', 'price': 29.99}}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/events', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nBulk Create Events\n\nPOST /klaviyo/api/event-bulk-create-jobs"
      },
      {
        "title": "Metrics",
        "body": "Access performance data and analytics.\n\nGet Metrics\n\nGET /klaviyo/api/metrics\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/metrics')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"metric\",\n      \"id\": \"TxVpCr\",\n      \"attributes\": {\n        \"name\": \"Placed Order\",\n        \"created\": \"2024-01-01T00:00:00Z\",\n        \"updated\": \"2024-03-01T00:00:00Z\",\n        \"integration\": {\n          \"object\": \"integration\",\n          \"id\": \"shopify\",\n          \"name\": \"Shopify\"\n        }\n      }\n    }\n  ]\n}\n\nGet a Metric\n\nGET /klaviyo/api/metrics/{metric_id}\n\nQuery Metric Aggregates\n\nPOST /klaviyo/api/metric-aggregates\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = 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()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/metric-aggregates', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF"
      },
      {
        "title": "Templates",
        "body": "Manage email templates.\n\nGet Templates\n\nGET /klaviyo/api/templates\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/templates?fields[template]=name,created,updated')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet a Template\n\nGET /klaviyo/api/templates/{template_id}\n\nCreate a Template\n\nPOST /klaviyo/api/templates\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'template', 'attributes': {'name': 'Welcome Email', 'editor_type': 'CODE', 'html': '<html><body><h1>Welcome!</h1></body></html>'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/templates', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nUpdate a Template\n\nPATCH /klaviyo/api/templates/{template_id}\n\nDelete a Template\n\nDELETE /klaviyo/api/templates/{template_id}\n\nRender a Template\n\nPOST /klaviyo/api/template-render\n\nClone a Template\n\nPOST /klaviyo/api/template-clone"
      },
      {
        "title": "Catalogs",
        "body": "Manage product catalogs.\n\nGet Catalog Items\n\nGET /klaviyo/api/catalog-items\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/catalog-items?fields[catalog-item]=title,price,url')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"catalog-item\",\n      \"id\": \"$custom:::$default:::PROD-001\",\n      \"attributes\": {\n        \"title\": \"Blue Running Shoes\",\n        \"price\": 129.99,\n        \"url\": \"https://store.example.com/products/blue-running-shoes\"\n      }\n    }\n  ]\n}\n\nGet a Catalog Item\n\nGET /klaviyo/api/catalog-items/{catalog_item_id}\n\nCreate Catalog Items\n\nPOST /klaviyo/api/catalog-items\n\nUpdate Catalog Item\n\nPATCH /klaviyo/api/catalog-items/{catalog_item_id}\n\nDelete Catalog Item\n\nDELETE /klaviyo/api/catalog-items/{catalog_item_id}\n\nGet Catalog Variants\n\nGET /klaviyo/api/catalog-variants\n\nGet Catalog Categories\n\nGET /klaviyo/api/catalog-categories"
      },
      {
        "title": "Tags",
        "body": "Organize resources with tags.\n\nGet Tags\n\nGET /klaviyo/api/tags\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/tags')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate a Tag\n\nPOST /klaviyo/api/tags\n\nUpdate a Tag\n\nPATCH /klaviyo/api/tags/{tag_id}\n\nDelete a Tag\n\nDELETE /klaviyo/api/tags/{tag_id}\n\nTag a Campaign\n\nPOST /klaviyo/api/tag-campaign-relationships\n\nTag a Flow\n\nPOST /klaviyo/api/tag-flow-relationships\n\nGet Tag Groups\n\nGET /klaviyo/api/tag-groups\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/tag-groups')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Tag Group\n\nPOST /klaviyo/api/tag-groups\n\nUpdate Tag Group\n\nPATCH /klaviyo/api/tag-groups/{tag_group_id}\n\nDelete Tag Group\n\nDELETE /klaviyo/api/tag-groups/{tag_group_id}"
      },
      {
        "title": "Coupons",
        "body": "Manage discount codes.\n\nGet Coupons\n\nGET /klaviyo/api/coupons\n\nCreate a Coupon\n\nPOST /klaviyo/api/coupons\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'coupon', 'attributes': {'external_id': 'SUMMER_SALE_2024', 'description': 'Summer sale discount coupon'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/coupons', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nNote: The external_id must match regex ^[0-9_A-z]+$ (alphanumeric and underscores only, no hyphens).\n\nGet Coupon Codes\n\nGET /klaviyo/api/coupon-codes\n\nNote: This endpoint requires a filter parameter. You must filter by coupon ID or profile ID.\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/coupon-codes?filter=equals(coupon.id,\"SUMMER_SALE_2024\")')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Coupon Codes\n\nPOST /klaviyo/api/coupon-codes\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = 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()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/coupon-codes', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF"
      },
      {
        "title": "Webhooks",
        "body": "Configure event notifications.\n\nGet Webhooks\n\nGET /klaviyo/api/webhooks\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/webhooks')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Webhook\n\nPOST /klaviyo/api/webhooks\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = 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()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/webhooks', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet a Webhook\n\nGET /klaviyo/api/webhooks/{webhook_id}\n\nUpdate a Webhook\n\nPATCH /klaviyo/api/webhooks/{webhook_id}\n\nDelete a Webhook\n\nDELETE /klaviyo/api/webhooks/{webhook_id}\n\nGet Webhook Topics\n\nGET /klaviyo/api/webhook-topics"
      },
      {
        "title": "Accounts",
        "body": "Retrieve account information.\n\nGet Accounts\n\nGET /klaviyo/api/accounts\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/accounts')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF"
      },
      {
        "title": "Images",
        "body": "Manage uploaded images.\n\nGet Images\n\nGET /klaviyo/api/images\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/images')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet an Image\n\nGET /klaviyo/api/images/{image_id}\n\nUpload Image from URL\n\nPOST /klaviyo/api/images\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'image', 'attributes': {'import_from_url': 'https://example.com/image.jpg', 'name': 'Product Image'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/images', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF"
      },
      {
        "title": "Forms",
        "body": "Manage signup forms.\n\nGet Forms\n\nGET /klaviyo/api/forms\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/forms')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet a Form\n\nGET /klaviyo/api/forms/{form_id}\n\nGet Form Versions\n\nGET /klaviyo/api/forms/{form_id}/form-versions"
      },
      {
        "title": "Reviews",
        "body": "Manage product reviews.\n\nGet Reviews\n\nGET /klaviyo/api/reviews\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/reviews')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet a Review\n\nGET /klaviyo/api/reviews/{review_id}\n\nUpdate Review\n\nPATCH /klaviyo/api/reviews/{review_id}"
      },
      {
        "title": "Universal Content",
        "body": "Manage reusable email content blocks.\n\nGet Universal Content\n\nGET /klaviyo/api/template-universal-content\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/template-universal-content')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Universal Content\n\nPOST /klaviyo/api/template-universal-content\n\nUpdate Universal Content\n\nPATCH /klaviyo/api/template-universal-content/{content_id}\n\nDelete Universal Content\n\nDELETE /klaviyo/api/template-universal-content/{content_id}"
      },
      {
        "title": "Bulk Profile Subscriptions",
        "body": "Manage email/SMS subscriptions in bulk.\n\nBulk Subscribe Profiles\n\nPOST /klaviyo/api/profile-subscription-bulk-create-jobs\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({\n    'data': {\n        'type': 'profile-subscription-bulk-create-job',\n        'attributes': {\n            'profiles': {\n                'data': [{\n                    'type': 'profile',\n                    'attributes': {\n                        'email': 'newsubscriber@example.com',\n                        'subscriptions': {\n                            'email': {'marketing': {'consent': 'SUBSCRIBED'}}\n                        }\n                    }\n                }]\n            }\n        },\n        'relationships': {\n            'list': {'data': {'type': 'list', 'id': 'LIST_ID'}}\n        }\n    }\n}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profile-subscription-bulk-create-jobs', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nBulk Unsubscribe Profiles\n\nPOST /klaviyo/api/profile-subscription-bulk-delete-jobs\n\nBulk Suppress Profiles\n\nPOST /klaviyo/api/profile-suppression-bulk-create-jobs\n\nBulk Unsuppress Profiles\n\nPOST /klaviyo/api/profile-suppression-bulk-delete-jobs"
      },
      {
        "title": "Profile Bulk Import",
        "body": "Import profiles in bulk.\n\nGet Bulk Import Jobs\n\nGET /klaviyo/api/profile-bulk-import-jobs\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profile-bulk-import-jobs')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Bulk Import Job\n\nPOST /klaviyo/api/profile-bulk-import-jobs"
      },
      {
        "title": "Filtering",
        "body": "Klaviyo uses JSON:API filtering syntax. Common operators:\n\nOperatorExampleequalsfilter=equals(email,\"test@example.com\")containsfilter=contains(name,\"newsletter\")greater-thanfilter=greater-than(datetime,2024-01-01T00:00:00Z)less-thanfilter=less-than(created,2024-03-01)greater-or-equalfilter=greater-or-equal(updated,2024-01-01)anyfilter=any(status,[\"draft\",\"scheduled\"])\n\nCombine filters with and:\n\nfilter=and(equals(status,\"active\"),greater-than(created,2024-01-01))"
      },
      {
        "title": "Pagination",
        "body": "Klaviyo uses cursor-based pagination:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles?page[size]=50&page[cursor]=CURSOR_TOKEN')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nResponse includes pagination links:\n\n{\n  \"data\": [...],\n  \"links\": {\n    \"self\": \"https://a.klaviyo.com/api/profiles\",\n    \"next\": \"https://a.klaviyo.com/api/profiles?page[cursor]=WzE2...\"\n  }\n}"
      },
      {
        "title": "Sparse Fieldsets",
        "body": "Request only specific fields to reduce response size:\n\n# Request only email and first_name for profiles\n?fields[profile]=email,first_name\n\n# Request specific fields for included relationships\n?include=lists&fields[list]=name,created"
      },
      {
        "title": "JavaScript",
        "body": "const response = await fetch(\n  'https://gateway.maton.ai/klaviyo/api/profiles?fields[profile]=email,first_name',\n  {\n    headers: {\n      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,\n      'revision': '2024-10-15'\n    }\n  }\n);\nconst data = await response.json();"
      },
      {
        "title": "Python",
        "body": "import os\nimport requests\n\nresponse = requests.get(\n    'https://gateway.maton.ai/klaviyo/api/profiles',\n    headers={\n        'Authorization': f'Bearer {os.environ[\"MATON_API_KEY\"]}',\n        'revision': '2024-10-15'\n    },\n    params={'fields[profile]': 'email,first_name'}\n)\ndata = response.json()"
      },
      {
        "title": "Notes",
        "body": "All requests use JSON:API specification\nTimestamps are in ISO 8601 RFC 3339 format (e.g., 2024-01-16T23:20:50.52Z)\nResource IDs are strings (often base64-encoded)\nUse sparse fieldsets to optimize response size\nInclude revision header for API versioning (recommended: 2026-01-15)\nSome POST endpoints return 200 instead of 201 for successful creation\nCoupon external_id must match regex ^[0-9_A-z]+$ (no hyphens)\nCoupon codes endpoint requires a filter (e.g., filter=equals(coupon.id,\"...\"))\nFlow creation via API may be limited; flows are typically created in the Klaviyo UI\nIMPORTANT: When using curl commands, use curl -g when URLs contain brackets (fields[], page[]) to disable glob parsing\nIMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get \"Invalid API key\" errors when piping."
      },
      {
        "title": "Error Handling",
        "body": "StatusMeaning400Bad request or missing Klaviyo connection401Invalid or missing Maton API key403Forbidden - insufficient permissions404Resource not found429Rate limited (fixed-window algorithm)4xx/5xxPassthrough error from Klaviyo API"
      },
      {
        "title": "Troubleshooting: API Key Issues",
        "body": "Check that the MATON_API_KEY environment variable is set:\n\necho $MATON_API_KEY\n\nVerify the API key is valid by listing connections:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF"
      },
      {
        "title": "Troubleshooting: Invalid App Name",
        "body": "Ensure your URL path starts with klaviyo. For example:\n\nCorrect: https://gateway.maton.ai/klaviyo/api/profiles\nIncorrect: https://gateway.maton.ai/api/profiles"
      },
      {
        "title": "Resources",
        "body": "Klaviyo API Documentation\nAPI Reference\nKlaviyo Developer Portal\nMaton Community\nMaton Support"
      }
    ],
    "body": "Klaviyo\n\nAccess the Klaviyo API with managed OAuth authentication. Manage profiles, lists, segments, campaigns, flows, events, metrics, templates, catalogs, and webhooks for email marketing and customer engagement.\n\nQuick Start\n# List profiles\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nBase URL\nhttps://gateway.maton.ai/klaviyo/{native-api-path}\n\n\nReplace {native-api-path} with the actual Klaviyo API endpoint path. The gateway proxies requests to a.klaviyo.com and automatically injects your OAuth token.\n\nAuthentication\n\nAll requests require the Maton API key in the Authorization header:\n\nAuthorization: Bearer $MATON_API_KEY\n\n\nEnvironment Variable: Set your API key as MATON_API_KEY:\n\nexport MATON_API_KEY=\"YOUR_API_KEY\"\n\nGetting Your API Key\nSign in or create an account at maton.ai\nGo to maton.ai/settings\nCopy your API key\nAPI Versioning\n\nKlaviyo uses date-based API versioning. Include the revision header in all requests:\n\nrevision: 2026-01-15\n\nConnection Management\n\nManage your Klaviyo OAuth connections at https://ctrl.maton.ai.\n\nList Connections\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections?app=klaviyo&status=ACTIVE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Connection\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'app': 'klaviyo'}).encode()\nreq = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet Connection\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nResponse:\n\n{\n  \"connection\": {\n    \"connection_id\": \"21fd90f9-5935-43cd-b6c8-bde9d915ca80\",\n    \"status\": \"ACTIVE\",\n    \"creation_time\": \"2025-12-08T07:20:53.488460Z\",\n    \"last_updated_time\": \"2026-01-31T20:03:32.593153Z\",\n    \"url\": \"https://connect.maton.ai/?session_token=...\",\n    \"app\": \"klaviyo\",\n    \"metadata\": {}\n  }\n}\n\n\nOpen the returned url in a browser to complete OAuth authorization.\n\nDelete Connection\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nSpecifying Connection\n\nIf you have multiple Klaviyo connections, specify which one to use with the Maton-Connection header:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nreq.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nIf omitted, the gateway uses the default (oldest) active connection.\n\nAPI Reference\nProfiles\n\nManage customer data and consent.\n\nGet Profiles\nGET /klaviyo/api/profiles\n\n\nQuery parameters:\n\nfilter - Filter profiles (e.g., filter=equals(email,\"test@example.com\"))\nfields[profile] - Comma-separated list of fields to include\npage[cursor] - Cursor for pagination\npage[size] - Number of results per page (max 100)\nsort - Sort field (prefix with - for descending)\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles?fields[profile]=email,first_name,last_name&page[size]=10')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"profile\",\n      \"id\": \"01GDDKASAP8TKDDA2GRZDSVP4H\",\n      \"attributes\": {\n        \"email\": \"alice@example.com\",\n        \"first_name\": \"Alice\",\n        \"last_name\": \"Johnson\"\n      }\n    }\n  ],\n  \"links\": {\n    \"self\": \"https://a.klaviyo.com/api/profiles\",\n    \"next\": \"https://a.klaviyo.com/api/profiles?page[cursor]=...\"\n  }\n}\n\nGet a Profile\nGET /klaviyo/api/profiles/{profile_id}\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate a Profile\nPOST /klaviyo/api/profiles\nContent-Type: application/json\n\n{\n  \"data\": {\n    \"type\": \"profile\",\n    \"attributes\": {\n      \"email\": \"newuser@example.com\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"phone_number\": \"+15551234567\",\n      \"properties\": {\n        \"custom_field\": \"value\"\n      }\n    }\n  }\n}\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'profile', 'attributes': {'email': 'newuser@example.com', 'first_name': 'John', 'last_name': 'Doe'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nUpdate a Profile\nPATCH /klaviyo/api/profiles/{profile_id}\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'profile', 'id': '01GDDKASAP8TKDDA2GRZDSVP4H', 'attributes': {'first_name': 'Jane'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H', data=data, method='PATCH')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nMerge Profiles\nPOST /klaviyo/api/profile-merge\n\nGet Profile Lists\nGET /klaviyo/api/profiles/{profile_id}/lists\n\nGet Profile Segments\nGET /klaviyo/api/profiles/{profile_id}/segments\n\nLists\n\nOrganize subscribers into static lists.\n\nGet Lists\nGET /klaviyo/api/lists\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/lists?fields[list]=name,created,updated')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"list\",\n      \"id\": \"Y6nRLr\",\n      \"attributes\": {\n        \"name\": \"Newsletter Subscribers\",\n        \"created\": \"2024-01-15T10:30:00Z\",\n        \"updated\": \"2024-03-01T14:22:00Z\"\n      }\n    }\n  ]\n}\n\nGet a List\nGET /klaviyo/api/lists/{list_id}\n\nCreate a List\nPOST /klaviyo/api/lists\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'list', 'attributes': {'name': 'VIP Customers'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/lists', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nUpdate a List\nPATCH /klaviyo/api/lists/{list_id}\n\nDelete a List\nDELETE /klaviyo/api/lists/{list_id}\n\nAdd Profiles to List\nPOST /klaviyo/api/lists/{list_id}/relationships/profiles\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': [{'type': 'profile', 'id': '01GDDKASAP8TKDDA2GRZDSVP4H'}]}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/lists/Y6nRLr/relationships/profiles', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nRemove Profiles from List\nDELETE /klaviyo/api/lists/{list_id}/relationships/profiles\n\nGet List Profiles\nGET /klaviyo/api/lists/{list_id}/profiles\n\nSegments\n\nCreate dynamic audiences based on conditions.\n\nGet Segments\nGET /klaviyo/api/segments\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/segments?fields[segment]=name,created,updated')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet a Segment\nGET /klaviyo/api/segments/{segment_id}\n\nCreate a Segment\nPOST /klaviyo/api/segments\n\nUpdate a Segment\nPATCH /klaviyo/api/segments/{segment_id}\n\nDelete a Segment\nDELETE /klaviyo/api/segments/{segment_id}\n\nGet Segment Profiles\nGET /klaviyo/api/segments/{segment_id}/profiles\n\nCampaigns\n\nDesign and send email campaigns.\n\nGet Campaigns\nGET /klaviyo/api/campaigns\n\n\nNote: A channel filter is required. Use filter=equals(messages.channel,\"email\") or filter=equals(messages.channel,\"sms\").\n\nQuery parameters:\n\nfilter - Required. Filter by channel (e.g., filter=equals(messages.channel,\"email\"))\nfields[campaign] - Fields to include\nsort - Sort by field\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/campaigns?filter=equals(messages.channel,\"email\")')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"campaign\",\n      \"id\": \"01GDDKASAP8TKDDA2GRZDSVP4I\",\n      \"attributes\": {\n        \"name\": \"Spring Sale 2024\",\n        \"status\": \"Draft\",\n        \"audiences\": {\n          \"included\": [\"Y6nRLr\"],\n          \"excluded\": []\n        },\n        \"send_options\": {\n          \"use_smart_sending\": true\n        }\n      }\n    }\n  ]\n}\n\nGet a Campaign\nGET /klaviyo/api/campaigns/{campaign_id}\n\nCreate a Campaign\nPOST /klaviyo/api/campaigns\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'campaign', 'attributes': {'name': 'Summer Newsletter', 'audiences': {'included': ['Y6nRLr']}, 'campaign-messages': {'data': [{'type': 'campaign-message', 'attributes': {'channel': 'email'}}]}}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/campaigns', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nUpdate a Campaign\nPATCH /klaviyo/api/campaigns/{campaign_id}\n\nDelete a Campaign\nDELETE /klaviyo/api/campaigns/{campaign_id}\n\nSend a Campaign\nPOST /klaviyo/api/campaign-send-jobs\n\nGet Recipient Estimation\nPOST /klaviyo/api/campaign-recipient-estimations\n\nFlows\n\nBuild automated customer journeys.\n\nGet Flows\nGET /klaviyo/api/flows\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/flows?fields[flow]=name,status,created,updated')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"flow\",\n      \"id\": \"VJvBNr\",\n      \"attributes\": {\n        \"name\": \"Welcome Series\",\n        \"status\": \"live\",\n        \"created\": \"2024-01-10T08:00:00Z\",\n        \"updated\": \"2024-02-15T12:30:00Z\"\n      }\n    }\n  ]\n}\n\nGet a Flow\nGET /klaviyo/api/flows/{flow_id}\n\nCreate a Flow\nPOST /klaviyo/api/flows\n\n\nNote: Flow creation via API may be limited. Flows are typically created through the Klaviyo UI, then managed via API. Use GET, PATCH, and DELETE operations for existing flows.\n\nUpdate Flow Status\nPATCH /klaviyo/api/flows/{flow_id}\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'flow', 'id': 'VJvBNr', 'attributes': {'status': 'draft'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/flows/VJvBNr', data=data, method='PATCH')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nDelete a Flow\nDELETE /klaviyo/api/flows/{flow_id}\n\nGet Flow Actions\nGET /klaviyo/api/flows/{flow_id}/flow-actions\n\nGet Flow Messages\nGET /klaviyo/api/flows/{flow_id}/flow-messages\n\nEvents\n\nTrack customer interactions and behaviors.\n\nGet Events\nGET /klaviyo/api/events\n\n\nQuery parameters:\n\nfilter - Filter events (e.g., filter=equals(metric_id,\"ABC123\"))\nfields[event] - Fields to include\nsort - Sort by field (default: -datetime)\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/events?filter=greater-than(datetime,2024-01-01T00:00:00Z)&page[size]=50')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"event\",\n      \"id\": \"4vRpBT\",\n      \"attributes\": {\n        \"metric_id\": \"TxVpCr\",\n        \"profile_id\": \"01GDDKASAP8TKDDA2GRZDSVP4H\",\n        \"datetime\": \"2024-03-15T14:30:00Z\",\n        \"event_properties\": {\n          \"value\": 99.99,\n          \"product_name\": \"Running Shoes\"\n        }\n      }\n    }\n  ]\n}\n\nGet an Event\nGET /klaviyo/api/events/{event_id}\n\nCreate an Event\nPOST /klaviyo/api/events\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'event', 'attributes': {'profile': {'data': {'type': 'profile', 'attributes': {'email': 'customer@example.com'}}}, 'metric': {'data': {'type': 'metric', 'attributes': {'name': 'Viewed Product'}}}, 'properties': {'product_id': 'SKU123', 'product_name': 'Blue T-Shirt', 'price': 29.99}}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/events', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nBulk Create Events\nPOST /klaviyo/api/event-bulk-create-jobs\n\nMetrics\n\nAccess performance data and analytics.\n\nGet Metrics\nGET /klaviyo/api/metrics\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/metrics')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"metric\",\n      \"id\": \"TxVpCr\",\n      \"attributes\": {\n        \"name\": \"Placed Order\",\n        \"created\": \"2024-01-01T00:00:00Z\",\n        \"updated\": \"2024-03-01T00:00:00Z\",\n        \"integration\": {\n          \"object\": \"integration\",\n          \"id\": \"shopify\",\n          \"name\": \"Shopify\"\n        }\n      }\n    }\n  ]\n}\n\nGet a Metric\nGET /klaviyo/api/metrics/{metric_id}\n\nQuery Metric Aggregates\nPOST /klaviyo/api/metric-aggregates\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = 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()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/metric-aggregates', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nTemplates\n\nManage email templates.\n\nGet Templates\nGET /klaviyo/api/templates\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/templates?fields[template]=name,created,updated')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet a Template\nGET /klaviyo/api/templates/{template_id}\n\nCreate a Template\nPOST /klaviyo/api/templates\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'template', 'attributes': {'name': 'Welcome Email', 'editor_type': 'CODE', 'html': '<html><body><h1>Welcome!</h1></body></html>'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/templates', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nUpdate a Template\nPATCH /klaviyo/api/templates/{template_id}\n\nDelete a Template\nDELETE /klaviyo/api/templates/{template_id}\n\nRender a Template\nPOST /klaviyo/api/template-render\n\nClone a Template\nPOST /klaviyo/api/template-clone\n\nCatalogs\n\nManage product catalogs.\n\nGet Catalog Items\nGET /klaviyo/api/catalog-items\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/catalog-items?fields[catalog-item]=title,price,url')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nResponse:\n\n{\n  \"data\": [\n    {\n      \"type\": \"catalog-item\",\n      \"id\": \"$custom:::$default:::PROD-001\",\n      \"attributes\": {\n        \"title\": \"Blue Running Shoes\",\n        \"price\": 129.99,\n        \"url\": \"https://store.example.com/products/blue-running-shoes\"\n      }\n    }\n  ]\n}\n\nGet a Catalog Item\nGET /klaviyo/api/catalog-items/{catalog_item_id}\n\nCreate Catalog Items\nPOST /klaviyo/api/catalog-items\n\nUpdate Catalog Item\nPATCH /klaviyo/api/catalog-items/{catalog_item_id}\n\nDelete Catalog Item\nDELETE /klaviyo/api/catalog-items/{catalog_item_id}\n\nGet Catalog Variants\nGET /klaviyo/api/catalog-variants\n\nGet Catalog Categories\nGET /klaviyo/api/catalog-categories\n\nTags\n\nOrganize resources with tags.\n\nGet Tags\nGET /klaviyo/api/tags\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/tags')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate a Tag\nPOST /klaviyo/api/tags\n\nUpdate a Tag\nPATCH /klaviyo/api/tags/{tag_id}\n\nDelete a Tag\nDELETE /klaviyo/api/tags/{tag_id}\n\nTag a Campaign\nPOST /klaviyo/api/tag-campaign-relationships\n\nTag a Flow\nPOST /klaviyo/api/tag-flow-relationships\n\nGet Tag Groups\nGET /klaviyo/api/tag-groups\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/tag-groups')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Tag Group\nPOST /klaviyo/api/tag-groups\n\nUpdate Tag Group\nPATCH /klaviyo/api/tag-groups/{tag_group_id}\n\nDelete Tag Group\nDELETE /klaviyo/api/tag-groups/{tag_group_id}\n\nCoupons\n\nManage discount codes.\n\nGet Coupons\nGET /klaviyo/api/coupons\n\nCreate a Coupon\nPOST /klaviyo/api/coupons\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'coupon', 'attributes': {'external_id': 'SUMMER_SALE_2024', 'description': 'Summer sale discount coupon'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/coupons', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nNote: The external_id must match regex ^[0-9_A-z]+$ (alphanumeric and underscores only, no hyphens).\n\nGet Coupon Codes\nGET /klaviyo/api/coupon-codes\n\n\nNote: This endpoint requires a filter parameter. You must filter by coupon ID or profile ID.\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/coupon-codes?filter=equals(coupon.id,\"SUMMER_SALE_2024\")')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Coupon Codes\nPOST /klaviyo/api/coupon-codes\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = 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()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/coupon-codes', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nWebhooks\n\nConfigure event notifications.\n\nGet Webhooks\nGET /klaviyo/api/webhooks\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/webhooks')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Webhook\nPOST /klaviyo/api/webhooks\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = 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()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/webhooks', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet a Webhook\nGET /klaviyo/api/webhooks/{webhook_id}\n\nUpdate a Webhook\nPATCH /klaviyo/api/webhooks/{webhook_id}\n\nDelete a Webhook\nDELETE /klaviyo/api/webhooks/{webhook_id}\n\nGet Webhook Topics\nGET /klaviyo/api/webhook-topics\n\nAccounts\n\nRetrieve account information.\n\nGet Accounts\nGET /klaviyo/api/accounts\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/accounts')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nImages\n\nManage uploaded images.\n\nGet Images\nGET /klaviyo/api/images\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/images')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet an Image\nGET /klaviyo/api/images/{image_id}\n\nUpload Image from URL\nPOST /klaviyo/api/images\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'data': {'type': 'image', 'attributes': {'import_from_url': 'https://example.com/image.jpg', 'name': 'Product Image'}}}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/images', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nForms\n\nManage signup forms.\n\nGet Forms\nGET /klaviyo/api/forms\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/forms')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet a Form\nGET /klaviyo/api/forms/{form_id}\n\nGet Form Versions\nGET /klaviyo/api/forms/{form_id}/form-versions\n\nReviews\n\nManage product reviews.\n\nGet Reviews\nGET /klaviyo/api/reviews\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/reviews')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nGet a Review\nGET /klaviyo/api/reviews/{review_id}\n\nUpdate Review\nPATCH /klaviyo/api/reviews/{review_id}\n\nUniversal Content\n\nManage reusable email content blocks.\n\nGet Universal Content\nGET /klaviyo/api/template-universal-content\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/template-universal-content')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Universal Content\nPOST /klaviyo/api/template-universal-content\n\nUpdate Universal Content\nPATCH /klaviyo/api/template-universal-content/{content_id}\n\nDelete Universal Content\nDELETE /klaviyo/api/template-universal-content/{content_id}\n\nBulk Profile Subscriptions\n\nManage email/SMS subscriptions in bulk.\n\nBulk Subscribe Profiles\nPOST /klaviyo/api/profile-subscription-bulk-create-jobs\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({\n    'data': {\n        'type': 'profile-subscription-bulk-create-job',\n        'attributes': {\n            'profiles': {\n                'data': [{\n                    'type': 'profile',\n                    'attributes': {\n                        'email': 'newsubscriber@example.com',\n                        'subscriptions': {\n                            'email': {'marketing': {'consent': 'SUBSCRIBED'}}\n                        }\n                    }\n                }]\n            }\n        },\n        'relationships': {\n            'list': {'data': {'type': 'list', 'id': 'LIST_ID'}}\n        }\n    }\n}).encode()\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profile-subscription-bulk-create-jobs', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nBulk Unsubscribe Profiles\nPOST /klaviyo/api/profile-subscription-bulk-delete-jobs\n\nBulk Suppress Profiles\nPOST /klaviyo/api/profile-suppression-bulk-create-jobs\n\nBulk Unsuppress Profiles\nPOST /klaviyo/api/profile-suppression-bulk-delete-jobs\n\nProfile Bulk Import\n\nImport profiles in bulk.\n\nGet Bulk Import Jobs\nGET /klaviyo/api/profile-bulk-import-jobs\n\n\nExample:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profile-bulk-import-jobs')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nCreate Bulk Import Job\nPOST /klaviyo/api/profile-bulk-import-jobs\n\nFiltering\n\nKlaviyo uses JSON:API filtering syntax. Common operators:\n\nOperator\tExample\nequals\tfilter=equals(email,\"test@example.com\")\ncontains\tfilter=contains(name,\"newsletter\")\ngreater-than\tfilter=greater-than(datetime,2024-01-01T00:00:00Z)\nless-than\tfilter=less-than(created,2024-03-01)\ngreater-or-equal\tfilter=greater-or-equal(updated,2024-01-01)\nany\tfilter=any(status,[\"draft\",\"scheduled\"])\n\nCombine filters with and:\n\nfilter=and(equals(status,\"active\"),greater-than(created,2024-01-01))\n\nPagination\n\nKlaviyo uses cursor-based pagination:\n\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles?page[size]=50&page[cursor]=CURSOR_TOKEN')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('revision', '2026-01-15')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\n\nResponse includes pagination links:\n\n{\n  \"data\": [...],\n  \"links\": {\n    \"self\": \"https://a.klaviyo.com/api/profiles\",\n    \"next\": \"https://a.klaviyo.com/api/profiles?page[cursor]=WzE2...\"\n  }\n}\n\nSparse Fieldsets\n\nRequest only specific fields to reduce response size:\n\n# Request only email and first_name for profiles\n?fields[profile]=email,first_name\n\n# Request specific fields for included relationships\n?include=lists&fields[list]=name,created\n\nCode Examples\nJavaScript\nconst response = await fetch(\n  'https://gateway.maton.ai/klaviyo/api/profiles?fields[profile]=email,first_name',\n  {\n    headers: {\n      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,\n      'revision': '2024-10-15'\n    }\n  }\n);\nconst data = await response.json();\n\nPython\nimport os\nimport requests\n\nresponse = requests.get(\n    'https://gateway.maton.ai/klaviyo/api/profiles',\n    headers={\n        'Authorization': f'Bearer {os.environ[\"MATON_API_KEY\"]}',\n        'revision': '2024-10-15'\n    },\n    params={'fields[profile]': 'email,first_name'}\n)\ndata = response.json()\n\nNotes\nAll requests use JSON:API specification\nTimestamps are in ISO 8601 RFC 3339 format (e.g., 2024-01-16T23:20:50.52Z)\nResource IDs are strings (often base64-encoded)\nUse sparse fieldsets to optimize response size\nInclude revision header for API versioning (recommended: 2026-01-15)\nSome POST endpoints return 200 instead of 201 for successful creation\nCoupon external_id must match regex ^[0-9_A-z]+$ (no hyphens)\nCoupon codes endpoint requires a filter (e.g., filter=equals(coupon.id,\"...\"))\nFlow creation via API may be limited; flows are typically created in the Klaviyo UI\nIMPORTANT: When using curl commands, use curl -g when URLs contain brackets (fields[], page[]) to disable glob parsing\nIMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get \"Invalid API key\" errors when piping.\nError Handling\nStatus\tMeaning\n400\tBad request or missing Klaviyo connection\n401\tInvalid or missing Maton API key\n403\tForbidden - insufficient permissions\n404\tResource not found\n429\tRate limited (fixed-window algorithm)\n4xx/5xx\tPassthrough error from Klaviyo API\nTroubleshooting: API Key Issues\nCheck that the MATON_API_KEY environment variable is set:\necho $MATON_API_KEY\n\nVerify the API key is valid by listing connections:\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://ctrl.maton.ai/connections')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n\nTroubleshooting: Invalid App Name\nEnsure your URL path starts with klaviyo. For example:\nCorrect: https://gateway.maton.ai/klaviyo/api/profiles\nIncorrect: https://gateway.maton.ai/api/profiles\nResources\nKlaviyo API Documentation\nAPI Reference\nKlaviyo Developer Portal\nMaton Community\nMaton Support"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/byungkyu/klaviyo",
    "publisherUrl": "https://clawhub.ai/byungkyu/klaviyo",
    "owner": "byungkyu",
    "version": "1.0.4",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/klaviyo",
    "downloadUrl": "https://openagent3.xyz/downloads/klaviyo",
    "agentUrl": "https://openagent3.xyz/skills/klaviyo/agent",
    "manifestUrl": "https://openagent3.xyz/skills/klaviyo/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/klaviyo/agent.md"
  }
}