# Customer.io

Customer.io is a customer engagement platform that enables businesses to send automated emails, push notifications, SMS, and in-app messages based on user behavior. The Sling Customer.io connector extracts data from the Customer.io App API, supporting campaigns, broadcasts, newsletters, segments, activities, messages, and more.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `app_api_key` **(required)** -> Your Customer.io App API Key

**Inputs (optional):**

* `base_url` (optional) -> API base URL. Use `https://api-eu.customer.io` for EU region. Defaults to `https://api.customer.io`.
* `anchor_date` (optional) -> Starting date for first sync in ISO 8601 format (e.g., `2024-01-01T00:00:00Z`). Defaults to 1 year ago.

### Getting Your API Key

1. Log in to your [Customer.io account](https://fly.customer.io)
2. Go to **Settings** > **Account Settings** > **API Credentials**
3. Click the **App API keys** tab
4. Click **Create App API Key**
5. Give the key a name (e.g., "Sling Integration")
6. Click **Create** and copy the key immediately — it is only shown once

{% hint style="warning" %}
**Important:** Use an **App API Key**, not a Track API Key. Track API keys are for sending data *to* Customer.io, while App API keys are for reading data *from* Customer.io.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set CUSTOMERIO type=api spec=customerio secrets='{ app_api_key: "your_app_api_key_here" }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export CUSTOMERIO='{ type: api, spec: customerio, secrets: { app_api_key: "your_app_api_key_here" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  CUSTOMERIO:
    type: api
    spec: customerio
    secrets:
      app_api_key: "your_app_api_key_here"
```

#### EU Region

If your Customer.io workspace is hosted in the EU data center, add the `base_url` input:

```yaml
connections:
  CUSTOMERIO:
    type: api
    spec: customerio
    secrets:
      app_api_key: "your_app_api_key_here"
    inputs:
      base_url: "https://api-eu.customer.io"
```

## Replication

Here's an example replication configuration to sync Customer.io data to a PostgreSQL database:

```yaml
source: CUSTOMERIO
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: customerio.{stream_name}

streams:
  # Core messaging data
  campaigns:
  campaign_actions:
  broadcasts:
  broadcast_actions:
  newsletters:

  # Audience data
  segments:
  segment_membership:

  # Activity and message data (incremental)
  activities:
    mode: incremental
  messages:
    mode: incremental

  # Reference data
  transactional_messages:
  collections:
  snippets:
  sender_identities:
  subscription_topics:
```

## Endpoints

### Messaging

| Endpoint                 | Description                                             | Incremental |
| ------------------------ | ------------------------------------------------------- | ----------- |
| `campaigns`              | Campaign definitions and metadata                       | No          |
| `campaign_actions`       | Actions/steps within each campaign (child of campaigns) | No          |
| `broadcasts`             | One-time broadcast messages                             | No          |
| `broadcast_actions`      | Actions within each broadcast (child of broadcasts)     | No          |
| `newsletters`            | Newsletter definitions                                  | No          |
| `transactional_messages` | Transactional message templates                         | No          |

### Audience

| Endpoint             | Description                                      | Incremental |
| -------------------- | ------------------------------------------------ | ----------- |
| `segments`           | Audience segment definitions                     | No          |
| `segment_membership` | Customer IDs in each segment (child of segments) | No          |

### Activity & Messages

| Endpoint     | Description                                             | Incremental     |
| ------------ | ------------------------------------------------------- | --------------- |
| `activities` | Activity log (attribute changes, events, message sends) | Yes (cursor)    |
| `messages`   | Message delivery records (max 6 months lookback)        | Yes (timestamp) |

### Reference Data

| Endpoint              | Description                          | Incremental |
| --------------------- | ------------------------------------ | ----------- |
| `collections`         | Data collections for personalization | No          |
| `snippets`            | Reusable content snippets            | No          |
| `sender_identities`   | Sender email identities              | No          |
| `subscription_topics` | Subscription preference topics       | No          |

To discover available endpoints:

```bash
sling conns discover CUSTOMERIO
```

## Parent-Child Endpoints

Some endpoints are children of parent endpoints and require the parent to run first:

* **campaign\_actions** -> Requires `campaigns` to run first (iterates through each campaign)
* **broadcast\_actions** -> Requires `broadcasts` to run first (iterates through each broadcast)
* **segment\_membership** -> Requires `segments` to run first (iterates through each segment)

When using these endpoints in a replication, Sling automatically handles the ordering via internal queues.

## Incremental Sync

The Customer.io connector supports incremental sync for the following endpoints:

* **activities** - Uses cursor-based pagination to resume from the last position
* **messages** - Uses timestamp-based filtering with `start_ts` and `end_ts` parameters (maximum 6 months lookback)

### How it works

* **First run:** Fetches all available data (activities) or the last 6 months (messages)
* **Subsequent runs:** Only fetches records created after the last sync position

## Rate Limiting

The Customer.io App API enforces a rate limit of 10 requests per second. The connector automatically:

* Limits to 10 requests/second
* Limits concurrency to 3 parallel requests
* Retries with exponential backoff on 429 (rate limit) responses

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).