Connect Iterable to AI Agents: Sync Catalogs and Automate Flows

You want to connect Iterable to an AI agent so your system can autonomously sync product catalogs, update user profiles, trigger marketing journeys, and manage omni-channel campaigns based on real-time data. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom integration from scratch.

Giving a Large Language Model (LLM) read and write access to your marketing automation platform is an engineering challenge. You either spend sprints building, hosting, and maintaining a custom API connector, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Iterable to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Iterable to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Iterable, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex marketing automation workflows. For a broader look at this design pattern, read our guide on Architecting AI Agents: LangGraph, LangChain, and the SaaS Integration Bottleneck.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a line of integration code, decide what layer your AI agent talks to. This choice determines how safe your production system will be.

Direct API tools - mapping one tool per raw Iterable endpoint - look convenient initially. But they push provider-specific quirks directly into the LLM's context window. The model has to remember exactly how Iterable formats dates, how it handles custom fields, and the exact payload structures for triggering journeys. Every one of those quirks is a hallucination waiting to happen.

A unified tool layer collapses these complexities behind a consistent, predictable schema. Your agent sees stable, descriptive functions like create_a_iterable_user, create_a_iterable_event, and iterable_catalog_items_partial_update. That gives you concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only ever chooses from a stable list of function names and predictable arguments. It never invents proprietary payload fragments.
2. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments are rejected before they hit the marketing platform, meaning a broken tool call fails fast instead of corrupting a production campaign.
3. Decoupled reasoning. The LLM spends its token limit reasoning about the user's intent - like "this user abandoned their cart, trigger the recovery flow" - rather than guessing how to format a nested JSON object for the Iterable API.

The Engineering Reality of the Iterable API

Giving an LLM access to external data sounds simple in a local prototype. You write a standard Node.js function that makes a fetch request and wrap it in an @tool decorator. In production against complex marketing systems like Iterable, this approach collapses.

Iterable's API introduces several specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

The Type-Locking and Field Limit Trap

Iterable allows you to attach custom data fields to user profiles and events. However, there is a hard rule: once a data field is created, its type is locked globally across the entire project. If a previous request sent "lifetime_value": 100 (an integer), and your LLM hallucinates a string and sends "lifetime_value": "100", Iterable will reject the payload or fail to update the field.

Furthermore, Iterable imposes a soft limit - defaulting to 1,000 unique fields per user profile. If an LLM is allowed to arbitrarily generate keys for custom properties, it will quickly exhaust this limit, causing subsequent valid updates to fail with a 400 Bad Request. Your tool layer must strictly enforce which custom fields an agent is allowed to touch, using predefined JSON schemas, to prevent the LLM from polluting the project's data dictionary.

Asynchronous Race Conditions

Iterable processes certain high-volume endpoints asynchronously. For example, when updating a user profile via POST /api/users/update, processing time varies based on the current load of Iterable's back-end services.

If your AI agent updates a user's preference and immediately fires a dependent request - like sending a targeted email using create_a_iterable_email_send based on that new preference - you will hit a race condition. The email might go out before the user profile update finishes processing. Iterable explicitly advises providing a buffer of at least 60 seconds between updating a user profile and triggering dependent messaging. Your agent framework needs to understand these temporal constraints, either by implementing explicit waits or relying on webhooks to confirm state changes.

The Identity Routing and Character Encoding Quirk

Iterable identifies users by either email or userId. Depending on how your specific Iterable project was configured during setup, it might be an email-based project, a userId-based project, or a hybrid project.

If your agent tries to use an endpoint like delete_a_iterable_user_by_id using an email address on a userId-based project, the request will fail. More insidiously, if an identifier contains a forward slash (/), which is common in complex internal IDs, appending it as a path parameter (e.g., /api/users/{email}) breaks standard HTTP routing. Iterable's documentation explicitly notes this quirk, requiring you to shift to alternate endpoints or pass the identifier in the request body. A unified tool layer abstracts this routing logic away from the LLM, ensuring the correct endpoint and parameter placement is used based on the identifier type.

Fetching AI-Ready Tools for Iterable

Truto provides a set of tools for your LLM frameworks by offering a description and schema for all the Methods defined on the Resources for an integration. We then call the /tools endpoint on the Truto API to return all of these Proxy APIs with their descriptions and schemas, creating Tools that LLM frameworks can natively consume.

Every integration on Truto is essentially a comprehensive JSON object that represents how an underlying product's API behaves. Integrations have Resources, which map to the endpoints on the underlying product's API. These Resources have Methods defined on them, such as List, Get, Create, Update, Delete, and custom operations like "Send Email".

