customer-io

What this skill does

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

```json
{
  "userId": "clerk_user_abc123",
  "traits": {
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "plan": "free",
    "createdAt": 1700000000
  }
}
```

```bash
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`:

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

```bash
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`:

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

```bash
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:

```bash
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`:

```json
{
  "filter": {
    "and": [
      {
        "attribute": {
          "field": "email",
          "operator": "eq",
          "value": "[email protected]"
        }
      }
    ]
  }
}
```

```bash
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)

```bash
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`.