Connect Novu to AI Agents: Configure Domains and Inbound Routes

You want to connect Novu to AI agents so your system can autonomously provision domains, map inbound email routes, and orchestrate complex notification workflows across environments. If your team uses ChatGPT, check out our guide on connecting Novu to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Novu to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

Giving a Large Language Model (LLM) read and write access to your notification infrastructure is a significant engineering challenge. You either spend weeks building, hosting, and maintaining custom API wrappers, or you use a managed infrastructure layer that handles the boilerplate for you. This guide breaks down exactly how to use Truto's /tools endpoint to generate AI-ready tools for Novu, bind them natively to your LLM using frameworks like LangChain or Vercel AI SDK, and execute infrastructure automation safely. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of Custom Novu Connectors

Building AI agents is relatively straightforward. Connecting them safely to external SaaS APIs like Novu is where the complexity multiplies. A custom integration layer is essentially a translation service that converts an LLM's unstructured intent into structured REST API requests. While modern models are excellent at generating JSON payloads, implementing those payloads against vendor APIs is highly error-prone, a core challenge we explore in our guide to LLM function calling.

If you decide to build a custom integration layer for Novu, you are responsible for the entire API lifecycle. You must write and maintain massive JSON schemas for every endpoint you want the LLM to access. You also have to handle a few very specific API quirks that will immediately break naive agent implementations.

Environment Isolation and Promotion

Novu strictly isolates environments - typically Development and Production. When managing workflows programmatically, you do not simply PUT or PATCH a production workflow directly. Changes are made in a development environment and then promoted using specific sync endpoints.

If you build this yourself, your agent must understand this concept deeply. It needs to know which environment_id it is currently operating in, and it must explicitly pass the targetEnvironmentId when calling sync operations. If you hand-code these tools, you have to write complex prompt instructions to teach the LLM this dependency. Truto's dynamic tool schemas expose these parameters natively, enforcing the environment relationship so the agent cannot hallucinate missing IDs.

Domain Verification States

Configuring inbound routing in Novu requires an active, verified domain. When an agent creates a domain via the API, Novu returns a set of expected DNS records (MX, TXT). The domain is not usable immediately. The agent must pause, output those records so a human or automated CI/CD pipeline can update the DNS provider, and then later trigger a secondary verification endpoint.

Standard API wrappers fail here because the LLM assumes the resource is ready immediately after a 201 Created response. By utilizing precise tool descriptions fetched from Truto, the LLM is instructed that domain creation is a two-part asynchronous process, preventing it from attempting to bind routes to unverified domains.

Immutable Route Addresses

Inbound email routes in Novu bind a specific address (like 'support' or 'replies') to a domain. A common LLM hallucination is attempting to update the address identity of an existing route using a PATCH request.

Novu's API architecture dictates that the address identity cannot be changed once created. To rename an address, the system must delete the existing route and create an entirely new one. Truto handles this by exposing explicit delete_a_novu_route_by_id and create_a_novu_route tools, with schemas that guide the LLM away from invalid update attempts.

Handling Rate Limits in Agent Loops

When an AI agent executes a loop, it can easily fire dozens of API requests in seconds, hitting upstream rate limits. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Novu API returns an HTTP 429, Truto passes that error directly back to the caller.

However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This normalization is crucial. Without it, your agent framework would have to parse vendor-specific rate limit headers (which change between every SaaS provider). With Truto, your agent's error boundary only needs to look for the normalized ratelimit-reset header to know exactly how many milliseconds to sleep before retrying the tool call.

Hero Tools for Novu

Instead of manually writing OpenAPI specifications for your agent framework, Truto provides a dynamic /tools endpoint. This endpoint returns pre-formatted, AI-ready JSON schemas for every Novu API operation. Below are the highest-leverage hero tools for automating domains, inbound routes, and workflows in Novu.

create_a_novu_domain

