Advanced Analytica Advanced Analytica: IBOM
← All connectors
Iterable logo

Source connector

Iterable

Set up Iterable as a source and move its data into your chosen destination.

Version 1.0.2 community generally available

Iterable

Use this guide to set up the Iterable source connector and find reference information.

Prerequisites

To set up the Iterable source connector, you need:

  • An Iterable Server-side API key with Standard permissions. Create the key in the Iterable project you want to sync. Mobile, Browser, and other client-side API keys aren’t supported.
  • The data centre hosting your Iterable project. Each project uses either the US data centre (USDC) or European data centre (EDC). An API key only works with the data centre that issued it. If you’re unsure, ask an Iterable administrator or check your Iterable login URL.

Set up the connector

  1. Log into your Airbyte Cloud account or go to the Airbyte Open Source dashboard.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Iterable from the Source type dropdown.
  4. Enter a name for the Iterable connector.
  5. For API Key, enter your Iterable Server-side API key.
  6. For Start Date, enter the date in YYYY-MM-DDTHH:mm:ssZ format. The connector replicates data created on or after this date.
  7. For Region, select the option matching your project’s data centre. Select US for the US data centre or EU for the European data centre. The default is US. The connector calls https://api.iterable.com/api/ for US and https://api.eu.iterable.com/api/ for EU. Your selected region must match the data centre that issued your API key.
  8. (Optional) For Lookback Window (Minutes), enter the minutes to re-read before the current time at each sync window’s end. The default is 5 minutes. This setting accounts for eventual consistency delays in Iterable’s Export API. Increase it if events are missing near the end of sync windows.
  9. Click Set up source.

Supported sync modes

The Iterable source connector supports these sync modes:

  • Full Refresh - Overwrite
  • Full Refresh - Append
  • Incremental - Append
  • Incremental - Append + Deduped

Incremental streams don’t declare primary keys. To use Incremental - Append + Deduped, select a primary key when configuring the connection.

Supported streams

Limits and considerations

Data centre regions

Iterable hosts each project in either the US data centre (USDC) or European data centre (EDC). API keys only work with the data centre where they were created. Choose the Region matching your project, so the connector calls the correct base URL. If a working configuration suddenly fails authentication, confirm that Region still matches the data centre that issued your API key.

Rate limits

Iterable’s Export API allows 4 requests per minute for each project. The connector respects this limit and adjusts date-range slice sizes automatically. Most other endpoints allow 100 requests per second for each project. The connector retries rate-limited requests (HTTP 429) using exponential backoff.

Campaigns and Campaign Metrics

The Campaigns stream requests 1,000 campaigns at a time from Iterable’s GET /api/campaigns endpoint. It continues until a page returns fewer than 1,000 campaigns. From connector version 1.0.2, it always sends the page and pageSize parameters. Iterable has deprecated returning every campaign in one unpaginated response. With earlier versions, affected projects only receive the first campaign page when Iterable doesn’t allow unpaginated access.

The Campaign Metrics stream reads the same paginated campaign list. It then requests metrics for 20 campaigns at a time from GET /api/campaigns/metrics. Each request covers the period from your Start Date to the sync time. Therefore, every sync re-reads metrics for the full period. Projects with many campaigns generate many metrics requests.

Incremental sync behaviour

Streams supporting incremental sync use these approaches:

  • Users: Splits data retrieval into 90-day intervals. Uses profileUpdatedAt as the cursor.
  • Export-based event streams (Email, Push, SMS, In-App, Web Push, Inbox, Purchase, CustomEvent, HostedUnsubscribeClick): Uses adaptive date-range slicing. The connector starts with a 30-day slice. It adjusts later slice sizes based on each request’s processing time. If Iterable closes the connection before export finishes (a ChunkedEncodingError), the connector halves the slice size and retries. The sync fails after 6 consecutive failures for the same window, with the error Iterable Export API response repeatedly closed for the selected event window. The slice size resets for the next sync. Retry the sync before investigating further.
  • Templates: Uses fixed 90-day intervals. Uses updatedAt as the cursor.

Custom fields and the data object

Iterable projects define their own user profile and event fields. Three streams keep documented columns fixed and collect all other fields in a generic data object.

