Customerio Known Pitfalls

What it does

When your agent uses it

• Reviewing integrations
• Onboarding developers
• Auditing existing Customer.io code

Example prompts

• “customer.io mistakes”
• “customer.io anti-patterns”
• “customer.io gotchas”
• “/customerio-known-pitfalls”

Requirements

• A credential in CUSTOMERIO_TRACK_API_KEY
• A credential in CUSTOMERIO_APP_API_KEY
• Compatibility (from SKILL.md): Designed for Claude Code
• Pre-approved tools (allowed-tools): Read, Write, Edit, Bash(npm:*), Bash(npx:*), Glob, Grep

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

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

What it can do on your machine

Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Write
  • Edit
  • Bash(npm:*)
  • Bash(npx:*)
  • Glob
  • Grep

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are typescript and bash).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • docs.customer.io
  • github.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • CUSTOMERIO_TRACK_API_KEY
  • CUSTOMERIO_APP_API_KEY

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Designed for Claude Code

  From compatibility in the SKILL.md frontmatter.

Context cost

Customerio Known Pitfalls loads about 2.8k tokens when it runs, and up to ~5.5k if it reads all its reference files. Until then it costs about 79 tokens; SKILL.md has 664 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~79

When it runs · the whole SKILL.md, loaded when a task matches

~2.8k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~5.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 664 words, ~2,751 tokens.

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

compatibility

Designed for Claude Code

version

1.14.0

license

MIT

author

Jeremy Longshore <jeremy@intentsolutions.io>

tags

saas, customer-io, best-practices, anti-patterns

// 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!);

// 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
});

// 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: "user@example.com" });
await cio.track("new-user", { name: "signed_up", data: {} });

// WRONG — email can change, creating duplicate profiles
await cio.identify("user@example.com", { email: "user@example.com" });
// When user changes email, old profile orphaned, new one created

// CORRECT — use immutable database ID
await cio.identify("usr_abc123", {
  email: "user@example.com",    // Email as attribute, not ID
});

// 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: "jane@example.com",
  first_name: "Jane",
  plan: "pro",
});

// 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
});

// 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: {} })
    .catch((err) => console.error("CIO track failed:", err.message));
  res.json(result);  // Returns immediately
});

// WRONG — keep sending to bounced addresses, damaging sender reputation
// (No webhook handler for bounces)

// CORRECT — suppress users who bounce
async function handleBounceWebhook(event: { customer_id: string }) {
  await cio.suppress(event.customer_id);
  console.warn(`Suppressed bounced user: ${event.customer_id}`);
}

// WRONG — creates a new TCP connection for every API call
app.post("/track", async (req, res) => {
  const cio = new TrackClient(siteId, apiKey, { region: RegionUS });
  await cio.track(req.body.userId, req.body.event);
  res.sendStatus(200);
});

// CORRECT — singleton, created once
const cio = new TrackClient(siteId, apiKey, { region: RegionUS });

app.post("/track", async (req, res) => {
  await cio.track(req.body.userId, req.body.event);
  res.sendStatus(200);
});

// WRONG — multiple naming conventions
await cio.track(userId, { name: "UserSignedUp" });      // PascalCase
await cio.track(userId, { name: "user-signed-up" });     // kebab-case
await cio.track(userId, { name: "user signed up" });     // spaces

// CORRECT — consistent snake_case everywhere
await cio.track(userId, { name: "user_signed_up" });

// 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));
}

// WRONG — PII in event names is unsanitizable
await cio.track(userId, { name: `email_sent_to_john@example.com` });

// CORRECT — PII only in data properties (can be deleted per GDPR)
await cio.track(userId, {
  name: "email_sent",
  data: { recipient: "john@example.com" },
});

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

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in skills/.curated/customerio-known-pitfalls of jeremylongshore/tons-of-skills-marketplace.

• SKILL.md
• references/implementation-guide.md
• references/implementation.md

Open the folder on GitHubat commit cfae287