This tool registers a new inbound-email domain in Novu. It returns the domain ID alongside the specific DNS records (MX, TXT) that must be added at the DNS provider before the domain can receive mail.

"Register the domain 'inbound.acme.com' in our Novu environment and output the exact DNS records I need to add to Cloudflare."

novu_domains_verify

Once DNS records are propagated, this tool instructs Novu to verify the domain against live DNS. It refreshes the verification status, which is a hard prerequisite before you can map routes to the domain.

"Check the verification status of the domain ID 'dom_84nx92'. If it is verified, let me know. If not, trigger a verification check and report the missing records."

create_a_novu_route

This tool creates an inbound route that forwards mail addressed to a specific email prefix on a verified domain. You can route this mail directly to a webhook or an internal agent for processing.

"Create a new route on the 'inbound.acme.com' domain. Any mail sent to 'support' should be forwarded to our production webhook URL."

update_a_novu_route_by_id

While you cannot change the email address identity of a route, you use this tool to update where the route forwards its data. This is heavily used when migrating webhooks or rotating endpoint URLs.

"Update the route ID 'rt_992kx' on the 'inbound.acme.com' domain so that it points to our new v2 webhook endpoint instead of the legacy endpoint."

create_a_novu_inbound_route

This tool is critical for testing. It allows the agent to send a synthetic email payload through the exact same production delivery path to test webhook logic or agent routing without requiring actual external emails.

"Send a synthetic test email to 'support@inbound.acme.com' with a mock customer complaint to verify that the webhook destination is processing payloads correctly."

create_a_novu_workflow

This tool provisions a new notification workflow in the current environment. Agents can use this to scaffold entirely new notification sequences based on plain English requirements.

"Create a new workflow named 'Enterprise Password Reset'. It should be active immediately and set up to handle email and SMS channels."

novu_workflows_sync

This tool synchronizes a specific workflow from the development environment to a target production environment. It requires the source workflow ID and the target environment ID.

"Sync the 'Enterprise Password Reset' workflow to our production environment. The target environment ID is 'env_prod_882'."

To view the complete inventory of available operations, request parameters, and schemas, visit the Novu integration page.

Workflows in Action

Integrating these tools into an agentic loop allows you to build systems that act as autonomous DevOps engineers. Here are two concrete examples of how an AI agent uses Truto tools to execute complex infrastructure tasks in Novu.

Scenario 1: Provisioning a New Inbound Email Flow

An IT administrator needs to stand up a new inbound email pipeline for an acquired product line. They want all emails sent to a specific domain to route to a new internal API.

"We just acquired a product called Zenith. Register the domain 'replies.zenith.com' in Novu for inbound emails. Output the required DNS records in a markdown table. Wait for me to confirm DNS is updated, then verify the domain. Once verified, create a wildcard route so all mail to this domain goes to https://api.acme.com/zenith/inbound."

Execution Steps:

1. create_a_novu_domain: The agent calls this tool with name: "replies.zenith.com". The tool returns the domain ID and the expected DNS records.
2. The agent pauses execution, outputting the DNS records to the human user and waiting for a continuation signal.
3. novu_domains_verify: After the human confirms DNS changes, the agent calls this tool with the domain ID. Novu queries live DNS and updates the domain status to verified.
4. create_a_novu_route: The agent executes this tool, passing the domain name, setting address: "*" for a wildcard, and providing the webhook destination URL.

The user receives a fully configured inbound routing pipeline without ever opening the Novu dashboard or writing a script.

Scenario 2: Promoting Workflows Between Environments

A DevOps engineer needs to audit changes in a staging environment and safely promote them to production if they pass basic checks.

"Compare the 'Payment Failed' workflow in our dev environment against production (ID: env_prod_123). If there are new steps added, sync the workflow to production."

Execution Steps:

