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

> 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.

1. 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.

1. Add environment guards — wrap sends and deletions so non-production simply

logs instead of touching real data (guardCampaignSend, guardedProfileDeletion).

1. Wire multi-env CI — a GitHub Actions matrix maps staging→staging key and

main→prod key, verifies connectivity, then deploys.

1. Validate on startup — connect once, log the resolved account name, and warn

loudly if a pklive*** 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

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

pklive*** 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.