These Methods act as Proxy APIs. Truto handles authentication and query parameter processing, returning data in a predefined format. For AI agents, these Proxy APIs handle data normalization automatically using the raw data from the underlying product's APIs.

To fetch these tools, you need the integrated account ID for your connected Iterable instance. You can then retrieve the tools programmatically:

curl -X GET "https://api.truto.one/integrated-account/{integrated_account_id}/tools?methods[0]=read&methods[1]=write" \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY"

If you are building in TypeScript with LangChain, the @trutohq/truto-langchainjs-toolset package handles this entirely. You instantiate the tool manager, fetch the tools, and bind them to your model.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
// Initialize the LLM
const llm = new ChatOpenAI({
  modelName: "gpt-4o",
  temperature: 0,
});
 
// Initialize the Truto Tool Manager with your integrated account ID
const toolManager = new TrutoToolManager({
  integratedAccountId: "acc_abc123",
  trutoApiKey: process.env.TRUTO_API_KEY,
});
 
// Fetch the tools specific to Iterable
const tools = await toolManager.getTools();
 
// Bind the tools to the LLM
const llmWithTools = llm.bindTools(tools);

Handling Rate Limits in Production

When building autonomous agents, rate limiting is a critical infrastructure concern. Iterable has strict rate limits, such as 100 requests per second for standard user updates, but tighter limits for specific exports or bulk operations.

Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Iterable API returns an HTTP 429 Too Many Requests, Truto passes that exact error back to your caller. However, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification: ratelimit-limit, ratelimit-remaining, and ratelimit-reset.

Your agent framework or underlying HTTP client is fully responsible for catching the 429 error, reading the ratelimit-reset header, and applying the appropriate sleep or backoff strategy before allowing the agent to continue. Do not expect the infrastructure to absorb these limits silently; your agent loop must handle them explicitly.

Hero Tools for Iterable Agents

Exposing the entire Iterable API to an LLM at once consumes too much context and degrades reasoning performance. Instead, you filter the tools endpoint to return high-leverage operations. Here are the core hero tools that enable the most powerful marketing automation workflows.

create_a_iterable_user

This tool updates user data or adds a new user if one does not exist. It merges data, meaning omitted fields are not deleted. This is the primary entry point for syncing profile data, preferences, and custom attributes from your agent into Iterable.

"Find the user with email j.doe@example.com and update their profile to set 'subscription_tier' to 'premium' and 'ltv' to 1500."

create_a_iterable_event

Custom events are the lifeblood of Iterable journeys. This tool tracks a specific action a user took, which can then trigger workflows, increment counters, or enter users into specific segments. Remember the type-matching rule: identically named data fields must be of the same type across events.

"Log a 'CourseCompleted' event for userId 84729. Include the custom fields 'course_name' as 'Advanced React' and 'score' as 95."

iterable_catalog_items_partial_update

Catalogs in Iterable allow you to store non-user data, like product inventories, restaurant menus, or content libraries, which can be referenced dynamically in email templates. This asynchronous tool creates or updates an item in a specific catalog without overwriting unmentioned fields.

"Update the item 'prod_884' in the 'SummerApparel' catalog. Set the 'inventory_count' to 12 and reduce the 'price' to 29.99."

create_a_iterable_journey_trigger

This tool forcefully triggers a journey (formerly known as a workflow) for a specific user or list. This is crucial for agents that evaluate complex external conditions before deciding a user needs to enter a specific marketing flow.

"Trigger the journey with ID 59281 for the user with email alex@example.com. They just passed our internal VIP threshold."

create_a_iterable_email_send

Sometimes an agent needs to bypass complex journeys and send a specific, transactional email immediately. This tool sends an email to a specific address, allowing request data fields to override standard user profile data fields specifically for this one send to resolve field collisions.

"Send the email campaign ID 4432 to m.smith@example.com. Inject the custom field 'verification_code' with the value '883921'."

update_a_iterable_subscription_group_user_by_id

Managing consent and preferences is critical for compliance. This tool subscribes a single user to a specific subscription group, ensuring that they receive the correct categories of messages.

"Subscribe the user with email partner@example.com to the subscription group ID 102, which is our monthly newsletter."

To view the complete inventory of available tools, endpoint schemas, and required parameters, visit the Iterable integration page.

Workflows in Action

With the tool layer configured, you can combine these atomic operations into complex, autonomous workflows. Here is how an agent orchestrates multi-step marketing operations.

Scenario 1: AI-Driven Cart Abandonment Recovery

Standard cart abandonment flows rely on rigid time delays. An AI agent can evaluate a user's purchase history and inventory levels to trigger a highly personalized recovery flow.

