--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/segment/connections/destinations/catalog/actions-iterable#article headline: Iterable (Actions) Destination description: Connect the Iterable (Actions) destination to Segment to map and send events to Iterable's cross-channel marketing platform with custom mappings. url: https://www.twilio.com/docs/segment/connections/destinations/catalog/actions-iterable inLanguage: en dateModified: 2026-06-10T17:19:57.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Iterable (Actions) Destination [Iterable](https://www.iterable.com/?utm_source=segmentio\&utm_medium=docs\&utm_campaign=partners) is a cross-channel marketing platform that powers unified customer experiences and empowers you to create, optimize and measure every interaction across the entire customer journey. This destination is maintained by Iterable. For any issues with the destination, [contact the Iterable Support team](mailto:support@iterable.com). > \[!TIP] > > This page is about the [Actions-framework](/docs/segment/connections/destinations/actions/) Iterable Segment destination. There's also a page about the [non-Actions Iterable destination](/docs/segment/connections/destinations/catalog/iterable/). Both of these destinations receive data from Segment. ## Benefits of Iterable (Actions) vs Iterable Classic Iterable (Actions) provides the following benefit over Iterable Classic: **Transparent data mapping**: The Classic Iterable destination receives data from Segment and converts Segment events to Iterable's format using hard coded mappings that are unable to be adjusted. The Iterable (Actions) destination allows clients to fully define their own mappings of Segment events, ensuring they receive data structured specifically for their needs. For information about the differences between the Iterable (Actions) and Iterable Classic destinations, see [Important differences from the classic Iterable destination](#important-differences-from-the-classic-iterable-destination). ## Getting started Follow these steps to connect the Iterable (Actions) destination to your Segment sources: 1. Access the Segment web app and click on **Catalog**. 2. In the Catalog, use the search function to find "Iterable". Select the **Iterable (Actions)** destination from the results, and choose which of your sources to connect the destination to. 3. From the Segment web app, navigate to **Connections > Catalog > Destinations**. 4. Click the **Destination Actions** category item in the left navigation. 5. Search for **Iterable (Actions)** and select it. 6. Click **Configure Iterable (Actions)**. 7. Select an existing Source to connect to Iterable (Actions). 8. Complete the Destination Settings as listed below. ## Destination Settings | Field | Description | Required | Type | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | | API Key | To obtain the API Key, go to the Iterable app and naviate to Integrations > API Keys. Create a new API Key with the 'Server-Side' type. | Yes | password | | Data Center Location | The location where your Iterable data is hosted. | No | select | ## Available Presets Iterable (Actions) has the following presets | Preset Name | Trigger | Default Action | | --------------------- | ------------------------------------------------------------------------------- | -------------- | | Track Calls | Event type = "track" and event != "Order Completed" and event != "Cart Updated" | Custom Event | | Identify Calls | Event type = "identify" | Upsert User | | Order Completed Calls | Event type = "track" and event = "Order Completed" | Track Purchase | | Update Cart Calls | Event type = "track" and event = "Cart Updated" | Cart Updates | ## Available Actions Build your own Mappings. Combine supported [triggers](/docs/segment/connections/destinations/actions/#components-of-a-destination-action) with the following Iterable-supported actions: > \[!NOTE] > > Individual destination instances support a maximum of 5 mappings. * [Custom Event](#custom-event-2) * [Cart Updates](#cart-updates) * [Track Purchase](#track-purchase-4) * [Upsert User](#upsert-user) * [Update Subscriptions \[Beta\]](#update-subscriptions-beta) ### Custom Event Track a custom event to a user profile Custom Event is a **Cloud** action. The default Trigger is `type = "track" and event != "Order Completed" and event != "Cart Updated"` | Field | Description | Required | Type | | ----------------- | ------------------------------------------------------------------------- | -------- | -------- | | Email Address | An email address that identifies a user profile in Iterable. | No | STRING | | User ID | A user ID that identifies a user profile in Iterable. | No | STRING | | Event name | Name of the event | Yes | STRING | | Event Data Fields | Additional event properties. | No | OBJECT | | Event ID | A unique ID. If an event exists with that id, the event will be updated | No | STRING | | Timestamp | Time the event took place. | No | DATETIME | | Campaign ID | Iterable campaign the event can be attributed to. | No | INTEGER | | Template ID | Iterable template the event can be attributed to. | No | INTEGER | | Enable Batching | When enabled, Segment will send data to Iterable in batches of up to 1001 | No | BOOLEAN | ### Cart Updates Updates the shoppingCartItems field on the user profile. Cart Updates is a **Cloud** action. The default Trigger is `type = "track" and event == "Cart Updated"` | Field | Description | Required | Type | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | | User Data | Updates user data or adds a user if none exists | Yes | OBJECT | | Cart items | Individual items in the cart. Each item must contain \`id\`, \`name\`, \`price\`, and \`quantity\`. Extra values are added to dataFields. | Yes | OBJECT | ### Track Purchase Tracks a purchase to Iterable Track Purchase is a **Cloud** action. The default Trigger is `type = "track" and event == "Order Completed"` | Field | Description | Required | Type | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | | Order ID | Similar to \`Event ID\` in custom events. Iterable recommends mapping \`order\_id\` or \`messageId\`. If a purchase exists with that id, the purchase will be updated. If none is specified, a new id will automatically be generated by Iterable | No | STRING | | User Data | Updates user data or adds a user if none exists | Yes | OBJECT | | Event Data Fields | Additional event properties. | No | OBJECT | | Cart items | Individual items in the cart. Each item must contain \`id\`, \`name\`, \`price\`, and \`quantity\`. Extra values are added to dataFields. | Yes | OBJECT | | Total | Total order amount. | Yes | NUMBER | | Timestamp | Time the event took place. | No | DATETIME | | Campaign ID | Iterable campaign the event can be attributed to. | No | INTEGER | | Template ID | Iterable template the event can be attributed to. | No | INTEGER | ### Upsert User Creates or updates a user Upsert User is a **Cloud** action. The default Trigger is `type = "identify"` | Field | Description | Required | Type | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | Email Address | An email address that identifies a user profile in Iterable. | No | STRING | | User ID | A user ID that identifies a user profile in Iterable. | No | STRING | | New Email Address | The new email address to assign to the user. For single event processing, Segment makes a separate API call to set the new email address. Batch updating a profile email address is only supported for Hybrid projects. | No | STRING | | User Data Fields | Data to store on the user profile. | No | OBJECT | | User Phone Number | User phone number. Must be a valid phone number including country code. e.g. +14158675309 | No | STRING | | Merge Nested Objects | If you'd like to merge (rather than overwrite) a user profile's top-level objects with the values provided for them in the request body, set mergeNestedObjects to true. | No | BOOLEAN | | Enable Batching | When enabled, Segment will send data to Iterable in batches of up to 1001 | No | BOOLEAN | | Update Only | When enabled, Segment will only update existing users in Iterable. New users will not be created. This is only applicable when batching is enabled. Talk to your Iterable representative to enable this feature on the Iterable side. | No | BOOLEAN | ### Update Subscriptions \[Beta] This feature is in beta. Manage subscription preferences for a user, including subscribing and unsubscribing from channels, message types, and email lists. This integration is only supported on Iterable projects with opt-in Message Type Subscriptions and the Subscriptions API enabled. Update Subscriptions \[Beta] is a **Cloud** action. The default Trigger is `type = "track" and event = "Subscriptions Updated"` | Field | Description | Required | Type | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User Identifier | User identifier - provide email, userId, or both. At least one is required. | Yes | OBJECT | | User Identifier Preference | When both email and userId are provided, this determines which identifier is sent to Iterable. Iterable requires one or the other, not both. | Yes | STRING | | Subscription Preferences | Subscription changes to apply for this user. Maximum 6 items. | Yes | OBJECT | | Enable Batching | When enabled, Segment will send data to Iterable in batches. | No | BOOLEAN | ## Important differences from the classic Iterable destination Iterable supports multiple project types. To determine the appropriate identifier for your project type, refer to the list of available project types and their respective identifiers in Iterable's documentation: [Project Types and Unique Identifiers](https://support.iterable.com/hc/en-us/articles/9216719179796-Project-Types-and-Unique-Identifiers). ### Creating or Updating Users The method by which you identify users depends on the project type you use: #### Email-based Projects In email-based projects, it is necessary to include the email to successfully create a user in Iterable. Once both the email and `userId` have been set in Iterable, the `userId` can be utilized for any future user updates. #### UserID-based Projects For userID-based projects, a unique `userId` is required for creating a user in Iterable. While it is optional to add an email to a userID-based user profile, all subsequent user updates must be performed using the `userId`. #### Hybrid Projects In hybrid projects, you have the flexibility to choose between using a unique email or a `userId` to create a user in Iterable. The Iterable (Actions) destination doesn't automatically map the following context fields to Iterable user profiles during Identify calls (the classic destination did map them): * app * device * ip * locale * page * timezone To include these fields in user profiles, pass them as traits with Identify calls. This gives you more control and customization options for managing user data within Iterable. The integration also supports explicit mappings for updating the `phoneNumber` user profile field, as well as the `mergeNestedObject` boolean field in user update calls. ### Custom Events In UserID and Hybrid projects, when a passed `userId` doesn't match an existing user, Iterable creates a new user automatically. In email-based projects, tracking a custom event for an unidentified user will not create a user profile. To ensure proper user profile creation in email-based projects: * Call the Identify method with both a `userId` and an `email` to create a user profile. * After you create the user profile, proceed with tracking the custom event for that user. If you follow this approach, you can guarantee the creation of user profiles and accurately track custom events within Iterable for email-based projects. ### Commerce Events In the classic Iterable destination, cart updates were associated with Segment's `Product Added` and `Product Removed` events. In the Iterable (Actions) destination, custom events titled `Cart Updated` are routed to Iterable's Update Cart API instead.