Connect Dotdigital to AI Agents: Automate Messaging & Lead Scoring

You want to connect Dotdigital to an AI agent so your system can independently orchestrate omnichannel marketing campaigns, trigger SMS flows, sync consent preferences, and react to lead scores. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom marketing automation integration from scratch.

Giving a Large Language Model (LLM) read and write access to a platform like Dotdigital is an engineering headache. You either spend sprints building, hosting, and maintaining a custom 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 Dotdigital to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Dotdigital 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 Dotdigital, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex marketing automation workflows. For a deeper look at the architecture behind this approach, refer to our research on [architecting AI agents and the SaaS integration bottleneck](/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/).

The Engineering Reality of the Dotdigital API

Giving an LLM access to external data sounds simple during the prototyping phase. You write a Node.js function that makes a fetch request, wrap it in an @tool decorator, and hand it to LangChain. In production against complex marketing systems like Dotdigital, this approach collapses quickly.

Dotdigital'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 capabilities.

The Asynchronous Polling Trap

Standard LLMs are trained to expect synchronous, deterministic outcomes. When an agent wants to bulk import a list of webinar attendees into Dotdigital, it naturally expects a success response confirming the import.

Dotdigital handles heavy operations—like bulk contact imports, transactional data syncs, and large list deletions—asynchronously. Calling the import endpoint does not return the contacts; it returns an id and a status of NotFinished. The caller must repeatedly poll a separate status endpoint until the operation completes. If you expose raw endpoints directly to an LLM, the model will hallucinate that the import failed because it did not receive an immediate 200 OK with the created records, or it will attempt to spam the creation endpoint again.

To safely expose this to an agent, the tool layer must either abstract the polling away from the model or strictly define the expected asynchronous pattern in the tool's JSON schema so the LLM knows to invoke a follow-up checking tool.

Complex Consent and Preference Fragmentation

Marketing APIs live and die by compliance. In Dotdigital, updating a contact is not a matter of sending a flat JSON object with a firstName and email. The API strictly enforces a separation between core contact data, consentFields (for GDPR compliance logging), and marketing preferences (opt-in states for specific categories).

If you hand a generic REST schema to an LLM, it will frequently attempt to patch a user's subscription preference directly onto the root contact object ({"email": "user@example.com", "wants_newsletter": true}). Dotdigital rejects this. The schema must enforce strict encapsulation: core data goes in the contact object, consent strings go in consentFields, and opt-in arrays go in preferences.

Raw Rate Limits and Model Context

When a multi-step agent hits a rate limit, the integration architecture dictates whether the agent survives or crashes. Dotdigital enforces strict rate limiting on its endpoints.

A factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Dotdigital API returns an HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification.

The caller (your agent runner) is entirely responsible for retry and backoff logic. If you feed a raw 429 HTML error page back into the LLM's context window, you waste expensive tokens and confuse the model. Your agent framework must catch the 429, read the normalized ratelimit-reset header provided by Truto, pause execution, and retry without involving the LLM.

Connecting Dotdigital Tools to Your Agent

A unified tool layer collapses API complexity. Instead of forcing your agent to memorize Dotdigital's unique identifier requirements and asynchronous polling states, Truto exposes strict, normalized JSON schemas for every operation.

Here is exactly how to fetch Dotdigital tools programmatically and bind them to your LLM using the TrutoToolManager from the truto-langchainjs-toolset SDK.

1. Initialize the SDK and Fetch Tools

First, install the required packages:

npm install @trutohq/truto-langchainjs-toolset @langchain/openai

Next, authenticate the client and retrieve the tools for a specific integrated Dotdigital account. You retrieve these by calling Truto's /tools endpoint for the specific integrated-account-id.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
async function initializeAgent() {
  // 1. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 2. Initialize the Truto Tool Manager
  const toolManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY,
  });
 
  // 3. Fetch tools for the specific Dotdigital connection
  const integratedAccountId = "your_dotdigital_account_id";
  const tools = await toolManager.getTools(integratedAccountId);
 
  console.log(`Loaded ${tools.length} Dotdigital tools`);
 
  // 4. Bind the normalized tools to the LLM
  const agentWithTools = llm.bindTools(tools);
  
  return agentWithTools;
}

