thatrebeccarae/claude-marketing / skills/klaviyo-analyst
klaviyo-analyst
VerifiedKlaviyo marketing operations and analyst expertise. Audit flows, segments, campaigns, deliverability, and revenue attribution. Use when the user asks about Klaviyo marketing strategy, email/SMS automation, customer segmentation, flow optimization, or lifecycle marketing. For API integration, SDK, webhook, or developer questions, see the klaviyo-developer skill.
| File | Kind | Size |
|---|---|---|
| .env.example | other | 757 B |
| EXAMPLES.md | markdown | 12.0 KB |
| LICENSE | other | 1.0 KB |
| REFERENCE.md | markdown | 19.3 KB |
| SKILL.md | skill md | 19.7 KB |
| requirements.txt | manifest | 141 B |
| scripts/analyze.py | script | 32.9 KB |
| scripts/klaviyo_client.py | script | 15.6 KB |
scripts/klaviyo_client.py
View on GitHub#!/usr/bin/env python3
"""
Klaviyo Analytics API Client
Read-only SDK wrapper for fetching Klaviyo marketing data including
flows, campaigns, segments, lists, metrics, and performance reports.
Usage:
python klaviyo_client.py --resource flows
python klaviyo_client.py --resource campaigns --format table
python klaviyo_client.py --resource report --report-type flow --id FLOW_ID
python klaviyo_client.py --resource metrics --format json --output metrics.json
Environment Variables:
KLAVIYO_API_KEY: Klaviyo private API key (required, starts with "pk_")
"""
import os
import sys
import json
import argparse
import traceback
from typing import Dict, List, Optional
try:
from klaviyo_api import KlaviyoAPI
from dotenv import load_dotenv
except ImportError:
print("Error: Required packages not installed.", file=sys.stderr)
print("Install with: pip install klaviyo-api python-dotenv", file=sys.stderr)
sys.exit(1)
def _safe_output_path(path: str) -> str:
"""Validate output path does not escape working directory."""
resolved = os.path.realpath(path)
cwd = os.path.realpath(os.getcwd())
if not resolved.startswith(cwd + os.sep) and resolved != cwd:
raise ValueError(f"Output path must be within working directory: {cwd}")
return resolved
class KlaviyoAnalyticsClient:
"""Read-only client for fetching Klaviyo marketing analytics data."""
API_REVISION = "2025-10-15"
def __init__(self):
"""Initialize the client with credentials from environment."""
load_dotenv()
api_key = os.environ.get("KLAVIYO_API_KEY")
if not api_key:
raise ValueError(
"KLAVIYO_API_KEY environment variable not set. "
"Find your API key in Klaviyo: Settings > Account > API Keys"
)
if not api_key.startswith("pk_"):
raise ValueError(
"KLAVIYO_API_KEY should start with 'pk_'. "
"Use a Private API Key, not a Public API Key."
)
try:
self.client = KlaviyoAPI(api_key, max_delay=60, max_retries=3)
except Exception as e:
print(f" caused by: {type(e).__name__}: {e}", file=sys.stderr)
raise RuntimeError("Failed to initialize Klaviyo client. Check your API key.") from e
self._conversion_metric_id: Optional[str] = None
self._flow_report_cache: Dict[str, Dict] = {}
self._campaign_report_cache: Dict[str, Dict] = {}
def _get_conversion_metric_id(self, name: str = "Placed Order") -> str:
"""Resolve a metric name to its Klaviyo metric ID. Cached after first call."""
if self._conversion_metric_id:
return self._conversion_metric_id
metrics = self.get_metrics()
for m in metrics:
if m.get("name") == name:
self._conversion_metric_id = m.get("id")
return self._conversion_metric_id
raise RuntimeError(
f"Conversion metric '{name}' not found in account. "
f"Reporting calls require an alphanumeric metric ID, not a name."
)
def get_flows(self, filter_str: Optional[str] = None) -> List[Dict]:
"""
List all flows with status and trigger information.
Args:
filter_str: Optional filter (e.g., 'equals(status,"live")')
Returns:
List of flow dictionaries with id, name, status, trigger_type
"""
try:
kwargs = {}
if filter_str:
kwargs["filter"] = filter_str
response = self.client.Flows.get_flows(**kwargs)
return self._parse_jsonapi_response(response)
except Exception as e:
print(f" caused by: {type(e).__name__}: {e}", file=sys.stderr)
raise RuntimeError("Failed to fetch flows. Check API key scopes.") from e
def get_campaigns(self, filter_str: Optional[str] = None) -> List[Dict]:
"""
List campaigns with send status and performance summary.
Args:
filter_str: Optional filter (e.g., 'equals(messages.channel,"email")')
Returns:
List of campaign dictionaries
"""
try:
# Klaviyo API requires a filter on messages.channel; default to email.
kwargs = {"filter": filter_str or 'equals(messages.channel,"email")'}
response = self.client.Campaigns.get_campaigns(**kwargs)
return self._parse_jsonapi_response(response)
except Exception as e:
print(f" caused by: {type(e).__name__}: {e}", file=sys.stderr)
raise RuntimeError("Failed to fetch campaigns. Check API key scopes.") from e
def get_segments(self) -> List[Dict]:
"""
List all segments.
Returns:
List of segment dictionaries with id, name, and profile count
"""
try:
response = self.client.Segments.get_segments()
return self._parse_jsonapi_response(response)
except Exception as e:
print(f" caused by: {type(e).__name__}: {e}", file=sys.stderr)
raise RuntimeError("Failed to fetch segments. Check API key scopes.") from e
def get_lists(self) -> List[Dict]:
"""
List all lists.
Returns:
List of list dictionaries with id, name, and profile count
"""
try:
response = self.client.Lists.get_lists()
return self._parse_jsonapi_response(response)
except Exception as e:
print(f" caused by: {type(e).__name__}: {e}", file=sys.stderr)
raise RuntimeError("Failed to fetch lists. Check API key scopes.") from e
def get_flow_report(self, flow_id: str) -> Dict:
"""
Get performance metrics for a specific flow.
Args:
flow_id: The flow ID to get a report for
Returns:
Dictionary with flow performance metrics
"""
if flow_id in self._flow_report_cache:
return self._flow_report_cache[flow_id]
try:
body = {
"data": {
"type": "flow-values-report",
"attributes": {
"statistics": [
"opens",
"opens_unique",
"clicks",
"clicks_unique",
"recipients",
"delivered",
"bounced",
"unsubscribes",
"spam_complaints",
"conversion_value",
],
"timeframe": {"key": "last_365_days"},
"conversion_metric_id": self._get_conversion_metric_id(),
"filter": f"equals(flow_id,\"{flow_id}\")",
},
}
}
response = self.client.Reporting.query_flow_values(body)
parsed = self._parse_jsonapi_response(response)
results = parsed.get("results") if isinstance(parsed, dict) else None
stats = results[0].get("statistics", {}) if results else {}
self._flow_report_cache[flow_id] = stats
return stats
except Exception as e:
print(f" caused by: {type(e).__name__}: {e}", file=sys.stderr)
raise RuntimeError(f"Failed to fetch flow report for {flow_id}.") from e
def get_campaign_report(self, campaign_id: str) -> Dict:
"""
Get performance metrics for a specific campaign.
Args:
campaign_id: The campaign ID to get a report for
Returns:
Dictionary with campaign performance metrics
"""
if campaign_id in self._campaign_report_cache:
return self._campaign_report_cache[campaign_id]
try:
body = {
"data": {
"type": "campaign-values-report",
"attributes": {
"statistics": [
"opens",
"opens_unique",
"clicks",
"clicks_unique",
"recipients",
"delivered",
"bounced",
"unsubscribes",
"spam_complaints",
"conversion_value",
],
"timeframe": {"key": "last_365_days"},
"conversion_metric_id": self._get_conversion_metric_id(),
"filter": f"equals(campaign_id,\"{campaign_id}\")",
},
}
}
response = self.client.Reporting.query_campaign_values(body)
parsed = self._parse_jsonapi_response(response)
results = parsed.get("results") if isinstance(parsed, dict) else None
stats = results[0].get("statistics", {}) if results else {}
self._campaign_report_cache[campaign_id] = stats
return stats
except Exception as e:
print(f" caused by: {type(e).__name__}: {e}", file=sys.stderr)
raise RuntimeError(
f"Failed to fetch campaign report for {campaign_id}."
) from e
def get_metrics(self) -> List[Dict]:
"""
List all available event types (metrics).
Returns:
List of metric dictionaries with id and name
"""
try:
response = self.client.Metrics.get_metrics()
return self._parse_jsonapi_response(response)
except Exception as e:
print(f" caused by: {type(e).__name__}: {e}", file=sys.stderr)
raise RuntimeError("Failed to fetch metrics. Check API key scopes.") from e
def _parse_jsonapi_response(self, response) -> List[Dict]:
"""
Flatten JSON:API envelope into simple dictionaries.
Args:
response: SDK response object
Returns:
List of flattened dictionaries or a single dictionary
"""
if hasattr(response, "to_dict"):
response = response.to_dict()
elif isinstance(response, str):
response = json.loads(response)
data = response.get("data", response)
if isinstance(data, list):
return [self._flatten_resource(item) for item in data]
elif isinstance(data, dict):
return self._flatten_resource(data)
else:
return data
def _flatten_resource(self, resource: Dict) -> Dict:
"""Flatten a single JSON:API resource object."""
flat = {
"id": resource.get("id"),
"type": resource.get("type"),
}
attributes = resource.get("attributes", {})
if attributes:
flat.update(attributes)
return flat
def format_as_table(data, resource_type: str) -> str:
"""Format result as a human-readable table."""
if not data:
return "No data found."
if isinstance(data, dict):
data = [data]
# Select columns based on resource type
column_map = {
"flows": ["id", "name", "status", "trigger_type"],
"campaigns": ["id", "name", "status", "send_strategy"],
"segments": ["id", "name"],
"lists": ["id", "name"],
"metrics": ["id", "name"],
"report": None,
}
columns = column_map.get(resource_type)
if columns is None:
return json.dumps(data, indent=2, default=str)
# Filter to available columns
available_cols = [c for c in columns if any(c in item for item in data)]
if not available_cols:
available_cols = list(data[0].keys())[:5]
# Build header
lines = []
header = " | ".join(col.replace("_", " ").title() for col in available_cols)
lines.append(header)
lines.append("-" * len(header))
# Build rows
for item in data:
values = [str(item.get(col, "")) for col in available_cols]
lines.append(" | ".join(values))
lines.append("")
lines.append(f"Total: {len(data)} {resource_type}")
return "\n".join(lines)
def main():
parser = argparse.ArgumentParser(
description="Fetch Klaviyo analytics data",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
Examples:
# List all flows
python klaviyo_client.py --resource flows
# List only live flows
python klaviyo_client.py --resource flows --filter 'equals(status,"live")'
# Get campaign report
python klaviyo_client.py --resource report --report-type campaign --id CAMPAIGN_ID
# List segments as table
python klaviyo_client.py --resource segments --format table
# Export metrics to file
python klaviyo_client.py --resource metrics --output metrics.json
""",
)
parser.add_argument(
"--resource",
required=True,
choices=["flows", "campaigns", "segments", "lists", "metrics", "report"],
help="Resource type to fetch",
)
parser.add_argument(
"--report-type",
choices=["flow", "campaign"],
help="Report type (required when --resource report)",
)
parser.add_argument(
"--id",
help="Resource ID (required for report)",
)
parser.add_argument(
"--filter",
help="API filter expression (e.g., 'equals(status,\"live\")')",
)
parser.add_argument(
"--format",
choices=["json", "table"],
default="json",
help="Output format (default: json)",
)
parser.add_argument(
"--output",
help="Output file path (default: stdout)",
)
parser.add_argument(
"--debug",
action="store_true",
help="Re-raise exceptions with full traceback instead of friendly error",
)
args = parser.parse_args()
# Validate report arguments
if args.resource == "report":
if not args.report_type:
parser.error("--report-type is required when --resource is 'report'")
if not args.id:
parser.error("--id is required when --resource is 'report'")
try:
client = KlaviyoAnalyticsClient()
# Fetch data
if args.resource == "flows":
result = client.get_flows(filter_str=args.filter)
elif args.resource == "campaigns":
result = client.get_campaigns(filter_str=args.filter)
elif args.resource == "segments":
result = client.get_segments()
elif args.resource == "lists":
result = client.get_lists()
elif args.resource == "metrics":
result = client.get_metrics()
elif args.resource == "report":
if args.report_type == "flow":
result = client.get_flow_report(args.id)
else:
result = client.get_campaign_report(args.id)
# Format output
if args.format == "json":
output = json.dumps(result, indent=2, default=str)
else:
output = format_as_table(result, args.resource)
# Write output
if args.output:
safe_path = _safe_output_path(args.output)
with open(safe_path, "w", encoding="utf-8") as f:
f.write(output)
print(f"Data saved to {args.output}", file=sys.stderr)
else:
print(output)
except ValueError as e:
print(f"Error: {e}", file=sys.stderr)
sys.exit(1)
except Exception:
if args.debug:
traceback.print_exc()
else:
print("Error: Operation failed. Check your API key and network connection.", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |