Iterable Destination

Destination Info
Components
  • Server
Connection Modes
Device-mode Cloud-mode
Web Web
Mobile Mobile
Server Server
Partner Owned
  • This integration is partner owned. Please reach out to the partner's support for any issues.

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, 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.

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.

Track

When you call track with one of Segment’s sources, Segment calls Iterable’s track API endpoint, 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).

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

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 documentation.

Ecommerce

Iterable also supports Segment’s ecommerce events. 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. 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:

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 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.

Send email events from Iterable.

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 is enabled.

They support the following events: Push Delivered, Push Bounced, Mobile App Uninstalled, Push Opened

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.

A screenshot of a profile in Segment, with the Traits tab selected.

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.

A screenshot of a user profile in Iterable.

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.

A screenshot of the Segment Configure and Preview Your Trait screen.

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.

A screenshot of the Iterable settings page in Segment, with a defined Enter Event and Exit Event.

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.

A screenshot of the Audience tab in Segment.

You can check a specific user profile for Audience membership in the Iterable UI by going to Audience → Contact Lookup.

A screenshot of the Contact Lookup page in Iterable.

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.

A screenshot of Segment's Audience Explorer with an Audience Entered event.

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.

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.

A screenshot of the Segment audience builder.

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 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.

Setting Description
API Key
(required)
string. You can find your iterable API key under your “API Configuration Settings”. It should look something like this: 42f187310705012194bd0bd694905664ae.
Map All Pages to Single Event Name boolean, defaults to TRUE .

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”.
Track All Pages boolean, defaults to FALSE .

Send an event for every page or screen event.
Track Categorized Pages boolean, defaults to TRUE .

Send an event for every page or screen with a category.
Track Named Pages boolean, defaults to TRUE .

Send an event for every page or screen with a name.

This page was last modified: 09 Aug 2024



Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account