Customer.io

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of Customer.io for test suites, serving all three hosts our code talks to from one process: the Segment-compatible CDP (identify, track, batch, exactly as @customerio/cdp-analytics-node posts them), the App API transactional sends (email, SMS, inbox message), message catalog, profile attribute reads, sender opt-out reconciliation, and delivery-status reads, and the link-tracking click endpoint. Sends land in an outbox a suite asserts on (and reads links out of); reporting events (unsubscribed, subscribed, spammed, subscription preferences, clicked) are posted to our reporting webhook, signed the way Customer.io signs them.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from Customer.io's CDP (Segment spec) and App API references, trimmed to what our consumers send.

#Install

npm install -D @crvouga/mockingbird-service-customerio

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-customerio serve, createServer from ./server (Node), or createRuntime with any Fetch server.

#Usage

The app hardcodes Customer.io's hosts per region (customer-io.config.ts, seam G-Y1): once they are env-driven, point the CDP host (the SDK's host), the App API host and the link tracking domain at the emulator. Customer.io only runs when CUSTOMERIO_RUNTIME_ENABLED is on and the stage is in CUSTOMERIO_ALLOWED_STAGES.

npx mockingbird-customerio serve --port 8810 \
  --webhook-url http://127.0.0.1:3000/v1/customer-io/reporting-webhook \
  --webhook-secret "$CUSTOMERIO_REPORTING_WEBHOOK_SIGNING_KEY"

import { Analytics } from "@customerio/cdp-analytics-node"
import { createServer } from "@crvouga/mockingbird-service-customerio/server"

const cio = await createServer({
  webhooks: { url: "http://127.0.0.1:3000/v1/customer-io/reporting-webhook", secret: "k".repeat(32) },
})

// The application's CDP client. Only its host changes.
const analytics = new Analytics({ writeKey: "wk", host: cio.url, maxEventsInBatch: 1 })
analytics.identify({ userId: "42", traits: { email: "ada@example.com" } })
await analytics.closeAndFlush()

// Test control. The member unsubscribes in Customer.io: the signed reporting event reaches the backend.
await fetch(`${cio.url}/__admin/reporting-events`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ metric: "unsubscribed", userId: "42", objectType: "customer" }),
})
await cio.close()

Transactional sends go through the App API client (customerio-node), pointed at the same emulator. The test then reads back what the app sent:

import { Analytics } from "@customerio/cdp-analytics-node"
import { APIClient, SendEmailRequest } from "customerio-node"
import { createServer } from "@crvouga/mockingbird-service-customerio/server"

const cio = await createServer()

// The application's clients. Only the CDP host and the App API url change.
const analytics = new Analytics({ writeKey: "wk", host: cio.url, maxEventsInBatch: 1 })
const api = new APIClient("app-key", { url: `${cio.url}/v1` })
analytics.identify({ userId: "42", traits: { email: "ada@example.com" } })
await analytics.closeAndFlush()
await api.sendEmail(
  new SendEmailRequest({ transactional_message_id: 1, identifiers: { id: "42" }, to: "ada@example.com" }),
)

// Test assertions read the emulator's state.
const profiles = await (await fetch(`${cio.url}/__admin/profiles`)).json()
const deliveries = await (await fetch(`${cio.url}/__admin/outbox?userId=42`)).json()
await cio.close()

#Routes

#Reporting webhook

POST <webhook-url> with x-cio-timestamp: <unix seconds> and x-cio-signature: <hex HMAC-SHA256(secret, "v0:<timestamp>:<body>")> (wall-clock timestamps). Body: {event_id, object_type, metric, timestamp, data: {identifiers: {id, email, cio_id}, customer_id, email_address, delivery_id?, transactional_message_id?, href?, link_id?, content?}}; content is the JSON string of subscription preferences. timestamp never runs ahead of wall-clock time (our receiver rejects events > 5 min in the future). Retries, GET /__admin/webhooks, …/events, …/replay, …/flush and PUT /__admin/webhook-endpoints work as usual.

#Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets): transactional_message_missing (400 meta.error: trigger_name_missing, then fallback; no delivery), transactional_404, request_timeout_408 (408 before enqueue, no delivery, ambiguous), server_error (500 before enqueue, no delivery, ambiguous), accepted_but_500 (queued, then 500), rate_limited (429 with numeric Retry-After, definite, no delivery), invalid_app_key, send_drop and send_drop_before_accept (socket closes before enqueue: ambiguous, no delivery), send_drop_after_accept (delivery recorded, then the socket closes: ambiguous, one delivery), cdp_unavailable (503; the SDK retries), cdp_bad_request (400; no retry), cdp_slow (15 s, past the 10 s delivery timeout), transactional_list_unavailable, omit_trigger_names (omit every trigger_name, or only params.ids), webhook_duplicate, webhook_drop, webhook_reorder. A manual fault can inject 403 or 503, or a 429 whose Retry-After is an HTTP-date. ECONNREFUSED (a definite failure) is a stopped emulator, not a preset. 401 is {error} on the CDP and {meta: {error}} on the App API. Keys mapped to the same namespace share profiles and deliveries; two namespaces do not, including faults and clock offsets. Resetting one namespace leaves the other.

#Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix on a host, or by key: the CDP write key (Basic username) or the App API key (Bearer) through PUT /__admin/credentials {"credentials": {"<key>": "<namespace>"}}. The click endpoint carries no credential: use the header or prefix.

#Deliberately not modelled

• Opt-out writes through the public PUT API, phone identifier workspace configuration, Twilio sender identity casing recovery, and automatic carrier STOP callbacks. Use the admin control to script reconciler state; it does not model carrier delivery enforcement.
• Rendering: templates are not rendered; the outbox holds message_data, not HTML.
• Campaigns, segments, journeys, broadcasts and the Track API (track.customer.io).
• CDP page, screen, group and alias calls (our consumers send none).
• Attachments are recorded by filename only. Customer.io documents a {filename: base64} map; our backend sends [{filename, content, content_type}]. Both are accepted; whether the real API accepts the array form is unverified (no sandbox credentials).
• Response bodies of the CDP host ({success: true}) and exact App API error strings other than transactional_message_id not found are unverified.

#API

Part of mockingbird.