Iterable Destination Config Reference

Iterable is a cross-channel marketing destination. RudderStack sends events to Iterable’s API from its servers, or — for web sources — through Iterable’s web SDK in device mode, which also shows in-app messages.

In an Iterable destination spec:

• type: iterable
• definition_version: 1

Sample configuration

version: rudder/v1
kind: destination
metadata:
  name: iterable-prod
spec:
  id: iterable-prod
  display_name: Iterable Production
  type: iterable
  definition_version: 1
  enabled: true
  config:
    api_key: "{{ .ITERABLE_API_KEY }}"
    data_center: USDC

    register_device_or_browser_api_key: "{{ .ITERABLE_MOBILE_WEB_KEY }}"
    prefer_user_id: true
    merge_nested_objects: true
    map_to_single_event: true
    track_all_pages: false
    track_categorized_pages: true
    track_named_pages: true

    package_name: acme-web
    initialisation_identifier:
      web: email
    get_in_app_event_mapping:
      web:
        - Viewed Pricing
    handle_links:
      web: open-all-new-tab
    close_button_position:
      web: top-right

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

The above example connects web sources in device mode, which is what makes package_name required, and sends server-side events in cloud mode, where the page settings apply — see Web device mode.

Config keys

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

In cloud mode Iterable accepts identify, page, screen, track, and alias events. In device mode, web sources send identify and track.

Connection

Cloud mode

These keys apply to events sent in cloud mode. The dashboard shows them only when the destination has a cloud-mode connection.

Web device mode

These keys configure Iterable’s web SDK, so they apply only when connection_mode.web is device. Apart from package_name, each is keyed by web.

get_in_app_event_mapping:
  web:
    - Viewed Pricing
    - Started Checkout

In-app message display

These keys shape how in-app messages look and behave in the browser. They apply only when connection_mode.web is device, and each is keyed by web. Unless noted, the value is a string and isn’t validated locally:

animation_duration:
  web: "400"
top_offset:
  web: "10%"
handle_links:
  web: open-all-new-tab
close_button_position:
  web: top-right
is_required_to_dismiss_message:
  web: false

Event filtering

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

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
  cloud: cloud

Source types

Iterable accepts events from these source types in the mentioned connection modes:

Only web offers device mode, which loads Iterable’s web SDK — recommended if you use Iterable’s web push notifications. See Iterable 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.

The dashboard additionally offers Iterable 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 two 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 'iterable-prod' config has no 'connection_mode' entry for source type 'web'

Iterable needs no additional config keys to connect a source of any type, in any mode. package_name is checked on the destination instead — see Web device mode.

Secrets

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

config:
  api_key: "{{ .ITERABLE_API_KEY }}"
  register_device_or_browser_api_key: "{{ .ITERABLE_MOBILE_WEB_KEY }}"

export RUDDER_ITERABLE_API_KEY="..."
export RUDDER_ITERABLE_MOBILE_WEB_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.

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

• Iterable Destination for the API key, web SDK, and Iterable catalogs
• Destination Type Reference for Rudder CLI for the rules shared across destination types
• Destination YAML Reference for the spec envelope