Agent Skills: customer-io

Troubleshooting

If requests fail, run zero doctor check-connector --env-name CUSTOMERIO_TRACK_TOKEN or zero doctor check-connector --url https://cdp.customer.io/v1/identify --method POST

Core APIs

Identify a Person (Pipelines API)

Add or update a person's profile. Uses Basic auth with Site ID and Track API key combined and base64-encoded.

Write to /tmp/cio_request.json:

{
  "userId": "clerk_user_abc123",
  "traits": {
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "plan": "free",
    "createdAt": 1700000000
  }
}

curl -s -X POST "https://cdp.customer.io/v1/identify" --header "Authorization: Basic $(printf "%s:%s" "$CUSTOMERIO_SITE_ID" "$CUSTOMERIO_TRACK_TOKEN" | base64 -w 0)" --header "Content-Type: application/json" -d @/tmp/cio_request.json

Docs: https://docs.customer.io/integrations/data-in/connections/http-api/

Track an Event (Pipelines API)

Send a behavioral event to trigger automated campaigns or journeys.

Write to /tmp/cio_request.json:

{
  "userId": "clerk_user_abc123",
  "event": "plan_upgraded",
  "properties": {
    "from_plan": "free",
    "to_plan": "pro",
    "mrr": 49
  }
}

curl -s -X POST "https://cdp.customer.io/v1/track" --header "Authorization: Basic $(printf "%s:%s" "$CUSTOMERIO_SITE_ID" "$CUSTOMERIO_TRACK_TOKEN" | base64 -w 0)" --header "Content-Type: application/json" -d @/tmp/cio_request.json

Send Transactional Email (App API)

Send a one-off email using a template configured in Customer.io. Replace <transactional-message-id> with the ID from your Customer.io dashboard.

Write to /tmp/cio_request.json:

{
  "transactional_message_id": "<transactional-message-id>",
  "to": "user@example.com",
  "identifiers": {
    "email": "user@example.com"
  },
  "message_data": {
    "firstName": "Jane",
    "resetLink": "https://app.example.com/reset?token=abc123"
  }
}

curl -s -X POST "https://api.customer.io/v1/send/email" --header "Authorization: Bearer $CUSTOMERIO_APP_TOKEN" --header "Content-Type: application/json" -d @/tmp/cio_request.json

Docs: https://docs.customer.io/journeys/transactional-api-examples/

Delete a Person (App API)

Delete a person by their Customer.io ID. Replace <person-id> with the actual ID:

curl -s -X DELETE "https://api.customer.io/v1/customers/<person-id>" --header "Authorization: Bearer $CUSTOMERIO_APP_TOKEN"

Search People (App API)

Write to /tmp/cio_request.json:

{
  "filter": {
    "and": [
      {
        "attribute": {
          "field": "email",
          "operator": "eq",
          "value": "user@example.com"
        }
      }
    ]
  }
}

curl -s -X POST "https://api.customer.io/v1/customers" --header "Authorization: Bearer $CUSTOMERIO_APP_TOKEN" --header "Content-Type: application/json" -d @/tmp/cio_request.json | jq '{results: [.results[] | {id, email: .attributes.email}]}'

List Segments (App API)

curl -s "https://api.customer.io/v1/segments" --header "Authorization: Bearer $CUSTOMERIO_APP_TOKEN" | jq '[.segments[] | {id, name, type}]'

Guidelines

1. Two API systems: Pipelines API (cdp.customer.io) handles identity and events; App API (api.customer.io) handles transactional sends and profile queries. Use different credentials for each.
2. Basic auth encoding: The Pipelines API uses base64(site_id:track_api_key) — not Bearer token.
3. userId: Use a stable, unique identifier (e.g., Clerk user ID). Do not use email as the primary ID if users can change their email.
4. Event names: Use snake_case by convention (e.g., plan_upgraded, interview_scheduled).
5. Transactional message ID: Find it in Customer.io under Journeys > Transactional > [template] in the URL or code example tab.
6. Rate limit: 100 requests per second (fair-use). Implement exponential backoff on HTTP 429.
7. Regions: Default region uses api.customer.io; EU region uses api-eu.customer.io and track-eu.customer.io.