Customer.io Destination Config Reference

Customer.io is a messaging and marketing automation destination. RudderStack sends events to Customer.io’s APIs from its servers, or through Customer.io’s own SDKs in device mode on web, Android, and iOS.

In a Customer.io destination spec:

• type: customerio
• definition_version: 1

Sample configuration

version: rudder/v1
kind: destination
metadata:
  name: customerio-prod
spec:
  id: customerio-prod
  display_name: Customer.io Production
  type: customerio
  definition_version: 1
  enabled: true
  config:
    site_id: "{{ .CUSTOMERIO_SITE_ID }}"
    api_key: "{{ .CUSTOMERIO_API_KEY }}"
    datacenter: US
    api_version: v2
    user_id_identifier_type: id
    device_token_event_name: Device Token Registered

    sdk_version:
      web: v2
    write_key:
      web: "{{ .CUSTOMERIO_WRITE_KEY }}"
    anonymous_in_app:
      web: false
    send_page_name_in_sdk:
      web: true
    auto_track_device_attributes:
      android: true
      ios: true
    background_queue_min_number_of_tasks:
      android: "10"
    background_queue_seconds_delay:
      android: "30"

    connection_mode:
      web: device
      android: device
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - marketing

The above example sends server-side events through the v2 API, and connects web and Android sources in device mode, where the SDK settings apply. Web loads the v2 JavaScript client, so it needs write_key — see Key dependencies.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

Key dependencies

Which credentials Customer.io needs depends on the modes your sources connect in, and on the web SDK version. Rudder CLI enforces each requirement below.

Write sdk_version out to use the v2 web client. When the block is omitted, nothing fills it in — the destination is stored without a version, which Customer.io’s web SDK and the API’s checks both read as v1. The v2 default applies only inside an sdk_version block you write.

Connection

Cloud mode

These keys apply to events sent in cloud mode. They have no effect on device-mode delivery.

Device mode

These keys configure Customer.io’s SDKs, so they apply only to sources connected in device mode. Each is keyed by the source type it applies to.

sdk_version:
  web: v2

auto_track_device_attributes:
  android: true
  ios: false

Event filtering

Client-side event filtering applies only when connection_mode.web is device — the dashboard shows these controls only then, and the SDK is what applies the filter. Rudder CLI accepts the block in any mode, but it has no effect on other connections.

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode:
  web: device
  android: device
  ios: cloud

Source types

Customer.io accepts events from these source types in the mentioned connection modes:

web, android, and ios offer device mode. The Kotlin and Swift SDKs — android_kotlin and ios_swift — are cloud only. See Customer.io device mode.

warehouse is the token a Reverse ETL source resolves to. Rudder CLI manages the destination’s warehouse entry — if the destination is connected to a Reverse ETL source, set connection_mode.warehouse: cloud in its spec, or apply removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under Supported destinations — see Manage Reverse ETL Connections using Rudder CLI.

Important considerations

• Rudder CLI cannot declare a Reverse ETL connection to Customer.io — it syncs Reverse ETL data through its own flow, which connection specs can’t express. The warehouse entry still belongs in the spec so that apply keeps a connection you set up in the dashboard.
• The dashboard additionally offers Customer.io to AMP and Shopify sources. Rudder CLI doesn’t manage those connections, so amp and shopify are invalid here.

Connect a source

An event stream connection to this destination is checked against three rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. Every type an event stream source can resolve to is supported here, so this check always passes.

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'customerio-prod' config has no 'connection_mode' entry for source type 'web'

Every source needs api_key and site_id, except web connecting in device mode. Without them:

destination 'customerio-prod' config is missing fields required to connect a 'cloud' source: api_key, site_id

What web needs in device mode depends on the other source types and on sdk_version — see Key dependencies.

Secrets

api_key and site_id are the secret keys. Write each as a {{ .VAR }} reference and supply the value at apply time:

config:
  site_id: "{{ .CUSTOMERIO_SITE_ID }}"
  api_key: "{{ .CUSTOMERIO_API_KEY }}"

export RUDDER_CUSTOMERIO_SITE_ID="..."
export RUDDER_CUSTOMERIO_API_KEY="..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

• rudder-cli import writes only the secrets the API returns, as {{ .VAR }} references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see Secrets.
• In web device mode the site ID (v1) or write_key (v2) is embedded in the page’s JavaScript, so neither value is hidden from a visitor. Masking site_id protects your YAML, not the value itself. write_key isn’t a secret key, so import writes it as a literal.

See How to Use Variable Substitution in Rudder CLI.

Changes by release

For changes across every destination type, see Destination Type Changes by Release.

See more

• Customer.io Destination for the API key and site ID, and the per-mode settings
• Destination Type Reference for Rudder CLI for the rules shared across destination types
• Destination YAML Reference for the spec envelope