This source did not publish a separate summary. Review SKILL.md before using the skill.
SKILL.md
Customer.io Known Pitfalls
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.
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
// 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
// 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
// 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
// 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.
Why: Event names are case-sensitive. Inconsistent naming means campaign triggers only match one variant, and your event catalog becomes a mess.
Pitfall 11: No Rate Limiting
// WRONG — blasting API at full speed during import
for (const user of allUsers) {
await cio.identify(user.id, user.attrs); // 1000+ req/sec → 429 errors
}
// CORRECT — rate-limited processing
import Bottleneck from "bottleneck";
const limiter = new Bottleneck({ maxConcurrent: 10, minTime: 15 });
for (const user of allUsers) {
await limiter.schedule(() => cio.identify(user.id, user.attrs));
}
Why: Customer.io rate limits at ~100 req/sec. Without throttling, bulk operations trigger 429 errors and potentially get your API key temporarily blocked.
Pitfall 12: PII in Event Names
// WRONG — PII in event names is unsanitizable
await cio.track(userId, { name: `[email protected]` });
// CORRECT — PII only in data properties (can be deleted per GDPR)
await cio.track(userId, {
name: "email_sent",
data: { recipient: "[email protected]" },
});
Why: Event names are indexed and cached. PII in event names can't be deleted for GDPR compliance. Always put PII in event data properties.
Quick Reference
#
Pitfall
Fix
1
Wrong API key type
Track key for tracking, App key for transactional
2
Millisecond timestamps
Math.floor(Date.now() / 1000)
3
Track before identify
Always identify() first
4
Email as user ID
Use immutable database ID
5
Missing email attribute
Include email in identify()
6
Dynamic event names
Static names, dynamic data properties
7
Blocking request path
Fire-and-forget with .catch()
8
No bounce handling
Suppress bounced users via webhook
9
New client per request
Singleton pattern
10
Inconsistent event names
Always snake_case
11
No rate limiting
Use Bottleneck or p-queue
12
PII in event names
PII in data properties only
Integration Audit Script
# Quick grep audit for common pitfalls in your codebase
echo "=== Customer.io Pitfall Audit ==="
echo "--- Checking for Date.now() without /1000 ---"
grep -rn "created_at.*Date.now()" --include="*.ts" --include="*.js" \
| grep -v "/ 1000" || echo "OK"
echo "--- Checking for new TrackClient inside functions ---"
grep -rn "new TrackClient" --include="*.ts" --include="*.js" \
| grep -v "^.*const\|^.*let\|^.*export" || echo "OK"
echo "--- Checking for dynamic event names ---"
grep -rn "name:.*\`" --include="*.ts" --include="*.js" \
| grep "track\|Track" || echo "OK"
echo "--- Checking for blocking await in routes ---"
grep -rn "await.*cio\.\|await.*track\.\|await.*identify" --include="*.ts" \
| grep "router\.\|app\." || echo "Review these for fire-and-forget"