Users, from connector version 1.0.0, keeps the fields Iterable manages at the top level. These include email, userId, itblUserId, emailListIds, userListIds, profileUpdatedAt, signupDate, and signupSource. They also include subscribedMessageTypeIds, unsubscribedChannelIds, unsubscribedMessageTypeIds, knownLitigatorFilter, receivedSMSDisclaimer, city, region, and country. The remaining fields are devices, ip, locale, phoneNumber, whatsAppPhoneNumber, profile, and timeZone. It also keeps the itblInternal and itblDS keys listed below. Every other profile field arrives inside data, including custom fields defined by your project.

The Export API returns Iterable’s internal metadata as flat, dotted keys, rather than a nested object. The connector preserves itblInternal.emailDomain, itblInternal.phoneCountry, itblInternal.phoneType, itblInternal.documentCreatedAt, itblInternal.documentUpdatedAt, itblInternal.isUnknownUser, itblDS.brandAffinityLabel, and itblDS.predictiveGoals in this form. Most destinations replace unsupported characters in column names. Expect something like itblinternal_emaildomain, rather than a nested structure you can traverse.

Iterable returns some profile timestamps in a space-separated format, such as 2024-01-15 10:30:00 +00:00. The connector converts signupDate, profileUpdatedAt, itblInternal.documentCreatedAt, and itblInternal.documentUpdatedAt to RFC 3339 (2024-01-15T10:30:00+00:00). This conversion lets destinations store them as timestamps. Values in other formats pass through unchanged.

Events keeps _type, createdAt, email, and itblInternal at the top level. Every other field, including userId, goes into data.

Campaign Metrics returns one data object for each campaign. Iterable provides these metrics as CSV. The connector parses each row into data. Individual metrics are keys within that object, not top-level columns.

If you’re upgrading from connector version 0.x, see the Iterable migration guide for details about the users stream restructuring.

Lookback window

Iterable’s Export API has eventual consistency, so recent events may not appear immediately in export results. To prevent silent data loss, the connector applies a configurable lookback window. It subtracts this window from the current time when setting each sync window’s end. The default is 5 minutes. The connector also removes duplicate records within the lookback overlap.

Error handling

The List Users stream skips lists returning 500 - Generic Error responses and continues processing the remaining lists. This behaviour stops intermittent API failures for individual lists from blocking the entire sync.

