Iterable

Run better email, push, and SMS campaigns on Iterable with up-to-date customer data from your data warehouse

Supported syncing

Connect to Iterable

Go to the Destinations overview page and click the Add destination button. Select Iterable and click Continue. You can then authenticate Hightouch to Iterable with an Iterable API key and Project Type Identifier.

You can follow Iterable's instructions for how to create an API key. Your API key needs to have server-side permissions.

To see your project type identifier, go to Settings > Project Settings and see the identifier(s) underneath the project's cluster ID.

Check out Iterable's docs for more information.

Sync configuration

Once you've set up your Iterable destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Iterable destination you want to sync to.

Syncing users

Sync Iterable users and user properties with data from any source.

Record matching

You can either use email or user ID to match rows from your model to users in Iterable. In general, it's best to select the one that corresponds to the project type you selected when first setting up your Iterable instance.

There's one exception when you shouldn't match your record matching column to your project type: If you have an email-based Iterable project and you're using update mode, selecting user ID for record matching can increase sync speed.

You should do this if you're confident that your user IDs are unique. (In email-based projects, Iterable doesn't require uniqueness for user IDs.) Ensure you set your project identifier appropriately.

If you select user ID for record matching in email-based projects, Hightouch uses the bulk user update endpoint with the preferUserId parameter. The preferUserId parameter dictates whether new users should be created if the request includes a userId that doesn't yet exist in the Iterable project. This allows Hightouch to update only existing users without first having to perform a lookup.

Iterable only respects the preferUserId parameter in API calls for email-based projects. For more information on how Iterable's API works differently according to project-type, refer to Iterable's docs.

Field mapping

You can sync columns from your model to Iterable user's data fields. If you send data for a custom field that doesn't exist, Hightouch adds the field and automatically detects its type.

Nested objects and object arrays

Iterable supports user and event fields containing JSON objects or arrays of objects. These objects and object arrays are commonly used to support "entities" related to each user—for example, devices, medications, pets, etc.—especially when marketing communication needs to include metadata about these related entities.

For example, say you want to sync an array of a customer's pets to be an attribute named pets in Iterable:

{
    "email": "docs@hightouch.com",
    "dataFields": {
        "pets": [
          {
            "name": "Nacho",
            "color": "Ginger",
            "age": 1,
            "favoriteToy": "Fuzzy spring"
          },
          {
            "name": "Rami",
            "color": "Brown Tabby",
            "age": 2,
            "favoriteToy": "Feather wand"
          }
        ]
    }
}

Hightouch's inline mapper is purpose-built to create nested JSON objects and arrays like this. Refer to the data format requirements and array creation instructions for details.

Delete behavior

You have these options for how to treat records that leave your model's query results:

Syncing events

The integration lets you sync custom events, purchase events, and updateCart events to Iterable. This section describes custom and purchase events. Skip to the syncing update shopping cart items events for more information on this sync type.

When syncing custom and purchase events, the integration inserts new events into Iterable and lets you modify existing events as long as you provide their event ID.

Event name

Providing an event name is required to send an event to the Iterable API. You can either provide a static value or select to use a column from your model. Hightouch syncs the static or column value as the eventName body parameter the API requires.

Event timestamp

You can optionally select a column that contains timestamps of when events occurred. If this field is empty, Iterable uses the time the event arrives at the server.

Additional track configuration

You can also optionally include this information as part of your event information:

• Name of the campaign associated with the event: choose a static value or select to use a column from your model.
• Event template: choose a static value or select to use a column from your model.
• Event ID: select a column from your model. You must include this configuration if you want to modify existing events.

If you don't select a column from your model to map as the event ID, Hightouch considers it a new event and Iterable generates a new event ID.

Field mapping

You can use field mapping to add context to your events. You must include either an email or user ID in your mappings. Which you include depends on how your project identifies users. If you provide both email and user ID, your project type takes precedence. The integration uses these fields for identifying the user associated with this event.

For purchase events, you also need to provide the shopping cart items as Items and the Total order dollar amount in your mappings.

You can also include event data fields, including custom ones. Hightouch sends any custom fields you include as part of the in the dataFields property of event's body.

Updating shopping cart items