1. novu_environments_compare: The agent uses this tool, targeting the Dev environment workflow and passing targetEnvironmentId: "env_prod_123". The tool returns a diff showing additions, modifications, and deletions.
2. The agent evaluates the diff JSON in its context. It sees a new SMS fallback step was added.
3. novu_workflows_sync: Because the condition was met, the agent calls this tool with the workflow ID and the target production environment ID, promoting the changes seamlessly.

The user gets back a summary of the exact differences found and a confirmation that the workflow is now live in production.

Building Multi-Step Workflows

To build these autonomous workflows, you must fetch the tools from Truto and bind them to your LLM. Because Truto normalizes the API surface, this code is entirely framework-agnostic. Whether you use LangChain, LangGraph, CrewAI, or the Vercel AI SDK, the pattern remains identical—much like the modular approach used in building MCP servers for AI agents.

Architecture Flow

graph TD
    A["Agent Framework<br>(LangChain/Vercel)"] -->|"GET /integrated-account/:id/tools"| B["Truto API"]
    B -->|"Returns JSON Schemas"| A
    A -->|".bindTools()"| C["Large Language Model"]
    C -->|"Tool Call intent"| A
    A -->|"Execute Tool"| B
    B -->|"REST API Request"| D["Novu API"]
    D -->|"API Response / 429 Rate Limit"| B
    B -->|"Normalized Response"| A

Fetching and Binding Tools

First, you retrieve the specific proxy tools for your connected Novu account. Truto handles the OAuth tokens, environment variables, and authentication injection behind the scenes.

import { ChatAnthropic } from "@langchain/anthropic";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
// 1. Initialize the Truto SDK with your connected Novu account ID
const toolManager = new TrutoToolManager({
  apiKey: process.env.TRUTO_API_KEY,
  integratedAccountId: "acc_novu_987x5"
});
 
// 2. Fetch all available Novu tools
// Optionally filter by method type (e.g., read, write)
const novuTools = await toolManager.getTools();
 
// 3. Initialize your preferred LLM
const llm = new ChatAnthropic({
  model: "claude-3-5-sonnet-latest",
  temperature: 0,
});
 
// 4. Bind the Truto tools to the LLM natively
const agentWithTools = llm.bindTools(novuTools);

Handling Execution and Rate Limits

When the LLM decides to use a tool, your agent loop executes the request. As mentioned earlier, Truto does not absorb rate limit errors. If your agent is running a bulk data operation and hits Novu's API limits, Truto will return an HTTP 429.

Because Truto normalizes these headers, you can implement a standard retry boundary in your agent execution loop without writing vendor-specific code.

async function executeToolWithBackoff(tool, args, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      // Execute the tool call against Truto
      const result = await tool.invoke(args);
      return result;
    } catch (error) {
      if (error.status === 429) {
        // Truto normalizes upstream headers to the IETF specification
        const resetTime = error.headers.get('ratelimit-reset');
        
        if (resetTime) {
          // Calculate how long to sleep
          const sleepMs = (parseInt(resetTime) * 1000) - Date.now();
          if (sleepMs > 0) {
            console.warn(`Rate limited. Sleeping for ${sleepMs}ms`);
            await new Promise(resolve => setTimeout(resolve, sleepMs));
            continue;
          }
        }
        // Fallback exponential backoff if header is missing
        const fallbackMs = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, fallbackMs));
        continue;
      }
      // Rethrow non-rate-limit errors to halt the agent
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

This architecture guarantees predictable execution. Your agent framework handles the cognitive reasoning and retry logic, the LLM handles the intent parsing, and Truto handles the complex realities of API authentication, JSON translation, and header normalization.

If you are serious about building production-grade AI agents, you cannot afford to maintain point-to-point API connectors manually. The complexity of environment syncing, rate limit header parsing, and custom object mapping will consume your entire engineering roadmap. By leveraging a unified integration infrastructure that generates dynamic schemas natively for LLMs, you decouple your agent logic from the chaotic reality of third-party APIs. Your engineers can focus on building intelligent multi-step workflows, while Truto ensures the underlying API requests succeed predictably and securely.