# Iterable Destination Config Reference


> Complete Rudder CLI reference for the Iterable destination config keys, cloud mode settings, web device mode and in-app message settings, and secrets.



[Iterable](https://www.rudderstack.com/docs/destinations/streaming-destinations/iterable/setting-up-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

```yaml
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](#web-device-mode).

## Config keys

`config` accepts only the keys listed below. The [shared config key rules](https://www.rudderstack.com/docs/rudder-cli/destination-types/#config-key-rules) cover unknown keys, defaults, and immutability.

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

### Connection

<div class="rs-ckeys">
<div class="rs-ckey" id="api_key">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">api_key</p>RequiredSecret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Your Iterable API key, from <strong>Integrations</strong> &gt; <strong>API Keys</strong> in Iterable.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/iterable/setting-up-iterable/#where-can-i-find-the-iterable-api-key" >Where can I find the Iterable API key?</a>.
</div>

</div>

<div class="rs-ckey" id="data_center">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">data_center</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Region of your Iterable project.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>USDC</code> or <code>EUDC</code>.</li>
<li>The dashboard defaults this field to <code>USDC</code>. Rudder CLI requires it explicitly.</li>
<li>A spec that omits this key fails validation.</li>
</ul>

</div>

</div>

</div>

### Cloud mode

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

<div class="rs-ckeys">
<div class="rs-ckey" id="register_device_or_browser_api_key">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">register_device_or_browser_api_key</p>Secret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Iterable mobile or web API key, used to register device and browser tokens. Needed when <code>identify</code> calls carry token information.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="prefer_user_id">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">prefer_user_id</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>true</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Create a new Iterable user when an event&rsquo;s <code>userId</code> doesn&rsquo;t match an existing one, using Iterable&rsquo;s <code>preferUserId</code> parameter. The dashboard calls this <strong>Create new user if userID exists</strong>.
</p>

<div class="rs-ckey__extra">
  See Iterable&rsquo;s <a href="https://api.iterable.com/api/docs#users_updateUser" >Update user data API</a>.
</div>

</div>

<div class="rs-ckey" id="merge_nested_objects">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">merge_nested_objects</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>true</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Merge top-level objects on the user profile instead of overwriting them, using Iterable&rsquo;s <code>mergeNestedObjects</code> parameter. The dashboard calls this <strong>Merge top-level objects</strong>.
</p>

</div>

<div class="rs-ckey" id="map_to_single_event">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">map_to_single_event</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>true</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send every page under one event name — <code>Loaded a Page</code> for <code>page</code> calls and <code>Loaded a Screen</code> for <code>screen</code> calls.
</p>

</div>

<div class="rs-ckey" id="track_all_pages">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_all_pages</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send every <code>page</code> event to Iterable.
</p>

</div>

<div class="rs-ckey" id="track_categorized_pages">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_categorized_pages</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>true</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send <code>page</code> events that have a category.
</p>

</div>

<div class="rs-ckey" id="track_named_pages">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_named_pages</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>true</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send <code>page</code> events that have a name.
</p>

</div>

</div>

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

<div class="rs-ckeys">
<div class="rs-ckey" id="package_name">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">package_name</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Name of the website Iterable shows in-app messages for.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Required when <code>connection_mode.web</code> is <code>device</code>. Leave it unset otherwise.</li>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="initialisation_identifier">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">initialisation_identifier</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Identifier the SDK uses to recognize a user across a session.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — <code>email</code> (default) or <code>userId</code>.</li>
<li>Rudder CLI fills in the default only when the <code>initialisation_identifier</code> block is present. Omit the block and no value is sent.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="get_in_app_event_mapping">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">get_in_app_event_mapping</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Event names that trigger fetching and showing in-app messages.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — array of event names, each at most 100 characters or a template.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">get_in_app_event_mapping:
  web:
    - Viewed Pricing
    - Started Checkout</code></pre></div>
</div>
</div>

</div>

<div class="rs-ckey" id="purchase_event_mapping">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">purchase_event_mapping</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Event names sent to Iterable as purchase events.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — array of event names, each at most 100 characters or a template.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="send_track_for_inapp">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">send_track_for_inapp</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send a <code>track</code> event each time an in-app message is shown.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — boolean.</li>
</ul>

</div>

</div>

</div>

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

```yaml
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
```

<div class="rs-ckeys">
<div class="rs-ckey" id="animation_duration">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">animation_duration</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Time, in milliseconds, that messages take to animate in and out.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string, for example <code>&quot;400&quot;</code>.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="display_interval">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">display_interval</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Time, in milliseconds, to wait after a message closes before showing the next one.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="top_offset">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">top_offset</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Space between the top of the screen and a message, in <code>px</code> or <code>%</code>. Doesn&rsquo;t apply to center, top, or full-screen messages.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string, for example <code>&quot;10%&quot;</code>.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="right_offset">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">right_offset</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Space between the right edge of the screen and a message, in <code>px</code> or <code>%</code>. Doesn&rsquo;t apply to center, top, or full-screen messages.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="bottom_offset">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">bottom_offset</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Space between the bottom of the screen and a message, in <code>px</code> or <code>%</code>. Doesn&rsquo;t apply to center, top, or full-screen messages.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="handle_links">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">handle_links</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  How links inside a message open.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — <code>open-all-new-tab</code> (default), <code>open-all-same-tab</code>, or <code>external-new-tab</code>.</li>
<li>Rudder CLI fills in the default only when the <code>handle_links</code> block is present. Omit the block and no value is sent.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="on_open_screen_reader_message">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">on_open_screen_reader_message</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Text a screen reader announces when a message opens.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="on_open_node_to_take_focus">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">on_open_node_to_take_focus</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  DOM element that takes keyboard focus when a message opens.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string, for example a CSS selector.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="close_button_color">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">close_button_color</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Color of the close button.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="close_button_size">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">close_button_size</p>Internal</div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Size of the close button.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="close_button_position">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">close_button_position</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Position of the close button on the message.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — <code>top-right</code> (default) or <code>top-left</code>.</li>
<li>Rudder CLI fills in the default only when the <code>close_button_position</code> block is present. Omit the block and no value is sent.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="close_button_color_top_offset">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">close_button_color_top_offset</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Space between the close button and the message&rsquo;s top border. Despite <code>color</code> in its name, this is an offset.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="close_button_color_side_offset">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">close_button_color_side_offset</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Space between the close button and the message&rsquo;s side borders. Despite <code>color</code> in its name, this is an offset.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="icon_path">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">icon_path</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Path to an image or SVG shown instead of the default close icon.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="is_required_to_dismiss_message">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">is_required_to_dismiss_message</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Stop users from dismissing a message by clicking outside it.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — boolean.</li>
</ul>

</div>

</div>

</div>

### Event filtering

**Warning:** [Client-side event filtering](https://www.rudderstack.com/docs/sources/event-streams/sdks/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.

<div class="rs-ckeys">
<div class="rs-ckey" id="event_filtering">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">event_filtering</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Restricts which <code>track</code> events the SDK passes to Iterable, by event name.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>whitelist</code> — array of event names to allow; every other <code>track</code> event is dropped.</li>
<li><code>blacklist</code> — array of event names to drop; every other <code>track</code> event is allowed.</li>
<li>The two are mutually exclusive, and Rudder CLI enforces it — setting both fails validation.</li>
<li>Each name is at most 100 characters, or a <code>{{ path || fallback }}</code> template.</li>
</ul>

</div>

</div>

</div>

### Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under [Source types](#source-types). A key naming a source type this destination doesn't support fails validation.

<div class="rs-ckeys">
<div class="rs-ckey" id="connection_mode">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">connection_mode</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Maps each source type you connect to the mode its events reach Iterable in, using the modes in <a href="#source-types" >Source types</a>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>An entry is required for each source type you connect — see <a href="#connect-a-source" >Connect a source</a>.</li>
<li>A mode the source type doesn&rsquo;t support on this destination fails validation — for example <code>device</code> for <code>android</code>.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">connection_mode:
  web: device
  cloud: cloud</code></pre></div>
</div>
</div>

</div>

<div class="rs-ckey" id="consent_management">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">consent_management</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Consent provider configuration per source type. The entry shape, accepted providers, and the rules on <code>resolution_strategy</code> and <code>consents</code> are shared across all destination types — see <a href="https://www.rudderstack.com/docs/rudder-cli/destination-types/#consent-management" >Consent management</a>.
</p>

</div>

</div>

## Source types

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

| Source type | Connection mode |
| :-----| :-----|
| `android` | `cloud` |
| `android_kotlin` | `cloud` |
| `ios` | `cloud` |
| `ios_swift` | `cloud` |
| `web` | `cloud`, `device` |
| `unity` | `cloud` |
| `react_native` | `cloud` |
| `flutter` | `cloud` |
| `cordova` | `cloud` |
| `cloud` | `cloud` |
| `warehouse` | `cloud` |

Only `web` offers `device` mode, which loads Iterable's web SDK — recommended if you use Iterable's web push notifications. See [Iterable device mode](https://www.rudderstack.com/docs/destinations/streaming-destinations/iterable/iterable-device-mode/).

`warehouse` is the token a [Reverse ETL source](https://www.rudderstack.com/docs/sources/reverse-etl/) 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](https://www.rudderstack.com/docs/rudder-cli/yaml-retl-connections/#supported-destinations) — see [Manage Reverse ETL Connections using Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/retl-connections/).

**Info:** The dashboard additionally offers Iterable to AMP and Shopify sources. Rudder CLI doesn&#39;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](https://www.rudderstack.com/docs/rudder-cli/yaml-connections/). Without it:

```text
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](#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:

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

```bash
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](https://www.rudderstack.com/docs/rudder-cli/destination-types/#secrets).

See [How to Use Variable Substitution in Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/).

## Changes by release

<table>
  <thead>
    <tr>
      <th>Version</th>
      <th>Change</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Breaking:</strong> A <code>null</code> config value, written as <code>key: null</code>, <code>key: ~</code>, or <code>key:</code> with no value, fails <code>validate</code> with <code>'&lt;key&gt;' must not be null; set a value or remove the key</code>. Earlier releases accepted it: a top-level null planned an update on every <code>apply</code>, and a null inside a list item failed at the API.<br><strong>What to do:</strong> Remove the key to leave it unset, or give it a value.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Breaking:</strong> An empty string, <code>&quot;&quot;</code>, on a key that takes one of a fixed set of values fails <code>validate</code> with <code>'&lt;key&gt;' must be one of [...]</code>, unless <code>&quot;&quot;</code> is one of the key&rsquo;s values. Earlier releases accepted it, and the API rejected it at <code>apply</code>.<br><strong>What to do:</strong> Remove the key to leave it unset, or set one of the listed values.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Changed:</strong> <code>validate</code> warns when a secret key holds anything but one <code>{{ .VAR }}</code> reference with no default, and when one variable fills two secret keys. It also masks secret values in the lines it prints.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Changed:</strong> <code>rudder-cli import</code> writes each secret reference single-quoted, as <code>'{{ .VAR }}'</code>, so a value containing double quotes, like a JSON key file, substitutes as a string. A single quote in a value that fills such a reference is written as <code>''</code>.<br><strong>What to do:</strong> In a spec imported by an earlier release, quote each reference to a JSON value by hand: <code>'{{ .VAR }}'</code>.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Changed:</strong> <code>validate</code> reports a value of the wrong type once per key, such as <code>'email' must be a string</code>, instead of one raw decoding error.</td>
    </tr>
    <tr>
      <td>v0.28.0</td>
      <td><strong>Added:</strong> <code>warehouse</code> source type, for destinations connected to a Reverse ETL source. Set <code>connection_mode.warehouse: cloud</code> for such a destination, or <code>apply</code> removes the entry.</td>
    </tr>
  </tbody>
</table>

For changes across every destination type, see [Destination Type Changes by Release](https://www.rudderstack.com/docs/rudder-cli/destination-types/changes/).

## See more

- [Iterable Destination](https://www.rudderstack.com/docs/destinations/streaming-destinations/iterable/setting-up-iterable/) for the API key, web SDK, and Iterable catalogs
- [Destination Type Reference for Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/destination-types/) for the rules shared across destination types
- [Destination YAML Reference](https://www.rudderstack.com/docs/rudder-cli/yaml-destinations/) for the spec envelope