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:
- 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.
- 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.
- Add environment guards — wrap sends and deletions so non-production simply
logs instead of touching real data (
guardCampaignSend, guardedProfileDeletion).
- Wire multi-env CI — a GitHub Actions matrix maps
staging→staging key and
main→prod key, verifies connectivity, then deploys.
- 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)
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';
}
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();
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