Because every tool returned by Truto is generated from strict OpenAPI definitions, the agent inherently understands required fields, data types, and constraints.

Core Dotdigital AI Agent Tools

Exposing the entire surface area of the Dotdigital API to an agent is rarely the right architectural choice. Instead, provide high-leverage tools that enable the agent to execute specific marketing operations. Here are the hero tools you should consider for a Dotdigital agent integration.

list_all_dotdigital_contact_scores

Retrieves contact scoring information for a specific contact identifier. This tool is critical for workflows where the agent needs to verify lead warmth before taking action.

"Check the current engagement score and suitability rating for user@example.com. If their engagement score is above 80, prepare an SMS campaign payload."

create_a_dotdigital_contacts_import_collection

Executes a bulk creation or update of Dotdigital contacts from a JSON collection. This initiates an asynchronous import job, returning an id that the agent can track.

"I have a list of 50 new leads from the virtual conference. Import them into Dotdigital and assign them to address book ID 142. Note the import job ID so we can verify completion later."

dotdigital_contact_with_consent_and_preferences_bulk_update

Updates an existing contact while explicitly handling GDPR consent information and marketing preference opt-ins in a single structured payload.

"Update the contact profile for user@example.com. Ensure their optInType is set to VerifiedDouble, and add a consent record indicating they opted in via the Q3 Webinar registration form."

create_a_dotdigital_campaign

Creates a new email campaign within Dotdigital, defining the HTML content, plain text fallback, subject line, and sender details.

"Draft a new email campaign named 'Q4 Feature Release'. The subject should be 'Unlock our new AI features', sent from 'Product Team'. Use the HTML string I generated in the previous step."

create_a_dotdigital_campaigns_send_time_optimised

Dispatches an existing email campaign to designated address books or contacts using Dotdigital's send-time optimization engine (which relies on historical open data).

"Take campaign ID 99281 and dispatch it to the Enterprise Segments list. Ensure you use send-time optimization so the emails arrive when recipients are most likely to open them."

create_a_dotdigital_sms_messages_send_to

Sends a single transactional SMS message to a specific contact using an E.164 formatted telephone number.

"Send an SMS to +15550198273 saying: 'Your VIP access pass to tomorrow's event is confirmed. Check your email for the barcode.'"

To view the complete inventory of available API actions and their schemas, visit the Dotdigital integration page.

Workflows in Action

Agents become powerful when they chain multiple tools together to solve multi-step problems that would normally require human intervention or rigid Zapier pipelines.

Autonomous Lead Scoring and SMS Escalation

Marketing and sales ops teams often struggle to engage high-intent leads quickly. You can instruct an agent to monitor incoming form fills, verify lead scores in Dotdigital, and execute immediate SMS outreach to hot leads.

"A new lead just registered for the enterprise trial: sarah@acmecorp.com (+15558901234). Check her current Dotdigital contact score. If her combined score exceeds 75, send her an automated SMS offering a direct line to our sales engineers."

1. The agent calls list_all_dotdigital_contact_scores passing the email address.
2. The agent parses the response, evaluating the scoreLabel, engagement, and suitability metrics.
3. Determining the score is 88, the agent formulates a personalized message.
4. The agent calls create_a_dotdigital_sms_messages_send_to, pushing the SMS out immediately.
5. The agent returns a success confirmation to the execution loop.

Post-Event Bulk Import and Consent Management

Handling post-event lists is notoriously messy due to fragmented consent rules. An agent can ingest raw list data, execute the asynchronous import, and ensure compliance tracking is rock solid.

"We just finished the European AI Summit. Import this JSON array of 30 attendees into Dotdigital. Once the import is queued, iterate through the resulting IDs and update their consent fields to log that they gave explicit permission at the physical booth."

