LlamaIndex Integration Guide

curl -X POST https://api.molted.email/v1/me/mailboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Outbound Agent",
    "emailAddress": "agent@yourdomain.com"
  }'

import os
from typing import Optional
import requests
from llama_index.core.tools import FunctionTool


def send_email(
    to: str,
    subject: str,
    body: str,
    dedupe_key: Optional[str] = None,
) -> str:
    """Send an email to a contact.

    The email is checked against policy rules before it is delivered.
    If blocked, the function returns the reason - do not retry a blocked send.

    Args:
        to: Recipient email address.
        subject: Email subject line.
        body: Email body in plain text or HTML.
        dedupe_key: Unique key to prevent duplicate sends. Defaults to recipient+subject.
    """
    api_key = os.environ["MOLTED_API_KEY"]
    tenant_id = os.environ["MOLTED_TENANT_ID"]

    payload = {
        "tenantId": tenant_id,
        "recipientEmail": to,
        "templateId": "_default",
        "dedupeKey": dedupe_key or f"{to}-{subject}",
        "agentId": "llamaindex-agent",
        "payload": {
            "subject": subject,
            "html": body,
            "text": body,
        },
    }

    response = requests.post(
        "https://api.molted.email/v1/agent/send/request",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=10,
    )
    data = response.json()

    if data.get("status") == "blocked":
        return (
            f"Email blocked by policy. Reason: {data.get('blockReason')}. "
            f"Decision trace: {data.get('requestId')}. Do not retry."
        )

    return (
        f"Email queued successfully. "
        f"requestId={data.get('requestId')}, status={data.get('status')}"
    )


send_email_tool = FunctionTool.from_defaults(fn=send_email)

import os
import requests
from llama_index.core.tools import FunctionTool


def check_email_status(request_id: str) -> str:
    """Check the delivery status of a previously queued email.

    Args:
        request_id: The requestId returned when the email was sent.
    """
    api_key = os.environ["MOLTED_API_KEY"]

    response = requests.get(
        f"https://api.molted.email/v1/agent/send/{request_id}/status",
        headers={"Authorization": f"Bearer {api_key}"},
        timeout=10,
    )
    data = response.json()

    return (
        f"Status: {data.get('status')}. "
        f"Provider: {data.get('provider', 'unknown')}. "
        f"Last event: {data.get('lastEvent', 'none')}."
    )


check_status_tool = FunctionTool.from_defaults(fn=check_email_status)

import os
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
from tools.send_email import send_email_tool
from tools.check_email_status import check_status_tool

llm = OpenAI(model="gpt-4o", api_key=os.environ["OPENAI_API_KEY"])

agent = ReActAgent.from_tools(
    tools=[send_email_tool, check_status_tool],
    llm=llm,
    verbose=True,
    system_prompt=(
        "You are an email outreach agent. You send policy-compliant emails through "
        "a managed mailbox. Every send is checked against policy rules before delivery. "
        "If a send is blocked, report the reason - do not retry. "
        "Use 'welcome-{email}' as the dedupeKey for welcome emails to prevent duplicates."
    ),
)

response = agent.chat(
    "Send a trial welcome email to alice@example.com. "
    "Let her know her 14-day trial starts today and she can reply with questions."
)
print(response)

from llama_index.core.agent import FunctionCallingAgent
from llama_index.llms.openai import OpenAI
from tools.send_email import send_email_tool
from tools.check_email_status import check_status_tool

llm = OpenAI(model="gpt-4o")

agent = FunctionCallingAgent.from_tools(
    tools=[send_email_tool, check_status_tool],
    llm=llm,
    verbose=True,
)

response = agent.chat("Send a churn-prevention email to bob@example.com.")
print(response)

import os
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from tools.send_email import send_email_tool
from tools.check_email_status import check_status_tool

llm = OpenAI(model="gpt-4o")

agent = FunctionAgent(
    tools=[send_email_tool, check_status_tool],
    llm=llm,
    system_prompt=(
        "You are an outreach agent. Send emails through the governed mailbox. "
        "If a send is blocked, report the block reason to the caller. Do not retry."
    ),
)

import asyncio

async def main():
    response = await agent.run(
        "Send a reactivation email to carol@example.com who hasn't logged in for 30 days."
    )
    print(response)

asyncio.run(main())

import os
import requests

api_key = os.environ["MOLTED_API_KEY"]
tenant_id = os.environ["MOLTED_TENANT_ID"]

agents = [
    {"name": "onboarding-agent", "config": {"humanizer_enabled": True, "humanizer_style": "friendly"}},
    {"name": "churn-agent", "config": {"humanizer_enabled": True, "humanizer_style": "professional"}},
    {"name": "billing-agent", "config": {"humanizer_enabled": False}},
]

agent_ids = {}
for agent in agents:
    response = requests.post(
        "https://api.molted.email/v1/agent/register",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"tenantId": tenant_id, **agent},
    )
    data = response.json()
    agent_ids[agent["name"]] = data["id"]
    print(f"Registered {agent['name']}: agentId={data['id']}")

payload = {
    "tenantId": tenant_id,
    "agentId": agent_ids["onboarding-agent"],  # from registration
    # ...
}

import { FunctionTool } from "llamaindex";

export const sendEmailTool = FunctionTool.from(
  async ({
    to,
    subject,
    body,
    dedupeKey,
  }: {
    to: string;
    subject: string;
    body: string;
    dedupeKey?: string;
  }) => {
    const response = await fetch(
      "https://api.molted.email/v1/agent/send/request",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.MOLTED_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          tenantId: process.env.MOLTED_TENANT_ID,
          recipientEmail: to,
          templateId: "_default",
          dedupeKey: dedupeKey ?? `${to}-${subject}`,
          agentId: "llamaindex-agent",
          payload: { subject, html: body, text: body },
        }),
      }
    );

    const data = await response.json();

    if (data.status === "blocked") {
      return `Email blocked: ${data.blockReason}. Decision trace: ${data.requestId}. Do not retry.`;
    }

    return `Email queued: requestId=${data.requestId}, status=${data.status}`;
  },
  {
    name: "send_email",
    description:
      "Send an email to a contact. Checked against policy rules before delivery. If blocked, returns the reason - do not retry.",
    parameters: {
      type: "object",
      properties: {
        to: { type: "string", description: "Recipient email address" },
        subject: { type: "string", description: "Email subject line" },
        body: { type: "string", description: "Email body in plain text or HTML" },
        dedupeKey: {
          type: "string",
          description: "Unique key to prevent duplicate sends",
        },
      },
      required: ["to", "subject", "body"],
    },
  }
);

import { OpenAI, ReActAgent } from "llamaindex";
import { sendEmailTool } from "./tools/sendEmail";

const llm = new OpenAI({ model: "gpt-4o" });

const agent = new ReActAgent({
  tools: [sendEmailTool],
  llm,
});

const response = await agent.chat({
  message: "Send a welcome email to alice@example.com.",
});
console.log(response.response);

system_prompt = """
You are an email outreach agent. When a send is blocked:
- 'duplicate_send': email was already sent recently. Report to the user. Do not retry.
- 'suppressed_recipient': contact has opted out. Skip and move to next contact.
- 'rate_limit_exceeded': mailbox rate limit hit. Stop all sends and report.
- 'cooldown_active': cooldown in effect. Report when it will lift. Do not retry now.
- Any other block: report the reason and requestId. Do not retry without explicit instruction.
"""