Articles in this section

See more

Building an Iterable Integration

This document describes various considerations to keep in mind as you're building an Iterable integration.

In this article

Planning

As you get started building an integration, it's a good idea to consider the following questions:

  1. What problem will the integration solve?
  2. How will you gauge your integration's success?
  3. How will the integration interface with Iterable (APIs, webhooks, etc.)? Which endpoints will it call? What data will it need to include in each request?
  4. Which of your customers will adopt this integration?
  5. How will you test and maintain the integration?
  6. What is your go-to-market strategy?

Connecting your platform to Iterable

Next, you'll need to consider how your platform will connect to Iterable. You'll have access to the same tools that Iterable's customers use: Iterable's API, webhooks, data feeds, and other tools like HTML code blocks:

  • Iterable's API is publicly available, and it can be accessed with project-specific API keys. To learn more, read:

  • Webhooks allow you send data from Iterable to external systems. There are two kinds of webhooks:

    • System webhooks are triggered by the creation of system event data (email sends, link clicks, etc.) in Iterable.

    • Journey webhooks are configured in journey tiles.

      Customers can configure webhooks inside of their Iterable projects. However, it's not possible to use Iterable's API to configure webhooks.

  • Data feeds allow Iterable campaigns to query data from an external system, at send time, on a per-user basis.

Iterable's API

When you need to send data from your platform to Iterable, consider using Iterable's API. Most of our existing partner integrations use at least one of the following endpoints:

  • POST /api/users/update

    Creates a new user or updates an existing user's Iterable profile.

    Example use case: Tealium's JavaScript SDK captures new user signups on customer websites. Then, it uses the captured email addresses (and other attributes) to create new users in Iterable. Then, these users are available to go through Iterable journeys (for example, a welcome series).

  • POST /api/events/track

    Creates an event in Iterable, capturing all relevant attributes.

    Example use case: Radar identifies when a user, after making a "buy online, pick up in store" purchase, has entered the geo-tagged location of a physical retailer. Radar captures this information as a custom event and then passes it to Iterable in real time (along with all relevant information). This event kicks off an Iterable journey that sends the user a series of messages, instructing them where and how to get their item.

  • POST /api/lists/subscribe and POST /api/lists/unsubscribe

    Adds or removes users to/from an existing list in Iterable.

    Example use case: In Iterable, a list is a group of users to whom you'd like to send messages, and subscribing/unsubscribing users to/from these lists can trigger other actions. For example, a dynamic report in Mixpanel might export users to a list in Iterable, causing a journey to run for each.

  • POST /api/users/bulkUpdate

    Bulk updates or creates users. Best for large updates that aren't time-sensitive.

    Example use case: Workato's Iterable integration can sync new Salesforce users to Iterable on a daily basis.

  • POST /api/commerce/updateCart

    A dedicated e-commerce endpoint for updating the shoppingCartItems on an Iterable user profile.

    Example use case: When the status of a user's cart changes on a customer website, Shopify can call this endpoint, which can trigger a journey.

  • POST /api/commerce/trackPurchase

    A dedicated e-commerce endpoint for tracking user purchases.

    Example use case: When a customer makes a purchase, Shopify can call this endpoint, which can trigger a journey. For example, it might trigger a "Thank you for your purchase!" message that includes discounts for other items.

  • Various template creation/updating endpoints:

    Many of our more sophisticated and/or enterprise customers use platforms that streamline the creation of message templates, often across teams. These platforms sometimes provide a way to export templates to Iterable, which is done by calling this API.

    Example use case: A marketing team might use Taxi for Email to create and approve a new seasonal email template. Then, they export this template into their Iterable project and use it for a blast campaign about their new fall clothing line.

NOTE

The response to each upsert endpoint includes a templateId, which you can use (along with the locale, if needed) to make future updates to the same template.

Webhooks

Webhooks provide a way to send data from Iterable to other systems. There are two kinds of webhooks: journey webhooks (called from journey tiles), and system webhooks (triggered for each occurrence of selected system events).

To learn more about webhook rate limits in journeys, read Call Webhook tiles.

System webhooks

Iterable creates system events automatically, at various points: when a user opens a message or clicks a link that it contains, when a message isn't sent to an intended recipient (a send skip), etc. System webhooks send this data to an external endpoint of your choosing, in real time.

NOTE

System webhooks send system events (defined by Iterable), not custom events (define as our customers).

Example use case: Fivetran maps an Iterable system webhook to their endpoint, allowing Iterable to send them system event data. Fivetran ingests the system events, transforms them, and then forwards them to a data warehouse (like Snowflake) for BI.

Journey webhooks

Journey webhooks send data from Iterable to external servers (your own, or third-party) as part of a journey.

Example use case: Some customers may want to send direct mail from their journeys. To do this, they can send journey webhook calls to Inkit, including all of the info needed to populate the content of the direct mailer, as well as the address of the recipient.

Update user profile journey webhooks

An update user profile webhook is a special kind of journey webhook that makes a GET request to an external server, and then uses the response to update the related Iterable user profile.

Example use case: To fetch an up-to-date lead score from Faraday, a journey can use an update user profile journey webhook. After the webhook fetches the data fro Faraday and saves it in Iterable, a message template can use it as needed.

Data feeds

Data feeds allow templates to fetch data from external services. This data, queried individually for each user when a campaign is being sent, can be used to personalize the message content.

Example use case: An Iterable template might reference data stored in Lytics. To access this data, it can use a data feed, which calls out to Lytics for each user in a campaign.
The template can then use the returned data to customize the content however needed.

HTML code blocks

Custom HTML code blocks can be used to insert dynamic content into an Iterable template.

Example use case: Movable Ink image tags insert dynamic images and content into an Iterable message at send-time.

Testing and maintaining your integration

As you build and maintain your integration, it's important to ensure quality and consistency:

  1. To make sure everything works as expected, test your integration in a sandbox environment.
  2. Provide comprehensive documentation (setup, configuration, usage).
  3. Keep track of version changes and code modifications in a version control system like GitHub.
  4. Monitor your integration's health, and keep up-to-date with updates in Iterable.

Have questions? Need help?

To learn more about Iterable, check out our documentation. And, if you have questions, reach out to partners@iterable.com.

Related articles