1. The agent formats the payload and calls create_a_dotdigital_contacts_import_collection.
2. Dotdigital returns a 202 Accepted and an import job ID.
3. The agent understands this is an async operation and waits for the job to complete (or relies on the orchestrator to poll).
4. Once imported, the agent uses dotdigital_contact_with_consent_and_preferences_bulk_update to append the specific GDPR consent strings to the newly created contact profiles.

Building Multi-Step Workflows

To make these workflows resilient in production, you cannot just hand the tools to an LLM and hope for the best. You need an execution loop that handles tool calling, intercepts errors, and manages HTTP 429 Rate Limits deterministically.

Below is an architectural example of a framework-agnostic execution loop that handles rate limits safely. Because Truto normalizes rate limit headers, you can read ratelimit-reset directly and pause your execution thread, entirely bypassing the LLM.

import { HumanMessage, AIMessage, ToolMessage } from "@langchain/core/messages";
 
async function executeWorkflow(agentWithTools, toolManager, userPrompt) {
  const messages = [new HumanMessage(userPrompt)];
  
  while (true) {
    // 1. Invoke the agent
    const response = await agentWithTools.invoke(messages);
    messages.push(response);
    
    // 2. If no tools are called, the agent is finished reasoning
    if (!response.tool_calls || response.tool_calls.length === 0) {
      return response.content;
    }
    
    // 3. Execute tools safely
    for (const toolCall of response.tool_calls) {
      try {
        console.log(`Executing: ${toolCall.name}`);
        const toolResult = await toolManager.executeTool(toolCall);
        
        messages.push(new ToolMessage({
          tool_call_id: toolCall.id,
          content: JSON.stringify(toolResult)
        }));
        
      } catch (error) {
        // 4. Deterministic Rate Limit Handling
        if (error.status === 429) {
          const resetTime = error.headers['ratelimit-reset'];
          const waitTimeMs = (parseInt(resetTime) * 1000) - Date.now();
          
          console.warn(`Rate limit hit. Sleeping for ${waitTimeMs}ms`);
          await new Promise(resolve => setTimeout(resolve, waitTimeMs));
          
          // Push a system message so the LLM knows to retry on the next loop
          messages.push(new ToolMessage({
            tool_call_id: toolCall.id,
            content: JSON.stringify({ error: "Rate limit hit, system paused, please retry this tool call." })
          }));
        } else {
          // Standard error handling fed back to the LLM
          messages.push(new ToolMessage({
            tool_call_id: toolCall.id,
            content: JSON.stringify({ error: error.message })
          }));
        }
      }
    }
  }
}

The Architecture of the Call

When you use this architecture, the integration complexity is fully decoupled from the LLM's reasoning engine. The flow looks like this:

sequenceDiagram
    participant App as Agent Runner
    participant LLM as LLM (OpenAI/Claude)
    participant Truto as Truto Tool Layer
    participant Upstream as "Dotdigital API"

    App->>LLM: Provide user prompt & tool schemas
    LLM-->>App: Return tool_call (e.g., create_campaign)
    App->>Truto: Execute normalized POST request
    
    alt Rate Limit Exceeded
        Truto->>Upstream: Forward Request
        Upstream-->>Truto: 429 Too Many Requests
        Truto-->>App: 429 + ratelimit-reset headers
        App->>App: Sleep until reset time
        App->>LLM: Instruct model to retry
    else Success
        Truto->>Upstream: Forward Authenticated Request
        Upstream-->>Truto: 201 Created (Dotdigital JSON)
        Truto-->>App: Normalized JSON response
        App->>LLM: Provide tool result
        LLM-->>App: Final natural language response
    end

Moving Beyond Workflow Automation

Connecting Dotdigital to AI agents transforms marketing operations from rigid, rules-based triggers into fluid, context-aware automation. By leveraging Truto's /tools endpoint, you abstract away the complexities of the Dotdigital API—its asynchronous polling logic, fragmented consent models, and rate limits—while retaining complete control over execution and safety.

Stop writing custom integration code to parse API documentation into agent schemas. Expose every product API as a reliable, typed, and normalized tool, and focus your engineering efforts on your AI agent's core capabilities.