For all streams, the connector retries rate-limited requests (HTTP 429) and server errors (HTTP 500–599) using exponential backoff. It makes up to 10 retries, with delays from 20 to 400 seconds.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
1.0.22026-11-1185908Paginate GET /api/campaigns (the campaigns stream and the campaign lookup used by campaigns_metrics) using the Iterable API’s page and pageSize parameters.
1.0.12026-09-1678129Improve the error message for Iterable Export API response closures after retries.
1.0.02026-08-2579635🚨 Breaking: Restructure users stream schema - standard Iterable fields stay top-level, custom fields move to a data object, itblInternal flattened to dotted keys, timestamp values (signupDate, profileUpdatedAt, itblInternal document timestamps) normalized to RFC3339 to match their timestamp_with_timezone typing, added itblUserId, whatsAppPhoneNumber, city, region. See the migration guide.
0.7.22026-05-0774702Add optional Region parameter to support Iterable’s EU data center
0.7.12026-04-0776036Fix reduce_range() to actually halve slice size on ChunkedEncodingError retry
0.7.02026-03-2474379Add configurable lookback window to prevent silent data loss from Iterable Export API eventual consistency
0.6.542026-03-0474256Filter duplicate records in export streams during incremental syncs
0.6.532025-10-2168545Update dependencies
0.6.522025-10-1467947Update dependencies
0.6.512025-10-1067602Fix array schema definitions
0.6.502025-10-0767361Update dependencies
0.6.492025-09-3066798Update dependencies
0.6.482025-09-0966107Update dependencies
0.6.472025-08-2365380Update dependencies
0.6.462025-08-1664970Update dependencies
0.6.452025-08-0964604Update dependencies
0.6.442025-08-0264284Update dependencies
0.6.432025-07-2663868Update dependencies
0.6.422025-07-1963451Update dependencies
0.6.412025-07-1263141Update dependencies
0.6.402025-07-0562665Update dependencies
0.6.392025-06-2862174Update dependencies
0.6.382025-06-2161814Update dependencies
0.6.372025-06-1661119Update dependencies
0.6.362025-05-2458772Update dependencies
0.6.352025-05-2260854Update dependencies and expected records
0.6.342025-04-1257737Update dependencies
0.6.332025-04-0557057Update dependencies
0.6.322025-03-2956655Update dependencies
0.6.312025-03-2256015Update dependencies
0.6.302025-03-0955510Update dependencies
0.6.292025-03-0154759Update dependencies
0.6.282025-02-2254287Update dependencies
0.6.272025-02-1853814Update dependencies
0.6.262025-02-0152726Update dependencies
0.6.252025-01-2552277Update dependencies
0.6.242025-01-1151163Update dependencies
0.6.232025-01-0450889Update dependencies
0.6.222024-12-2850608Update dependencies
0.6.212024-12-2150101Update dependencies
0.6.202024-12-1449211Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
0.6.192024-12-1248993Update dependencies
0.6.182024-11-0448294Update dependencies
0.6.172024-10-2947803Update dependencies
0.6.162024-10-2847487Update dependencies
0.6.152024-10-2347057Update dependencies
0.6.142024-10-1246814Update dependencies
0.6.132024-10-0546399Update dependencies
0.6.122024-09-2846155Update dependencies
0.6.112024-09-2145828Update dependencies
0.6.102024-09-1445518Update dependencies
0.6.92024-09-0745221Update dependencies
0.6.82024-08-3145029Update dependencies
0.6.72024-08-2444636Update dependencies
0.6.62024-08-1744260Update dependencies
0.6.52024-08-1243899Update dependencies
0.6.42024-08-1043527Update dependencies
0.6.32024-08-0343142Update dependencies
0.6.22024-07-2742653Update dependencies
0.6.12024-07-2342449Fix OOM errors; bum CDK version
0.6.02024-07-2241983Fix OOM errors; update CDK to v3
0.5.112024-07-2042228Update dependencies
0.5.102024-07-1341684Update dependencies
0.5.92024-07-1041401Update dependencies
0.5.82024-07-0941293Update dependencies
0.5.72024-07-0640811Update dependencies
0.5.62024-06-2540362Update dependencies
0.5.52024-06-2240080Update dependencies
0.5.42024-06-1739382Refactor state handling for Python incremental streams
0.5.32024-06-0539142Updated the CDK version to 0.89.0 to fix OOM
0.5.22024-06-0439077[autopull] Upgrade base image to v1.2.1
0.5.12024-04-2436645Schema descriptions and CDK 0.80.0
0.5.02024-03-1836231Migrate connector to low-code
0.4.02024-03-1936267Pin airbyte-cdk version to ^0
0.3.02024-02-2035465Per-error reporting and continue sync on stream failures
0.2.22024-02-1235150Manage dependencies with Poetry.
0.2.12024-01-121234prepare for airbyte-lib
0.2.02023-09-2930931Added userId to email_bounce, email_click, email_complaint, email_open, email_send email_send_skip, email_subscribe, email_unsubscribe, events streams
0.1.312023-12-0633106Base image migration: remove Dockerfile and use the python-connector-base image
0.1.302023-07-1928457Fixed TypeError for StreamSlice in debug mode
0.1.292023-05-2426459Added requests reading timeout 300 seconds
0.1.282023-05-1226014Improve 500 handling for Events stream
0.1.272023-04-0624962UserList stream when meet 500 - Generic Error will skip a broken slice and keep going with the next one
0.1.262023-03-1023938Improve retry for 500 - Generic Error
0.1.252023-03-0723821Added retry for 500 - Generic Error, increased max attempts number to 6 to handle ChunkedEncodingError
0.1.242023-02-1422979Specified date formatting in specification
0.1.232023-01-2722011Set AvailabilityStrategy for streams explicitly to None
0.1.222022-11-3019913Replace pendulum.parse -> dateutil.parser.parse to avoid memory leak
0.1.212022-10-2718537Improve streams discovery
0.1.202022-10-2118292Better processing of 401 and 429 errors
0.1.192022-10-0517602Add check for stream permissions
0.1.182022-10-0417573Limit time range for SATs
0.1.172022-09-0216067added new events streams
0.1.162022-08-1515670Api key is passed via header
0.1.152021-12-068524Update connector fields title/description
0.1.142021-12-018380Update Events stream to use export/userEvents endpoint
0.1.132021-11-228091Adjust slice ranges for email streams
0.1.122021-11-097780Split EmailSend stream into slices to fix premature connection close error
0.1.112021-11-037619Bugfix type error while incrementally loading the Templates stream
0.1.102021-11-037591Optimize export streams memory consumption for large requests
0.1.92021-10-065915Enable campaign_metrics stream
0.1.82021-09-205915Add new streams: campaign_metrics, events
0.1.72021-09-206242Updated schema for: campaigns, lists, templates, metadata
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.