Customer.io Debug Bundle

Output

• A minimal redacted diagnostic bundle containing correlation IDs, environment, timestamps, configuration version, and status/error class.
• An incident disposition that protects recipient data and credentials while allowing reproduction or vendor escalation.

Examples

For a delivery failure, collect the opaque event/message correlation ID, workspace, timestamp, template/workflow version, and redacted status. Do not export email addresses, full payloads, tokens, or message content. Reproduce with a synthetic profile, then share only the approved redacted bundle with support.

Current State

!node --version 2>/dev/null || echo 'Node.js: not installed' !npm list customerio-node 2>/dev/null | grep customerio || echo 'customerio-node: not installed'

Overview

Collect a comprehensive debug bundle for Customer.io support tickets: API connectivity tests, user profile inspection, SDK version info, environment validation, and a structured support report.

Prerequisites

• Customer.io API credentials configured
• curl available for API tests
• User ID or email of the affected user/delivery

Instructions

Step 1: API Connectivity Diagnostic

#!/usr/bin/env bash
set -euo pipefail

echo "=== Customer.io Debug Bundle ==="
echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo ""

# 1. Check Customer.io status
echo "--- Platform Status ---"
curl -s "https://status.customer.io/api/v2/status.json" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Status: {d[\"status\"][\"description\"]}')" \
  2>/dev/null || echo "Could not reach status page"

# 2. Test Track API authentication
echo ""
echo "--- Track API Auth ---"
TRACK_RESULT=$(curl -s -o /dev/null -w "%{http_code}" \
  -u "${CUSTOMERIO_SITE_ID}:${CUSTOMERIO_TRACK_API_KEY}" \
  -X PUT "https://track.customer.io/api/v1/customers/debug-test-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{"email":"debug-test@example.com"}')
echo "Track API: HTTP ${TRACK_RESULT}"

# 3. Test App API authentication
echo ""
echo "--- App API Auth ---"
APP_RESULT=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${CUSTOMERIO_APP_API_KEY}" \
  "https://api.customer.io/v1/campaigns")
echo "App API: HTTP ${APP_RESULT}"

# 4. DNS and latency
echo ""
echo "--- Network Diagnostics ---"
for host in track.customer.io api.customer.io; do
  LATENCY=$(curl -s -o /dev/null -w "%{time_total}" "https://${host}")
  echo "${host}: ${LATENCY}s&qu

Customer.io Deploy Pipeline

Output

• A versioned, staged deployment of Customer.io configuration/code with owner approval, validation evidence, and a rollback reference.
• A protected promotion path that prevents unreviewed changes from affecting production recipients.

Examples

Validate an event/template configuration in development and staging with synthetic profiles, attach schema/template test results to the change, then release through an approved canary. If the canary shows wrong audience, consent, or rendering behavior, stop promotion and restore the last approved configuration.

Overview

Deploy Customer.io integrations to production: GCP Cloud Run with Secret Manager, Vercel serverless functions, AWS Lambda with SSM, Kubernetes with external secrets, plus health check endpoints and blue-green deployment scripts.

Prerequisites

• CI/CD pipeline configured (see customerio-ci-integration)
• Cloud platform credentials and access
• Production Customer.io credentials in a secrets manager

Instructions

Step 1: Deploy to Google Cloud Run

# .github/workflows/deploy-cloud-run.yml
name: Deploy to Cloud Run
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write  # Required for Workload Identity Federation
    steps:
      - uses: actions/checkout@v4

      - id: auth
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SA }}

      - uses: google-github-actions/setup-gcloud@v2

      - name: Build and push
        run: |
          gcloud builds submit --tag gcr.io/${{ secrets.GCP_PROJECT }}/cio-service

      - name: Deploy
        run: |
          gcloud run deploy cio-service \
            --image gcr.io/${{ secrets.GCP_PROJECT }}/cio-service \
            --region us-central1 \
            --set-secrets "CUSTOMERIO_SITE_ID=cio-site-id:latest,\
              CUSTOMERIO_TRACK_API_KEY=cio-track-key:latest,\
              CUSTOMERIO_APP_API_KEY=cio-app-key:latest" \
            --set-env-vars "CUSTOMERIO_REGION=us,NODE_ENV=production" \
            --min-instances 1 \
            --max-instances 10 \
            --memory 512Mi \
            --cpu 1 \
            --allow-unauthenticated

Step 2: Health Check Endpoint

// routes/health.ts
import { TrackClient, RegionUS } from "customerio-node";
import { Router } from "express";

const router = Router();

router.get("/health", async (_req, res) => {
  const checks: Record<string, { status: string; latency_ms?: number }> = {};

  // Check Track API
  const cio = new TrackClient(
    process.env.CUSTOMERIO_SITE_ID!,
    process.env.

Customer.io Hello World

Output

• A verified synthetic profile/event or message example in a non-production workspace.
• A minimal receipt showing environment, validation result, and cleanup without retaining recipient data.

Examples

Create a development-only profile using a synthetic identifier, submit one schema-valid event, and confirm its arrival in the development workspace. Remove the test profile or let its documented TTL expire. Never use a real customer email or production segment as a tutorial target.

Overview

Create a minimal working Customer.io integration: identify a user (create/update their profile), track an event, and send a transactional email. This covers the three fundamental Customer.io operations.

Prerequisites

• customerio-node installed (npm install customerio-node)
• CUSTOMERIO_SITE_ID and CUSTOMERIO_TRACK_API_KEY configured
• CUSTOMERIO_APP_API_KEY configured (for transactional email example)

Instructions

Step 1: Identify a User (Create/Update Profile)

// hello-customerio.ts
import { TrackClient, RegionUS } from "customerio-node";

const cio = new TrackClient(
  process.env.CUSTOMERIO_SITE_ID!,
  process.env.CUSTOMERIO_TRACK_API_KEY!,
  { region: RegionUS }
);

// identify() creates the user if they don't exist, or updates if they do.
// The first argument is your internal user ID (immutable — use DB primary key).
await cio.identify("user-123", {
  email: "hello@example.com",          // Required for email campaigns
  first_name: "Jane",
  last_name: "Doe",
  plan: "pro",
  created_at: Math.floor(Date.now() / 1000),  // Unix seconds, NOT milliseconds
});

console.log("User identified in Customer.io");

Key rules:

• id (first arg) should be your immutable database ID — never use email as ID
• email attribute is required if you want to send email campaigns
• created_at must be Unix timestamp in seconds (not ms) — Math.floor(Date.now() / 1000)
• All custom attributes are stored on the user profile and usable in segments + Liquid templates

Step 2: Track an Event

// Track a custom event on the user's activity timeline.
// Events trigger campaigns — the event name must match exactly in the dashboard.
await cio.track("user-123", {
  name: "signed_up",                   // snake_case, matches campaign trigger
  data: {
    signup_method: "google_oauth",
    referral_source: "product_hunt",
    timestamp: Math.floor(Date.now() / 1000),
  },
});

console.log("Event tracked in Customer.io");

Customer.io Install & Auth

Output

• A scoped Customer.io credential reference for the intended workspace/environment, with a verified low-impact connection test.
• A secret-management and rotation record that keeps tokens out of repositories, shell history, and logs.

Examples

Inject the development workspace credential from the approved secret manager, validate it with a low-impact read or synthetic event, and record only the environment and result. If a token is exposed, revoke it immediately and issue a replacement; do not reuse it while attempting to scrub logs.

Overview

Set up the customerio-node SDK and configure authentication for Customer.io's two API surfaces: the Track API (identify users, track events) and the App API (transactional messages, broadcasts, data queries).

Prerequisites

• Node.js 18+ with npm/pnpm
• Customer.io account at https://fly.customer.io
• Site ID + Track API Key from Settings > Workspace Settings > API & Webhook Credentials
• App API Key (bearer token) from the same page — needed for transactional messages and broadcasts

Two API Keys, Two Clients

Instructions

Step 1: Install the SDK

npm install customerio-node

The package exports TrackClient, APIClient, RegionUS, RegionEU, SendEmailRequest, and SendPushRequest.

Step 2: Configure Environment Variables

# .env — NEVER commit this file
CUSTOMERIO_SITE_ID=your-site-id-here
CUSTOMERIO_TRACK_API_KEY=your-track-api-key-here
CUSTOMERIO_APP_API_KEY=your-app-api-key-here
CUSTOMERIO_REGION=us          # "us" or "eu"

Add .env to .gitignore if not already there.

Step 3: Create the Track Client

// lib/customerio.ts
import { TrackClient, RegionUS, RegionEU } from "customerio-node";

function getRegion() {
  return process.env.CUSTOMERIO_REGION === "eu" ? RegionEU : RegionUS;
}

// Singleton — reuse across your app
let trackClient: TrackClient | null = null;

Customer.io Known Pitfalls

Prerequisites

• The intended workspace, consent/data classification, event schema, and deployment owner.
• A synthetic test profile and a redacted diagnostic process; never investigate with production recipients by default.

Instructions

1. Identify the applicable pitfall before changing an event, campaign, segment, or integration setting.
2. Validate schema, identity, consent, environment, and idempotency in development/staging.
3. Make one reversible correction and verify its effect with synthetic data before promotion.
4. Record recurring failures in reviewed runbooks/contracts rather than relying on ad hoc retries.

Output

• A documented prevention or correction for a specific delivery, data, consent, or integration pitfall.

Error Handling

Examples

Before changing a campaign trigger, send a synthetic event with an idempotency key to development, verify the expected segment and message state, then promote through approved change control. Do not test trigger fixes on live recipient cohorts.

Overview

The 12 most common Customer.io integration mistakes, with the wrong pattern, the correct pattern, and why it matters. Use this as a code review checklist and developer onboarding reference.

The Pitfall Catalog

Pitfall 1: Wrong API Key Type

// WRONG — using Track API key for transactional messages
const api = new APIClient(process.env.CUSTOMERIO_TRACK_API_KEY!);
// Gets 401 because App API uses a DIFFERENT bearer token

// CORRECT — use the App API key
const api = new APIClient(process.env.CUSTOMERIO_APP_API_KEY!);

Why: Customer.io has two separate authentication systems. Track API uses Basic Auth (Site ID + Track Key). App API uses Bearer Auth (App Key). They are not interchangeable.

Pitfall 2: Millisecond Timestamps

// WRONG — JavaScript Date.now() returns milliseconds
await cio.identify("user-1", {
  created_at: Date.now(),           // 1704067200000 → year 55976
});

// CORRECT — Customer.io expects Unix seconds
await cio.identify("user-1", {
  created_at: Math.floor(Date.now() / 1000),  // 1704067200
});

Why: Customer.io accepts millisecond values without error but interprets them as seconds, resulting in dates th

Customer.io Local Dev Loop

Output

• A small, test-backed local change using a non-production workspace and synthetic recipient data.
• A reviewed deployment/revert path that preserves production campaigns, consent, and contact data.

Examples

Use a development workspace and a synthetic profile such as test-user-001; validate the event schema locally, run the focused test, and inspect the resulting campaign behavior before committing. Never point local experiments at production segments or use real recipient data to debug a template.

Overview

Set up an efficient local development workflow for Customer.io: environment isolation via separate workspaces, a dry-run client for safe development, test mocks for unit tests, and prefixed events that never pollute production data.

Prerequisites

• customerio-node installed
• Separate Customer.io workspace for development (recommended — free workspaces available)
• dotenv or similar for environment variable loading

Instructions

Step 1: Environment Configuration

# .env.development
CUSTOMERIO_SITE_ID=dev-site-id
CUSTOMERIO_TRACK_API_KEY=dev-track-key
CUSTOMERIO_APP_API_KEY=dev-app-key
CUSTOMERIO_REGION=us
CUSTOMERIO_DRY_RUN=false
CUSTOMERIO_EVENT_PREFIX=dev_

# .env.test
CUSTOMERIO_SITE_ID=not-needed
CUSTOMERIO_TRACK_API_KEY=not-needed
CUSTOMERIO_APP_API_KEY=not-needed
CUSTOMERIO_DRY_RUN=true
CUSTOMERIO_EVENT_PREFIX=test_

Step 2: Environment-Aware Client

// lib/customerio-dev.ts
import { TrackClient, APIClient, RegionUS, RegionEU } from "customerio-node";

interface CioConfig {
  siteId: string;
  trackApiKey: string;
  appApiKey: string;
  region: typeof RegionUS | typeof RegionEU;
  dryRun: boolean;
  eventPrefix: string;
}

function loadConfig(): CioConfig {
  return {
    siteId: process.env.CUSTOMERIO_SITE_ID ?? "",
    trackApiKey: process.env.CUSTOMERIO_TRACK_API_KEY ?? "",
    appApiKey: process.env.CUSTOMERIO_APP_API_KEY ?? "",
    region: process.env.CUSTOMERIO_REGION === "eu" ? RegionEU : RegionUS,
    dryRun: process.env.CUSTOMERIO_DRY_RUN === "true",
    eventPrefix: process.env.CUSTOMERIO_EVENT_PREFIX ?? "",
  };
}

export class DevTrackClient {
  private client: TrackClient | null = null;
  private config: CioConfig;
  private log: typeof console.log;

  constructor() {
    this.config = loadConfig();
    this.log = console.log.bind(console);
    if (!this.config.dryRun) {
      this.client = new TrackClient(
        this.config.siteId,
        this.config.trackApiKey,
        { region: this.config.region }
      );
    }
  }

  async identify(userId: string, attributes: Record<string, any>) {
    const prefixedId = `${this.config.eventPrefix}${userId}`;
    if (this.

Customer.io Multi-Environment Setup

Output

• Isolated development, staging, and production workspaces with separate scoped credentials, segments, and delivery controls.
• A promotion receipt with synthetic validation, owner approval, and a rollback path that avoids production-recipient experiments.

Examples

Promote a campaign template by validating it against synthetic profiles in development, then staging, while keeping production workspace identifiers and secrets distinct. If staging delivery or consent checks fail, stop promotion and restore the previous approved template rather than editing the production campaign in place.

Overview

Configure isolated Customer.io environments for dev, staging, and production: separate workspaces per environment, typed configuration with validation, environment-aware client wrappers, Kubernetes ConfigMap overlays, and data isolation verification.

Prerequisites

• Customer.io account with multiple workspaces (create at fly.customer.io)
• Environment variable management (dotenv, secrets manager)
• CI/CD pipeline for per-environment deployment

Workspace Strategy

Each workspace has its own Site ID, Track API Key, and App API Key. Create workspaces at Settings > Workspace Settings.

Instructions

Step 1: Typed Environment Configuration

// config/customerio.ts
import { RegionUS, RegionEU } from "customerio-node";

type CioEnvironment = "development" | "ci" | "staging" | "production";

interface CioEnvConfig {
  siteId: string;
  trackApiKey: string;
  appApiKey: string;
  region: typeof RegionUS | typeof RegionEU;
  dryRun: boolean;
  logLevel: "debug" | "info" | "warn" | "error";
  eventPrefix: string;     // Prefix events in non-prod to prevent confusion
}

function validateConfig(config: CioEnvConfig, env: CioEnvironment): void {
  if (!config.siteId) throw new Error(`Missing CUSTOMERIO_SITE_ID for ${env}`);
  if (!config.trackApiKey) throw new Error(`Missing CUSTOMERIO_TRACK_API_KEY for ${env}`);
  if (env === "production" && config.dryRun) {
    throw new Er

Customer.io Observability

Output

• Bounded metrics and redacted traces for event acceptance, campaign delivery, errors, latency, and rate-limit headroom.
• An owned alert/runbook path for delivery, authentication, data-quality, and provider incidents.

Examples

Emit an aggregate counter for accepted events and failures by environment and endpoint, never by email address, customer ID, message body, API key, or full payload. Trigger a staging alert with a harmless test event, verify the on-call route, then restore the normal state and record the alert receipt.

Overview

Implement comprehensive observability for Customer.io integrations: Prometheus metrics (latency, error rates, delivery funnel), structured JSON logging with PII redaction, OpenTelemetry tracing, and Grafana dashboard definitions.

Prerequisites

• Customer.io integration deployed
• Prometheus + Grafana (or compatible metrics stack)
• Structured logging system (pino recommended)

Key Metrics to Track

Instructions

Step 1: Prometheus Metrics

// lib/customerio-metrics.ts
import { Counter, Histogram, Gauge, Registry } from "prom-client";

const registry = new Registry();

export const cioMetrics = {
  apiDuration: new Histogram({
    name: "cio_api_duration_ms",
    help: "Customer.io API call duration in milliseconds",
    labelNames: ["operation", "status"] as const,
    buckets: [10, 25, 50, 100, 250, 500, 1000, 2500, 5000],
    registers: [registry],
  }),

  apiRequests: new Counter({
    name: "cio_api_requests_total",
    help: "Total Customer.io API requests",
    labelNames: ["operation"] as const,
    

Customer.io Performance Tuning

Output

• A measured delivery/API performance baseline with a scoped optimization, owner, and rollback trigger.
• A capacity decision that preserves consent, message correctness, rate limits, and provider reliability.

Examples

Measure event throughput, response latency, error rate, and queue depth in a development workspace using synthetic payloads. Change one batch/concurrency parameter, compare against the baseline, and revert if errors, rate limits, or message ordering regress. Do not increase concurrency by replaying production recipient data.

Overview

Optimize Customer.io API performance for high-volume integrations: HTTP connection pooling, identify deduplication caching, event batching with flush control, fire-and-forget async tracking, and regional routing.

Prerequisites

• Working Customer.io integration
• Understanding of your traffic patterns and volume
• Monitoring to measure improvement (see customerio-observability)

Performance Targets

Instructions

Step 1: HTTP Connection Pooling

// lib/customerio-pooled.ts
import { TrackClient, RegionUS } from "customerio-node";
import https from "https";

// The customerio-node SDK creates new connections by default.
// Reuse connections with a keep-alive agent.
const agent = new https.Agent({
  keepAlive: true,
  maxSockets: 25,        // Max concurrent connections
  maxFreeSockets: 10,    // Keep idle connections open
  timeout: 30000,        // 30s socket timeout
  keepAliveMsecs: 15000, // TCP keep-alive probe interval
});

// Apply to the SDK by creating a singleton with the agent
// Note: customerio-node doesn't directly accept an agent,
// but we configure Node.js global agent for HTTPS
https.globalAgent = agent;

// Singleton client — one instance = one connection pool
const cio = new TrackClient(
  process.env.CUSTOMERIO_SITE_ID!,
  process.env.CUSTOMERIO_TRACK_API_KEY!,
  { region: RegionUS }
);

export { cio };

Step 2: Identify Deduplication Cache

// lib/customerio-dedup.ts
// Skip duplicate identify() calls within a time window

class LRUCache<K, V> {
  private map = new Map<K, 

Customer.io Primary Workflow

Output

• A consent-aware workflow with explicit trigger, audience, data contract, message/template version, and owner.
• A synthetic validation receipt and a scoped rollback/disable action for unexpected delivery behavior.

Examples

Build the workflow in development using one synthetic profile and a versioned event, confirm trigger conditions and suppression/consent rules, then promote through staging. Enable production through an approved canary audience; pause/disable the workflow if the audience or message behavior does not match the reviewed expectation.

Overview

Implement Customer.io's core messaging workflow: identify users with segment-ready attributes, track lifecycle events that trigger campaigns, and set up the data layer for automated onboarding, nurture, and re-engagement sequences.

Prerequisites

• customerio-node configured with Track API credentials
• Campaigns created in Customer.io dashboard (triggered by events you define)
• Understanding of your user lifecycle stages

How Campaigns Work

Your App (SDK)           Customer.io Dashboard          User
─────────────           ────────────────────          ────
cio.identify(user)  →   Profile created/updated
cio.track("signed_up")  →   Campaign trigger fires
                             Wait 1 day             →   Welcome email
                             Check: verified?
                             ├─ No                  →   Verification reminder
                             └─ Yes → Wait 3 days   →   Feature tips email

Events tracked via the SDK trigger campaigns you build in the dashboard. The SDK sends the data; the dashboard defines the workflow logic.

Instructions

Step 1: Define Your Event Taxonomy

// lib/customerio-events.ts
import { TrackClient, RegionUS } from "customerio-node";

// Central event definitions — every event your app tracks
export const CIO_EVENTS = {
  // Onboarding
  SIGNED_UP: "signed_up",
  EMAIL_VERIFIED: "email_verified",
  PROFILE_COMPLETED: "profile_completed",
  FIRST_PROJECT_CREATED: "first_project_created",

  // Engagement
  FEATURE_USED: "feature_used",
  INVITED_TEAMMATE: "invited_teammate",
  UPGRADE_STARTED: "upgrade_started",
  UPGRADE_COMPLETED: "upgrade_completed",

  // Lifecycle
  SUBSCRIPTION_RENEWED: "subscription_renewed",
  SUBSCRIPTION_CANCELLED: "subscription_cancelled",
  TRIAL_EXPIRING: "trial_expiring",

  // Commerce
  CHECKOUT_STARTED: "checkout_started",
  CHECKOUT_COMPLETED: "checkout_completed",
  REFUND_REQUESTED: "refund_requested",
} as const;

type EventName = (typeof CIO_EVENTS)[key

Customer.io Production Checklist

Instructions

1. Complete every production gate with an evidence link: workspace/environment, identity, secret scope, consent, event/schema, template review, observability, rate limits, and rollback.
2. Verify the exact production audience and suppression/consent behavior using approved safe checks.
3. Hold release when any data, identity, delivery, or owner gate is unverified.
4. Record the named go/no-go decision and post-deployment observation result.

Output

• A production-readiness receipt with owners, evidence, exceptions, and tested rollback path.

Examples

Before enabling a campaign, validate it in staging with synthetic profiles, confirm the production segment and consent/suppression logic under review, and use an approved canary audience. If the canary differs from expected behavior, stop the launch and restore the previous version rather than widening sends.

Overview

Comprehensive go-live checklist for Customer.io integrations: credentials audit, integration quality review, email deliverability setup, monitoring configuration, smoke tests, and staged rollout plan.

Prerequisites

• Customer.io integration complete and tested in staging
• Production workspace credentials ready
• Sending domain configured and verified

Production Checklist

1. Credentials & Configuration

2. Integration Quality

// scripts/prod-audit.ts
import { TrackClient, RegionUS } from "customerio-node";

async function auditIntegration() {
  const checks: { name: string; pass: boolean; detail: string }[] = [];

  // Check 1: Credentials exist
  const siteId = process.env.CUSTOMERIO_SITE_ID;
  const trackKey = process.env.CUSTOMERIO_TRACK_API_KEY;
  const appKey = process.env.CUSTOMERIO_APP_API_KEY;
  checks.push({
    name: "Track credentials",
    pass: !!(siteId && trackKey),
    detail: siteId ? `Site ID: ${siteId.substring(0, 4)}...` : "MISSING",
  });
  checks.push({

Customer.io Rate Limits

Prerequisites

• Current provider limit documentation/plan, a measured baseline, idempotency design, and a named capacity owner.
• Synthetic test payloads and alerting for 429s, queue age, delivery failure, and duplicate-event risk.

Output

• A rate-aware client/workflow configuration with bounded concurrency, backoff, idempotency, monitoring, and a safe replay decision path.
• An aggregate load-test or incident receipt showing limit behavior without recipient payloads.

Examples

Send synthetic events at gradually increasing concurrency below the approved limit, record 429s and queue age, and apply exponential backoff with jitter using a stable idempotency key. If throttling occurs, reduce concurrency and allow recovery; do not retry every failed event immediately or widen sends to compensate.

Overview

Understand Customer.io's API rate limits and implement proper throttling: token bucket limiters, exponential backoff with jitter, queue-based processing, and 429 response handling.

Rate Limit Reference

These are approximate. Customer.io uses sliding window rate limiting. When exceeded, you get a 429 Too Many Requests response.

Instructions

Step 1: Token Bucket Rate Limiter

// lib/rate-limiter.ts
export class TokenBucket {
  private tokens: number;
  private lastRefill: number;

  constructor(
    private readonly maxTokens: number = 80,  // Stay under 100/sec limit
    private readonly refillRate: number = 80   // Tokens per second
  ) {
    this.tokens = maxTokens;
    this.lastRefill = Date.now();
  }

  private refill(): void {
    const now = Date.now();
    const elapsed = (now - this.lastRefill) / 1000;
    this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.refillRate);
    this.lastRefill = now;
  }

  async acquire(): Promise<void> {
    this.refill();
    if (this.tokens >= 1) {
      this.tokens -= 1;
      return;
    }
    // Wait until a token is available
    const waitMs = ((1 - this.tokens) / this.refillRate) * 1000;
    await new Promise((r) => setTimeout(r, Math.ceil(waitMs)));
    this.tokens = 0;
    this.lastRefill = Date.now();
  }
}

Step 2: Exponential Backoff with Jitter

                

                  
                    
                  
                  customerio-reference-architecture
                  View full skill →
                
                

                  
Implement Customer.
                  

                      ReadWriteEditBash(npm:*)Bash(npx:*)GlobGrep
                    
                
                

                  
Customer.io Reference Architecture
Prerequisites

A data-flow owner, approved workspace/environment boundaries, event contract, consent model, and incident/support route.
Repository/configuration review for any change to credentials, webhooks, message templates, or customer-data processing.

Output

A documented architecture mapping event producers, identity/consent, Customer.io workspaces, observability, ownership, and failure handling.
Clear trust boundaries and reversible integration points for delivery, replay, and incident response.

Examples
Document a producer that validates and idempotently emits a versioned event to the development workspace, with a consent gate before campaign entry and redacted metrics by environment. Promote the same contract through staging before production, retain a dead-letter/replay owner, and keep recipient identifiers and tokens outside logs and diagrams.
Overview
Enterprise-grade reference architecture for Customer.io: a service layer separating Track and App API concerns, event-driven processing with message queues, repository pattern for user-to-CIO sync, webhook event bus, and infrastructure as code.
Architecture Principles

Two Clients, Two Concerns — TrackClient for behavioral data in, APIClient for messages out
Event-Driven — Message queues decouple your app from Customer.io API availability
Idempotent Operations — All writes safely retryable via content hashing
Service Layer — Business logic never calls Customer.io SDK directly
Observability — Every operation emits timing and error metrics

Architecture Diagram

┌─────────────┐    ┌───────────────────┐    ┌──────────────┐
│ Application │───>│ MessagingService  │───>│ Track API    │
│ Routes      │    │ (service layer)   │    │ identify()   │
└─────────────┘    │                   │    │ track()      │
                   │ - identify users  │    └──────────────┘
                   │ - track events    │
                   │ - send txn emails │    ┌──────────────┐
                   │                   │───>│ App API      │
                   └───────────────────┘    │ sendEmail()  │
                          │                 │ broadcast()  │
                          │                 └──────────────┘
                          v
                   ┌───────────────────┐
                   │ Event Queue       │    ┌──────────────┐
                   │ (Redis/Kafka)     │───>│ DLQ          │
                   │ for reliability   │    │ (failures)   │
                   └───────────────────┘    └──────────────┘

┌─────────────┐    ┌───────────────────┐    ┌──────────────┐
│ Customer.io │───>│ Webhook Handler   │───>│ BigQuery     │
│ Webh