Connect Reverse ETL Source to Iterable Audience
5 minute read
This guide takes you through the steps to connect a Reverse ETL source to your Iterable Audience destination.
You can connect multiple Reverse ETL sources to the Iterable Audience destination.
Setup
- Set up and configure your Reverse ETL source.
- In the Overview tab of the source page, click Add destination > Create new destination. You can also select an already-configured destination here.
- From the list of destinations, select Iterable Audience and click Continue.
- Specify a unique name to identify this destination in RudderStack.
- 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 | Description |
|---|---|
| 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.
|
| 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. |
- Proceed to configure the mapping settings.
Mapping settings
This section lists the settings to correctly map data from your Reverse ETL source 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 | Behavior |
|---|---|
| Yes | Iterable updates only users that already exist in your project. 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 for this integration.
Map identifiers
In this section, map your warehouse columns to Iterable identifier fields based on your project type. See Identifier mappings and validation for the fields available per project type.
Click Map another field to add additional identifier mappings as required.
Sync settings
RudderStack determines how and when to run a sync based on the sync schedule you set for your Reverse ETL connection.
| Schedule type | Description |
|---|---|
| Basic | Run syncs at a given time interval and specified time (in UTC). |
| CRON | Run syncs based on a specified CRON expression (in UTC). |
| Manual | Run syncs manually. |
Sync observability settings
| Setting | Description | ||||||
|---|---|---|---|---|---|---|---|
| Retain sync logs | This setting is toggled on by default and instructs RudderStack to store the sync logs in your warehouse. You can also configure the below settings:
| ||||||
| Retry failed records | This setting is toggled on by default and causes RudderStack to continually retry sending the failed records. |
Storing sync logs and snapshot tables may incur additional warehouse costs.
Identifier mappings and validation
You can map warehouse columns to the following Iterable identifier fields based on your project type:
| Project type | Identifier | Description |
|---|---|---|
| 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. When a row includes both values, both are sent so Iterable can match on either identifier.
|
In mirror mode, audience membership changes map to Iterable list operations:
| Action | Iterable operation |
|---|---|
| Insert or update | Subscribe (add user to the list) |
| Delete | Unsubscribe (remove user from the list)
|
Note that:
- Subscribe and unsubscribe requests are batched, with up to 1000 subscribers per API request.
- RudderStack calls Iterable’s
/api/lists/subscribeand/api/lists/unsubscribeendpoints to make these requests.
Identifier validation
Before sending data to Iterable, each row is validated based on the mapped identifier fields:
| Identifier | Validation |
|---|---|
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.
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.
