Klaviyo Multi-Environment Setup

Overview

Configure Klaviyo across development, staging, and production with separate API keys, environment detection, secret management, and production safeguards. Every environment follows the same shape — detect the env, resolve its config, load its secret, guard destructive/send operations. The lean workflow and first skeleton live here; full step-by-step code lives in references/implementation.md.

Prerequisites

• Separate Klaviyo accounts or API keys per environment
• Secret management solution (GCP Secret Manager, AWS Secrets Manager, Vault)
• klaviyo-api SDK installed

Environment Strategy

Environment	Klaviyo Account	API Key	Use Case
Development	Test account	pk_test_dev_***	Local development, exploration
Staging	Test account	pk_test_staging_***	Pre-prod validation, integration tests
Production	Production account	pk_live_***	Real customer data, live sends

Important: Klaviyo does not have a sandbox mode. Use a separate test account for dev/staging to avoid sending real emails.

Instructions

The pattern is the same across all three environments; only the API key and the per-env flags change. Read the matching section in references/implementation.md, then:

1. Write the config module — use Write/Edit to create src/config/klaviyo.ts with a detectEnvironment() helper and a per-env ENV_CONFIGS map that flips enableSending, cache, and rate-limit concurrency by environment.
2. Store secrets per environment — create one secret per env in your platform's secret store (gcloud secrets create, aws secretsmanager create-secret, or Vault). Never commit keys; local dev reads a git-ignored .env.local.
3. Add environment guards — wrap sends and deletions so non-production simply logs instead of touching real data (guardCampaignSend, guardedProfileDeletion).
4. Wire multi-env CI — a GitHub Actions matrix maps staging→staging key and main→prod key, verifies connectivity, then deploys.
5. Validate on startup — connect once, log the resolved account name, and warn loudly if a pk_live_*** key is detected outside production.

Config skeleton (first example)

// src/config/klaviyo.ts — see reference for the full ENV_CONFIGS + getSession
type Environment = 'development' | 'staging' | 'production';

function detectEnvironment(): Environment {
  const env = process.env.NODE_ENV || 'development';
  if (['production', 'staging'].includes(env)) return env as Environment;
  return 'development';
}
// development/staging force enableSending:false; only production sends.

The full config module, per-platform secret commands, guard functions, the CI matrix, and the startup validator are in references/implementation.md.

Output

• src/config/klaviyo.ts resolving a typed config per environment
• Per-environment secrets stored in GCP / AWS / Vault (never committed)
• Send + deletion guards that no-op in dev/staging and act only in production
• A GitHub Actions matrix deploying staging and production with the right key
• Startup validation that logs the connected account and flags a leaked prod key

Error Handling

Issue	Cause	Solution
Wrong key for environment	Missing env-specific secret	Verify secret per environment
Production key in dev	Key leak risk	Add startup validation warning
Sends in staging	enableSending not checked	Add campaign send guard
Config merge fails	Invalid env value	Validate NODE_ENV on startup

Examples

Block a campaign send outside production. The guard reads the resolved config and throws when sending is disabled, so a staging run can never email real customers:

guardCampaignSend();   // throws in dev/staging (enableSending:false), passes in prod

Catch a leaked production key in staging. Startup validation warns when a pk_live_*** key is present outside production:

[Klaviyo] Environment: staging
[Klaviyo] Sending enabled: false
[Klaviyo] WARNING: Production API key detected in non-production environment!

The full config module, secret-store commands for each platform, the guard implementations, the CI matrix, and the startup validator are in references/implementation.md.

Resources

• Klaviyo Authentication
• GCP Secret Manager
• AWS Secrets Manager
• 12-Factor App Config
• Full implementation walkthrough — verbatim config, secrets, guards, CI, and startup validation
• For observability setup, see the klaviyo-observability skill.