This sync mode both updates the shoppingCartItems field on a user's profile and tracks updateCart events in Iterable. The integration inserts new events into Iterable when they first appear in your query results.

Field mapping

You must include shopping cart items as Items and either an email or user ID in your mappings. Which you include depends on how your project identifies users. If you provide both email and user ID, your project type takes precedence. The integration uses these fields for identifying the user associated with this event.

You can also include user data fields for the user who updated their cart.

Syncing catalogs

You can keep your Iterable catalogs up-to-date with Upsert mode. Begin by selecting the Iterable catalog you want to sync items to.

Record matching

To match rows from your model to catalog items, you need to select the model column that contains values that match the Unique Product ID field. Refer to the record matching docs for more information.

Field mapping

Once you've selected a catalog, Hightouch automatically pulls existing fields from your Iterable catalog for you to map data into.

Delete behavior

You have these options for how to treat records that leave your model's query results:

Syncing segments

Sync audiences into your Iterable static lists of users. Hightouch automatically removes users from the Iterable list when they leave the query result.

User identifers

To identify which contacts to add or update in a segment, select a model column and the corresponding Iterable field. You can match on either Email or User ID.

It's best to select the one that corresponds to the project type you selected when first setting up your Iterable instance. If you provide both email and user ID, your project type takes precedence.

Field mapping

You can sync columns from your model to user's default and custom data fields. If you send data for a custom field that doesn't exist, Hightouch adds the field and automatically detects its type.

Create or use an existing list

Your can create a new list or select an existing one. If you choose to create a new list, Hightouch creates it on the initial sync run and then keeps it updated on existing sync runs.

You can provide a name for the new list, or Hightouch defaults to the name of the model used to create the sync.

Updating user email addresses

Use this sync mode to update existing users' email addresses in email-based projects.

To update an email in a userID-based or hybrid project, use the user sync type.

Record matching

You can use either email or user ID to match rows from your model to users in Iterable, regardless of your Iterable project type. If you match by email, the update call is only made the first time the record appears in your query results. Matching by user ID updates the email the first time the record appears in your query results and every time changes are detected.

Field mapping

The only field you can include in field mapping is the new email. If you want to update other user data fields, use the user sync type.

User API actions

Hightouch lets you perform the following actions on your Iterable users:

• Delete
• Forget
• Unforget

Record matching

You can either use email or user ID to match rows from your model to users in Iterable. It's best to select the one that corresponds to the project type you selected when first setting up your Iterable instance.

Tips and troubleshooting

Unset project identifier

Before March 2023, Hightouch didn't require you to set your Iterable project identifier when connecting to Iterable. Setting it may enhance sync performance if you're using update mode with the users sync type for an email-based project. See the record matching section for more information.

You can set the project-type from the configuration tab of your Iterable destination in Hightouch.

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to reach out. We're here to help.

Fewer records in Iterable than synced

If you see a discrepancy between the number of records that have passed through your sync and the number of records displaying in Iterable, check your data set for duplicates. Iterable automatically dedupes records based on primary key so the number of records in Iterable might be less than the number of records in your Hightouch sync if your sync unintentionally contains duplicates.

413 - Request Entity Too Large

If you see this error or notice that your syncs are slow, you can try lowering the batch size in your sync configuration.

400 - Request does not have the same data types as the data previously submitted

The full error message looks something like this:

{
  "msg":"Project 13691: The request does not have the same data types as the data previously submitted, or the input value is not within the correct range. Field 'date_field' already exists for type 'user' and has a data type of 'date' but possible types 'string, keyword' in the request.",
  "code":"RequestFieldsTypesMismatched",
  "params":
    {
      "validationErrors":
        {
          "date_field":
            {
              "incomingTypes":["string","keyword"],
              "expectedType":"date",
              "category":"user",
              "offendingValue":["2023-04-19 12:15:30","0000-00-00 00:00:00"],
              "_type":"UnexpectedType"
            }
        }
    }
}

The first value in the offendingValue array is associated with the first record in the batch sent to Iterable. The second value in the array is the value causing the issue. One instance of this value ("0000-00-00 00:00:00") causes the entire batch of records being sent to Iterable to fail.

To resolve the error, check for instances of ("0000-00-00 00:00:00") in the date_field column of your model and replace these values with null or a valid date.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.