Iterable is a cross-channel marketing platform designed to help businesses create seamless and personalized customer experiences. It enables marketers to design, execute, and optimize campaigns across email, SMS, push notifications, in-app messaging, and social media channels. With robust automation, segmentation, and analytics capabilities, Iterable empowers brands to deliver targeted and data-driven messaging.
Product Type: Marketing
Integration Type: Starter Kit
Event Source Type: Web
Event Scope: Full-Funnel Events
- Project Support: This integration supports both hybrid and email-only Iterable projects, enabling flexible use cases depending on project type.
- Event Tracking: Supports standard event types like
identify, product_added, and order_completed, as well as custom events and parameters in alignment with Iterable's API schema.
- Default Event Mapping: Default events in the integration are used to track all events not covered by specific APIs, such as add to cart, purchase, or identify. These events leverage the generic
/api/events/track endpoint, allowing for flexible tracking of custom user interactions and behaviors outside the scope of dedicated APIs.
- Global and Event-Specific Mappings:
- Global mappings ensure consistent inclusion of key identifiers, such as
email, userId, and ip.
- Event-specific mappings capture additional contextual data like product details, quantities, and transaction amounts.
- Data Transformation: Lua expressions allow for dynamic data transformations and enrichment prior to transmission, ensuring compatibility with Iterable's requirements.
- Merge Users: The MetaRouter integration utilizes Iterable's Merge Users API to consolidate duplicate user profiles by merging a source user profile into a destination user profile. This process transfers system events, custom events, and user profile fields from the source to the destination, ensuring data consistency and reducing fragmentation. The source user profile is deleted post-merge, and conflicts in overlapping fields are resolved by prioritizing the destination profile's data. This functionality is especially valuable in hybrid or email-based projects where multiple identifiers (e.g., email, userId) may represent the same user.
- Authentication: Integrates with Iterable using API key-based authentication for secure data exchange.
- Data Schema Compliance: Event payloads must strictly adhere to Iterable's API specifications. Non-compliant payloads will be rejected without automatic error correction or fallback.
- Region-Specific Base URL Requirements: Data center-specific base URLs must be configured for regional compliance. Failure to use the correct URL may result in rejected or misrouted requests.
- IP Override: If the Iterable project setting 'Automatically update IP in user profile from inbound events' is enabled, the ip field updated by MetaRouter may be overwritten after email clicks. This setting populates the ip field on user profiles based on Iterable's tracking, which could impact data consistency. Customers should be aware of this potential interaction when configuring their integration.
- The referrer (
dataFields.referrer) and locale (dataFields.locale) can be added as Global or Event Specific mappings to improve user match rates when available.
- Push Notification Support: This integration does not support push notification delivery to Iterable. Only event tracking and email project data are supported.
- No In-App Messaging or SMS Support: In-app messaging, SMS, and other Iterable campaign types are not handled by this integration. The focus is on events and identifiers relevant to email and hybrid projects.
- Batch Event Processing: This integration processes events individually in real-time. Batch uploads or bulk event processing are not supported via the APIs being used.
- Geo Limitations on Merged Users: Geolocation updates for merged users are limited because the
ip address in the dataFields object does not transfer if the source profile lacks it. Geolocation is only updated for identify events through the /api/users/update endpoint. This limitation arises as the source profile's data is either prioritized or omitted during the merge unless explicitly included, as per the Merge Users API behavior.
- Merge User Array Fields: We do not support merging array fields. If an array field exists, only the destination profile's version is retained during the merge.
- Log in to your Iterable account and navigate to the API Keys section in account settings.
- Create a new API key with the necessary permissions for event tracking and user data management.
- Locate your Iterable data center to determine the appropriate
API_BASE_URL:
- US-based accounts:
https://api.iterable.com
- EU-based accounts:
https://api.eu.iterable.com
- Other regions: refer to Iterable's documentation or contact support for the correct base URL.
- From the integration library, add an Iterable integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|
API_KEY | The API key from your Iterable account. Required for authentication. |
API_BASE_URL | The base URL for the Iterable API. Typically https://api.iterable.com. |
- MetaRouter provides all of the event mappings that Iterable integrations typically require. You may add custom events, parameters, or mappings in accordance with Iterable's API documentation.
- In the Pipelines tab, add your Iterable integration.
- Select the correct integration revision.
- Click Add Integration to finalize deployment.
Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.
| Output Key | Description | Expected Input |
|---|
id Required | String: A unique identifier for the event. | messageId |
createdAt Required | Integer: The event timestamp in seconds since the Unix epoch. | Expression – converts timestamp to seconds since epoch |
dataFields.ip | String: The user's IP address. | context.ip |
dataFields.userAgent | String: The user's browser or device user agent. | context.userAgent |
createNewFields | Boolean: Indicates whether to create new custom fields automatically if not predefined. | Enrichment – true |
| Output Key | Description | Expected Input |
|---|
email Required | String: The email address of the user. | traits.email |
userId Highly Recommended | String: The unique identifier of the user. | anonymousId |
| Output Key | Description | Expected Input |
|---|
user.email Required | String: The email address of the user. | traits.email |
user.userId Highly Recommended | String: The unique identifier of the user. | anonymousId |
items Required | Array: Builds the added product item with id, sku, name, categories, price, quantity, imageUrl, and url. | Expression – builds the item from properties |
| Output Key | Description | Expected Input |
|---|
user.email Required | String: The email address of the user. | traits.email |
user.userId Highly Recommended | String: The unique identifier of the user. | anonymousId |
total Required | Float: The total value of the order. | Expression – sums price × quantity across properties.products |
items Required | Array: Builds a list of purchased product items, each with id, sku, name, categories, price, quantity, imageUrl, and url. | Expression – builds items from properties.products |
dataFields | Object: Additional custom fields for the purchase event. | Expression – returns properties with products removed |
dataFields.ip | String: The user's IP address. | context.ip |
dataFields.userAgent | String: The user's browser or device user agent. | context.userAgent |
| Output Key | Description | Expected Input |
|---|
email Required | String: The email address of the user. | traits.email |
userId Highly Recommended | String: The unique identifier of the user. | anonymousId |
eventName Required | String: The name of the event being tracked. | Expression – returns input.event for track events, otherwise input.type |
dataFields | Object: Additional custom fields associated with the event. | properties |
dataFields.ip | String: The user's IP address. | context.ip |
dataFields.userAgent | String: The user's browser or device user agent. | context.userAgent |
These identifiers must be mapped to Iterable in order for successful user matching to occur. Without these IDs, any events sent to Iterable may not be accurately reflected in reporting. For your convenience, required and recommended IDs are mapped as Global parameters to ensure they are added to every event.
| Attribute | Example | Sync Injector Required? |
|---|
user.email Required | [email protected] | No |
user.userId Recommended | 123456 | No |
dataFields.ip | 203.0.113.42 | No |
dataFields.userAgent | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36 | No |
Coordinate with your Iterable representative, or use the Iterable dashboard, to confirm that events are being received and processed correctly on their backend.
