Customerio Known PitfallsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: customerio-known-pitfalls
description: 'Identify and avoid Customer.io anti-patterns and gotchas.

  Use when reviewing integrations, onboarding developers,

  or auditing existing Customer.io code.

  Trigger: "customer.io mistakes", "customer.io anti-patterns",

  "customer.io gotchas", "customer.io pitfalls", "customer.io code review".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(npx:*), Glob, Grep
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- customer-io
- best-practices
- anti-patterns
compatibility: Designed for Claude Code
---
# 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

| Condition | Safe response |
|---|---|
| Wrong environment or recipient scope | Stop sends, correct configuration, and assess/notify under the incident process. |
| Event schema changes unexpectedly | Quarantine invalid events and version the contract before replay. |
| Consent status is uncertain | Do not message or replay until it is verified. |

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

```typescript
// 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

```typescript
// 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 thousands of years in the future. Segments using date comparisons silently break.

### Pitfall 3: Track Before Identify

```typescript
// WRONG — tracking before identifying creates orphaned events
await cio.track("new-user", { name: "signed_up", data: {} });
// User profile doesn't exist yet — event may be lost

// CORRECT — always identify first
await cio.identify("new-user", { email: "[email protected]" });
await cio.track("new-user", { name: "signed_up", data: {} });
```

**Why:** Track calls on non-existent users may be silently dropped. Always `identify()` before `track()`.

### Pitfall 4: Using Email as User ID

```typescript
// WRONG — email can change, creating duplicate profiles
await cio.identify("[email protected]", { email: "[email protected]" });
// When user changes email, old profile orphaned, new one created

// CORRECT — use immutable database ID
await cio.identify("usr_abc123", {
  email: "[email protected]",    // Email as attribute, not ID
});
```

**Why:** The first argument to `identify()` is the permanent user ID. If you use email and the user changes it, you get two profiles. Use your database primary key instead.

### Pitfall 5: Missing Email Attribute

```typescript
// WRONG — user can't receive email campaigns
await cio.identify("user-1", {
  first_name: "Jane",
  plan: "pro",
  // No email attribute!
});

// CORRECT — always include email for email campaigns
await cio.identify("user-1", {
  email: "[email protected]",
  first_name: "Jane",
  plan: "pro",
});
```

**Why:** Without an `email` attribute, the user profile exists but can't receive any email campaigns or transactional messages.

### Pitfall 6: Dynamic Event Names

```typescript
// WRONG — creates hundreds of unique event names
await cio.track("user-1", {
  name: `viewed_${productId}`,       // "viewed_SKU-12345"
  data: {},
});

// CORRECT — use a static name with data properties
await cio.track("user-1", {
  name: "product_viewed",             // Consistent, filterable
  data: { product_id: productId },    // Dynamic data in properties
});
```

**Why:** Dynamic event names pollute your event catalog and make it impossible to create campaign triggers. Use a fixed set of event names and pass variations as data properties.

### Pitfall 7: Blocking Request Path

```typescript
// WRONG — API call adds 200ms+ to every request
app.post("/api/action", async (req, res) => {
  const result = await doBusinessLogic(req.body);
  await cio.track(req.user.id, { name: "action_taken", data: {} }); // BLOCKS response
  res.json(result);
});

// CORRECT — fire-and-forget for non-critical tracking
app.post("/api/action", async (req, res) => {
  const result = await doBusinessLogic(req.body);
  cio.track(req.user.id, { name: "action_taken", data: {} })

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.