# Iterable Destination ## Destination Info * Accepts [Page](/docs/segment/connections/spec/page), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls. * Refer to it as **Iterable** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object) * This integration is **partner owned.** Please reach out to the partner's support for any issues. ### Components * Server ## Connection Modes [Learn more about connection modes.](/docs/segment/connections/destinations/#connection-modes) ### Device-Mode * web: no * mobile: no * server: no ### Cloud-Mode * web: yes * mobile: yes * server: yes When you enable the Iterable destination from the Segment app, your data starts flowing into Iterable, where it can trigger workflows and make data available for analytics. You can find or generate your Iterable API key by going to Integrations → API keys inside the Iterable app. ## Identify When you call `identify` with one of Segment's sources, Segment calls Iterable's [update user endpoint](https://api.iterable.com/api/docs#users_updateUser), to add data for that particular user. You can also call `identify` to update user fields. Iterable keys users by `email` or a user ID. This user ID will be the Segment `userId` if sent. To use a Segment `userId` for identify calls, first call identify with both a `userId` and `email`. Iterable won't accept the request and throws an error if you fail to send one of either the `userId` or `email`. > \[!NOTE] > > You must send the `email` parameter to Segment as `email`. The `email` value can't be passed in with any other key name in the payload. Sending `email` in with a different key name (for example, `customer_email`, `mail`) will not allow Iterable's processes to understand that key holds the `email` value you want to use. The same condition applies to the `userId` field. Using keys other than `email` and `userId` cause payloads to be silently rejected by Iterable. If you send `phone` in traits, Iterable performs checks on the phone number before showing them User Profiles. Read more about [Iterable's phone number field](https://support.iterable.com/hc/en-us/articles/211970843-SMS-Overview-#contact-phone-numbers). ## Track When you call `track` with one of Segment's sources, Segment calls Iterable's [track API endpoint](https://api.iterable.com/api/docs#events_track), and send over the event properties as the data fields in the request. The name of the `track` event appears as a Custom Event in Iterable, and will be available to trigger workflows, segment users, and view analytics. If a user does not already exist in Iterable, calling `track` for a user event will add that user into the system. You can track with either an `email` or userId (if a `userId` exists for that email). > \[!NOTE] > > You must send the `email` parameter to Segment as `email`. The `email` value can't be passed in with any other key name in the payload. Sending `email` in with a different key name (for example, `customer_email`, `mail`) will not allow Iterable's processes to understand that key holds the `email` value you want to use. The same condition applies to the `userId` field. Using keys other than `email` and `userId` cause payloads to be silently rejected by Iterable. ### Example steps: First `track` event with `userId` and `email`; user will be created Subsequent `track` with `userId` > \[!NOTE] > > If you send an ISO formatted date field in your events, Segment converts it into UTC to conform to standard Iterable format: `yyyy-MM-dd HH:mm:ss ZZ` (for example, `2023-02-05 20:42:10 +00:00`). Iterable has a specific date format that must be used to segment a field by date. Read more about Iterable date field in the [Field Data Types](https://support.iterable.com/hc/en-us/articles/208183076-Data-Field-Types-in-Iterable#date) documentation. ### Ecommerce Iterable also supports Segment's [ecommerce events](/docs/segment/connections/spec/ecommerce/v2/). This works just as you would expect, using the `track` method. Iterable has one important difference from the Segment Ecommerce spec. If you use the `Product Added` / `Product Removed`/ `Order Completed` events, you must include the "products" field with the cart info, as in the `Order Completed` example event. You must include [all required fields for the Purchase events in Iterable](https://api.iterable.com/api/docs#commerce_trackPurchase). This includes the total value of the purchase as `total` (best as a float, double, and possibly an integer), and an array of objects called `products`. Each product must include an `id` or `productId` as a string, and a `name`, `price`, and `quantity` on each product object in the array. These are used to map to Iterable's expected `items` array. An example might look like this: ```js analytics.track("Order Completed", { total: 100.00, products: [ { product_id: '507f1f77bcf86cd799439011', name: 'Monopoly: 3rd Edition', price: 19, quantity: 1 }, { product_id: '505bd76785ebb509fc183733', name: 'Uno Card Game', price: 3, quantity: 2 } ] }); ``` ## Page Calling `page` to track pageviews registers as a custom event in Iterable. If you have a page called "shoppingCart" the custom event is be called "shoppingCart page" in Iterable. If a user does not already exist in Iterable, calling `page` for a user event adds that user to the system. Be sure to pass in the `email` the first time you call page for a user, since Iterable identifies users by `email`. After the first time, you can call page with `userId`. ### Example steps: Call `page` with `userId` and `email`; if with `email` and the `email` doesn't exist, the user will be created. ## Sending Email Data from Iterable Iterable supports sending [email events](/docs/segment/connections/spec/email/) to other tools on the Segment platform. These events are sent as `track` calls to the other destinations you enabled. To enable this feature, go to Destinations, Third Party, and select Segment in the Add Destinations button. Then, enter your API key. ![The Enable syncing to Segment window in Amplitude.](https://docs-resources.prod.twilio.com/8f6999086be7c8c5d66002ce7c7dd99e94fccc02822149d1dbce4257dbeeb26c.png) ## Sending Push Notification Data from Iterable Iterable supports sending push notification events to Segment. These events are sent as `track` calls to the other destinations you've turned on. Push events are automatically enabled once the [Email Source](/docs/segment/connections/sources/catalog/cloud-apps/iterable/) is enabled. They support the following events: `Push Delivered`, `Push Bounced`, `Mobile App Uninstalled`, `Push Opened` ## High retry rate If you're experiencing a large amount of retries within your destinations that are connected to your HTTP API source, this could be due to Etimedout errors. Etimedout errors are intermittent problems that can come about when HTTP requests are made from server to server. The Etimedout error is the result of an HTTP response not being received in a specific timeframe. [Learn more](/docs/segment/connections/destinations/#retries-between-segment-and-destinations) about how Segment retries events to destinations. ## Using Iterable with Engage Iterable is a marketing platform that can accept Engage information. You can send Iterable the computed traits and audiences you create in Engage, so you can use the data to power email, push and SMS campaigns. You can set a "lookback window" for both computed traits and audiences, which limits the period of time in which data is considered when calculating the trait or audience. For example, you might set a lookback window of 7 days on an audience or trait like `new_users_7_days`, but you would not add a lookback window to a trait that isn't time-bounded, for example `lifetime_value` . When you specify a lookback window, Engage updates the audience or trait hourly. If you do not specify a lookback window, Engage continuously updates both computed traits and audiences in real time. ### Using Computed Traits with Iterable You can send Computed Traits created in Engage as `identify` calls to create user properties in Iterable. ![Profile showing computed traits with courses clicked count as 11.](https://docs-resources.prod.twilio.com/228d7f5d4a5e34a0ad89c667e6673113f6d833e9f1547b3ad1459c28de8d8efb.png) From the Iterable UI, you can check a specific user profile for Computed Traits by going to **Audience → Contact Lookup**. Engage updates user profiles that contain an `email` or `userId`. ![Iterable user profile showing Event History with 'Audience Entered' event details.](https://docs-resources.prod.twilio.com/7f9a3b77feaf5faeeb14564083bd698e35d141fc8fed9546ce5410991979c837.png) Computed traits without a lookback window search across all historical events and update in real time. Computed traits with a lookback window only search across events that occurred within the specified timeframe. Computed traits *with* a lookback window are updated hourly. ![Configure and Preview Your Trait aggregation settings with the lookback window set to 7 days.](https://docs-resources.prod.twilio.com/ce8419bf55ade6d1d910080f0b2a26ec6d486abd5ac415529baf9fc1f0f9994f.png) ### Using Audiences with Iterable You can send Engage Audiences to Iterable as `identify` or `track` calls. You can choose the type of call to send when you add Iterable as a destination for an audience. Engage sends updates to Iterable for users who have a known `email` or `userId`. ![Iterable settings page with options for Send Identify, Send Track, Enter Event, and Exit Event.](https://docs-resources.prod.twilio.com/ff23b8501d5970d7915ac3967ceb400843b809b9e47f2bd5823b20568859c059.png) #### Audiences using Identify Calls When you send Audiences as `identify` calls, Engage adds a trait matching the name of the audience to the user's profile, with a boolean value to indicate if the user is in the audience. For example, when a user first completes an order in the last 30 days, Engage sends an `identify` call with the property `order_completed_last_30days:` `true`. When the user no longer satisfies these criteria (for example when their last purchase was more than 30 days ago) Engage sets that value to `false`. ![Audience tab showing 'Order Completed Last 30 Days' with identifier 'order\_completed\_last\_30days'.](https://docs-resources.prod.twilio.com/018c318acd619b15f76b9c617456126fcf230d9bf3913221b8f8ac656795bef9.png) You can check a specific user profile for Audience membership in the Iterable UI by going to **Audience → Contact Lookup**. ![Manage user profile details with options for identify calls, context traits, and properties.](https://docs-resources.prod.twilio.com/8d9bd3d46cad003afaadb96a264f87f4751ff1400695f80f086d94dbeb04bcf1.png) When you first create an audience, Engage sends an `identify` call for every user in the audience. Later syncs only send updates for users who were added or removed from the audience since the last sync. #### Audiences using Track Calls When you use `track` calls, Segment sends an Audience Entered event when the user enters the audience, with the audience name as a property of the event. When the user exists the audience, Engage sends an Audience Exited event with the same property. ![Segment Audience Explorer showing events for Sherry Bobbins with details of an Audience Entered event on March 19, 2020.](https://docs-resources.prod.twilio.com/f21487fe4b243890b64db5ade39fbedb7af8fe342b62070a1275577d6349a51f.png) You can check a specific user profile for an Audience event in the Iterable UI by going to **Audience → Contact Lookup→ Event History** tab. ![A user profile in Iterable with the Event History tab selected.](https://docs-resources.prod.twilio.com/4b81fc57d949cef7aba34ebd7fb90a49c7111ff6b3af56fd7a032206854b7905.png) Audiences without a lookback window search across all historical events, and update in real time. Audiences with a lookback window only searches across events that occurred within the specified timeframe. Audiences *with* a lookback window are updated hourly. ![Segment Audience builder showing lookback window set to 7 days for order completion.](https://docs-resources.prod.twilio.com/949437fc97c9363f36dc529e3a11a0fb755516537cb8731943bc3a943d4f3a9d.png) ## Setting Up Engage and Iterable To send computed traits or audiences to Iterable, you first must connect it to your Engage space. Once it's set up, you can select Iterable as a destination for Engage data when you create computed traits or audiences. 1. In your Segment workspace, click Engage in the left navigation bar, and select your Space. 2. Click **Engage Settings** and select the **Destinations** tab. 3. Click **Add Destination**. 4. Search for **Iterable** and add the destination to your Space. 5. On the set up screen, enter in your API Key for the Iterable. ## Iterable Engage Details * **Engage Destination type**: Event Method (data is delivered to this Destination one-by-one on a realtime basis) * **Traits and Audiences created by**:You can add traits and audiences as user properties using `identify` calls. You can send audiences as `Audience Entered` or `Audience Exited` `track` calls with the audience name as an event property. * **Must create audience\_name field before Engage can update those values?**: No. If you send the audience as an `identify` call, Engage automatically creates the computed trait or audience name as a user property. * **Computed trait appears as**: A lower case user property with the spaces converted to underscores. * **Audience appears as**: When you send Audiences as an `identify` call, Engage creates a lower case boolean user property using the audience name with spaces converted to underscores. When you send Audiences as a `track` call, Engage sends `Audience Entered` and `Audience Exited` events, with the audience name as an event property. * **Destination rate limit**: If sending traits and audiences as `identify` calls, 500 requests/second, per project. If sending audiences as `track` calls, 2000 requests/second, per project. * **Lookback window allowed**: Unlimited * **Identifiers required** : `userId` or `email` * **Identifiers accepted** : `userId` and `email` * **Client or Server-Side Connection**: Server-side ## Iterable Engage FAQs #### What happens if I delete an audience or trait in Segment? When you delete an audience or trait in Segment it is not deleted from Iterable. You cannot delete properties in Iterable, but you can hide them from the Iterable UI by going to your Iterable project settings. #### If a user has multiple email addresses as external ids in Segment, what happens when they enter an audience or have a computed trait? Segment sends an `identify` or `track` call for each email address on the user's account. For example, if a user has three email addresses, this creates three separate users in Iterable. ### Are you able to update a user's email through Iterable? Updating a user's email in Iterable is currently not possible with Segment. You will have to call updateEmail outside of Segment if you want to be able to do so: Updating a user's email address cannot be achieved with the standard Segment identify call alone. It requires sending an Update Email Request directly to the Iterable API from outside the Segment platform. The API request outlined in Iterable's [Update user email](https://api.iterable.com/api/docs#users_updateEmail) docs. This needs to be followed in order to ensure Iterable has the correct email address for any users who have updated their email address. A workaround to update an email in Iterable from Segment would be to hit that API endpoint using a destination function. ## Settings Segment lets you change these destination settings from the Segment app without having to touch any code. | Field | Description | Required | Type | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | API Key | You can find your iterable API key under your "API Configuration Settings". It should look something like this: 42f187310705012194bd0bd694905664ae. | Yes | string | | Map All Pages to Single Event Name | When sending a page or screen event, always use the same Iterable "Event Type". The other page-related settings, i.e. "Track All/Categorized/Named Pages", are still relevant -- they determine whether an event will be sent to Iterable at all. Pages will be sent as "Loaded a Page". Screens will be sent as "Loaded a Screen". | No | boolean | | Track All Pages | Send an event for every page or screen event. | No | boolean | | Track Categorized Pages | Send an event for every page or screen with a category. | No | boolean | | Track Named Pages | Send an event for every page or screen with a name. | No | boolean |