klaviyo

# Klaviyo 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. ## Quick Start ```bash # List profiles python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/klaviyo/{native-api-path} ``` Replace `{native-api-path}` with the actual Klaviyo API endpoint path. The gateway proxies requests to `a.klaviyo.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## API Versioning Klaviyo uses date-based API versioning. Include the `revision` header in all requests: ``` revision: 2024-10-15 ``` ## Connection Management Manage your Klaviyo OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=klaviyo&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'klaviyo'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "klaviyo", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Klaviyo connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Profiles Manage customer data and consent. #### Get Profiles ```bash GET /klaviyo/api/profiles ``` Query parameters: - `filter` - Filter profiles (e.g., `filter=equals(email,"test@example.com")`) - `fields[profile]` - Comma-separated list of fields to include - `page[cursor]` - Cursor for pagination - `page[size]` - Number of results per page (max 100) - `sort` - Sort field (prefix with `-` for descending) **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles?fields[profile]=email,first_name,last_name&page[size]=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "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 a Profile ```bash GET /klaviyo/api/profiles/{profile_id} ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Create a Profile ```bash 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" } } } } ``` **Example:** ```bash 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', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Update a Profile ```bash PATCH /klaviyo/api/profiles/{profile_id} ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'data': {'type': 'profile', 'id': '01GDDKASAP8TKDDA2GRZDSVP4H', 'attributes': {'first_name': 'Jane'}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/profiles/01GDDKASAP8TKDDA2GRZDSVP4H', data=data, method='PATCH') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Merge Profiles ```bash POST /klaviyo/api/profile-merge ``` #### Get Profile Lists ```bash GET /klaviyo/api/profiles/{profile_id}/lists ``` #### Get Profile Segments ```bash GET /klaviyo/api/profiles/{profile_id}/segments ``` ### Lists Organize subscribers into static lists. #### Get Lists ```bash GET /klaviyo/api/lists ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/klaviyo/api/lists?fields[list]=name,created,updated') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('revision', '2024-10-15') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "data": [ { "type": "list", "id": "Y6nRLr", "attributes": { "name": "Newsletter Subscribers", "created": "2024-01-15T10:30:00Z", "updated": "2024-03-01T14:22:00Z" } } ] } ``` #### Get a List ```bash GET /klaviyo/api/lists/{list_id} ``` #### Create a List ```bash POST /klaviyo/api/lists ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json