"Check our internal database for abandoned carts over the last hour. For user brian@example.com, verify if the item 'Coffee Grinder X1' is still in stock. If it is, log an abandonment event and trigger the high-intent recovery journey."

1. The agent queries an internal database (via a custom internal tool) to find the abandoned cart data.
2. The agent uses get_single_iterable_catalog_item_by_id to verify the inventory count in the 'Products' catalog.
3. Confirmed in stock, the agent calls create_a_iterable_event with the event name HighIntentAbandon and passes the product ID.
4. Finally, the agent calls create_a_iterable_journey_trigger to drop Brian directly into a specialized workflow that bypasses the standard 24-hour wait time.

Scenario 2: Dynamic VIP Customer Onboarding

When a user hits a specific spend threshold, an agent can dynamically upgrade their status and send a personalized welcome packet, adjusting catalog data along the way.

"User sarah@example.com just completed a $500 purchase. Upgrade her profile to VIP, update the 'Rewards' catalog to generate a unique discount code for her, and send her the VIP welcome email."

1. The agent calls create_a_iterable_user to merge the field "status": "VIP" into Sarah's profile.
2. The agent calls iterable_catalog_items_partial_update to push a new entry into the 'Rewards' catalog, associating a generated discount code with her user ID.
3. The agent calls create_a_iterable_email_send, specifying the VIP welcome campaign ID and passing the new discount code in the data fields for template injection.

Scenario 3: Automated Preference Center Synchronization

When a user updates their preferences via an external customer support interaction (like a chat bot), the agent must accurately reflect those changes in Iterable's subscription groups.

"A user just told the support bot they no longer want daily marketing texts, but they want to keep receiving weekly newsletters. Update their Iterable subscriptions for phone number +15550198372."

1. The agent identifies the user's email or userId associated with the phone number via an internal system.
2. The agent calls delete_a_iterable_subscription_group_user_by_id for the SMS marketing group ID.
3. The agent calls update_a_iterable_subscription_group_user_by_id for the Newsletter group ID, ensuring their email preferences remain active and compliant.

Building Multi-Step Workflows

Building an agent loop requires a state graph that handles tool execution, parses responses, and strictly manages API rate limits. Because Truto passes HTTP 429 errors directly to the caller, your agent framework must intercept these errors and read the ratelimit-reset header.

Here is a conceptual architecture using Mermaid to illustrate the flow:

graph TD
    Agent["AI Agent (LangGraph/CrewAI)"]
    ToolNode["Tool Execution Node"]
    Truto["Truto Proxy API"]
    Iterable["Iterable API"]

    Agent -->|"Function Call (e.g. create_a_iterable_user)"| ToolNode
    ToolNode -->|"HTTP POST /api/users/update"| Truto
    Truto -->|"Authenticated Request"| Iterable
    
    Iterable -->|"429 Too Many Requests"| Truto
    Truto -->|"429 + ratelimit-reset header"| ToolNode
    
    ToolNode -->|"Catch 429, Sleep until reset"| ToolNode
    ToolNode -->|"Retry Request"| Truto
    Truto -->|"200 OK"| Iterable
    Iterable -->|"Success Payload"| Truto
    Truto -->|"JSON Response"| ToolNode
    ToolNode -->|"Tool Message"| Agent

If you are building this in LangChain or the Vercel AI SDK, you implement a custom fetch wrapper or an interceptor inside your tool execution node.

When the agent decides to invoke create_a_iterable_user, the framework formats the JSON arguments. The execution node fires the request to Truto. If Iterable is shedding load, Truto returns a 429 status code along with ratelimit-limit, ratelimit-remaining, and ratelimit-reset headers.

Your code must parse the ratelimit-reset value (which indicates the exact time the limit window resets), pause execution using a standard sleep function, and then retry the exact same tool call. Do not return the rate limit error to the LLM; the LLM cannot effectively "wait 15 seconds" via a text prompt. The infrastructure must handle the delay and return the eventual success payload back to the model's context window.

This separation of concerns - the LLM reasoning about the marketing objective, the unified tool layer formatting the payload, and the execution node managing the temporal rate limits - is the only way to build a reliable AI agent integration at scale.

Moving from Prototypes to Production

Connecting Iterable to an AI agent requires more than just passing a Bearer token to a script. Marketing automation platforms have strict data typing rules, complex identifier routing, and asynchronous processing delays that will break naive agent implementations.

By leveraging a unified tool layer and relying on the /tools endpoint, you abstract away the API boilerplate. You provide your LLM with a stable, deterministic set of functions that enforce schemas and prevent hallucinated payloads. You own the orchestration, the rate limit handling, and the prompt engineering, while the integration infrastructure ensures your agent interacts safely with the downstream platform.