# Sync Audiences to Iterable


This guide lists the steps to configure Iterable Audience as a destination in RudderStack and sync the created audiences to it.

## Prerequisites

- An [Iterable API key](#where-can-i-find-the-iterable-api-key) with permission to manage lists and add/remove users.
- Confirm your Iterable project type — **Email-based**, **User ID-based**, or **Hybrid**, so you map the correct identifier fields during sync setup

##  Setup

1. Set up an audience in RudderStack using the [Audience Builder]({{< ref "audiences/audience-builder/create-audience.md" >}}).
2. Go to the **Syncs** tab of the audience page and click **Add sync**. Then, select **Iterable Audience**.
3. Click **New destination** — you can also select an already-configured destination here.
4. Specify a unique name to identify this destination in RudderStack.
5. In the **Iterable account** section, click **Select** to choose an existing account. To add a new account, click **Add account** > **API Key**, and specify the following settings:

| Setting | <div style="width: 350px;">Description</div> |
| :----| :-----|
| Account Name | Specify a unique account name. |
| API Key | Enter your Iterable server-side API key. RudderStack sends this value as the `Api-Key` header. |
| Data Center | Select the Iterable data center for your project. <ul><li>**US**: Uses `api.iterable.com`</li><li>**EU**:  Uses `api.eu.iterable.com`</li></ul> {{< info >}}Syncs call the live Iterable API for your selected data center — there is **no** test or sandbox mode for this integration.{{< /info >}} |
| Project Type | Select your Iterable project type — **Email-based**, **User ID-based**, or **Hybrid** — to determine which identifier fields you can map in the sync. |

{{< image src="images/audiences/destinations/iterable/configure-account.webp" >}}

6. Proceed to configure the mapping settings.

## Configure sync

This section lists the settings to correctly configure your audience syncs to the Iterable Audience destination.

### Select list

In this section, you can create a new Iterable list or use an existing one. The selected list is where users are subscribed or unsubscribed during each sync.

- **Create new list**: Specify the list name and optional description. RudderStack creates the list in Iterable while creating the connection.
- **Use existing list**: Select an existing list from the dropdown. Click the refresh icon to fetch the latest lists from Iterable.

### Update existing users only

This setting is visible only for **Hybrid** and **User ID-based** project types. It is set to **No** by default.

The following table describes the behavior of this setting:

| Setting | <div style="width: 350px;">Behavior</div> |
| :---- | :---- |
| **Yes** | Iterable updates only users that already exist in your project. <br /><br />Rows whose `userId` or `email` is not found are reported as failed records and are not added to the list. |
| **No** | Iterable creates new users when subscribing — it creates a placeholder email, if not provided . |

### Sync mode

RudderStack supports only [Mirror mode]({{< ref "data-pipelines/reverse-etl/developer-guides/sync-modes.md#mirror-mode" >}}) for this integration.

### Map identifiers

In this section, map your warehouse columns to Iterable identifier fields based on your [project type](#setup). See [Identifier mappings and validation](#identifier-mappings-and-validation) for the fields available per project type.

{{< image src="images/audiences/destinations/iterable/map-identifiers.webp" >}}

Click **Map another field** to add additional identifier mappings as required.

## Sync settings

{{< customreadfile "/includes/audiences/sync-settings.md" >}}

## Enable sync

{{< customreadfile "/includes/audiences/enable-sync.md" >}}

## Identifier mappings and validation

You can map warehouse columns to the following Iterable identifier fields based on your project type:

| Project type | Identifier | <div style="width: 350px;">Description</div> |
| :---- | :---- | :---- |
| Email-based | `email` | Map a warehouse column to the user's email address. |
| UserId-based | `userId` | Map a warehouse column to the user's Iterable user ID. |
| Hybrid | `email`, `userId` | Map warehouse columns to **both** fields. <br /><br />When a row includes both values, both are sent so Iterable can match on either identifier. <br /><br />{{< info >}}Iterable treats `userId` as the primary key.{{< /info >}} |

In mirror mode, audience membership changes map to Iterable list operations:

| Action | <div style="width: 350px;">Iterable operation</div> |
| :---- | :---- |
| Insert or update | Subscribe (add user to the list) |
| Delete | Unsubscribe (remove user from the list) <br /><br />{{< warning >}}Unsubscribe removes the user from **this list only** — it does not unsubscribe them from all Iterable messaging channels.{{< /warning >}} |

Note that:

- Subscribe and unsubscribe requests are batched, with up to **1000** subscribers per API request. 
- RudderStack calls Iterable's [`/api/lists/subscribe`](https://api.iterable.com/api/docs#lists_subscribe) and [`/api/lists/unsubscribe`](https://api.iterable.com/api/docs#lists_unsubscribe) endpoints to make these requests.

#### Identifier validation

Before sending data to Iterable, each row is validated based on the mapped identifier fields:

| Identifier | <div style="width: 350px;">Validation</div> |
| :---- | :---- |
| `email` | Must be a valid email address. Values are normalized to lowercase and trimmed before sending. |
| `userId` | Must be non-empty with no leading or trailing whitespace. Iterable treats whitespace-padded user IDs as distinct identifiers, which can cause mismatches on unsubscribe. |

Rows with no valid identifier are skipped and reported as **failed records** in the sync report. The sync completes with failures rather than stopping entirely.

- Invalid identifier values are **not** sent to Iterable.
- If a row has no valid identifier, the entire row is marked as failed.

## FAQ

#### Where can I find the Iterable API key?

You can get the Iterable API key by navigating to **Integrations** > **API Keys** in your Iterable account.

For more information, refer to [Iterable's API key documentation](https://support.iterable.com/hc/en-us/articles/360043464871-API-Keys).

#### Why are some rows marked as failed when Update existing users only is enabled?

When **Update existing users only** is set to **Yes**, Iterable does not create users for identifiers that are not already in your project. Those rows fail with a not-found error and appear as failed records in the sync report.

#### Does removing a user from the audience unsubscribe them from Iterable entirely?

No. Delete actions call Iterable's list unsubscribe API, which removes the user from the synced list only. It does not unsubscribe them from all messaging channels in Iterable.

<br />