LlamaIndex Integration

Path 1: Agent Tools (ToolSpec)

The DeadSimpleToolSpec gives LlamaIndex agents direct access to email operations. Create inboxes, send messages, read mail, and reply to threads through natural language.

          
          agent_tools.py
        
from deadsimple.integrations.llamaindex import DeadSimpleToolSpec

tool_spec = DeadSimpleToolSpec(api_key="dse_your_api_key")
tools = tool_spec.to_tool_list()

The to_tool_list() method returns LlamaIndex FunctionTool objects that work with any LlamaIndex agent: OpenAIAgent, ReActAgent, or custom agent implementations. Each tool has typed parameters and descriptions for accurate function calling.

          
          
          
          agent_example.py
        

from llama_index.agent.openai import OpenAIAgent
from llama_index.llms.openai import OpenAI
from deadsimple.integrations.llamaindex import DeadSimpleToolSpec

tool_spec = DeadSimpleToolSpec(api_key="dse_your_api_key")
tools = tool_spec.to_tool_list()

agent = OpenAIAgent.from_tools(
    tools,
    llm=OpenAI(model="gpt-4o"),
    verbose=True,
    system_prompt="You are an email assistant. Use your tools to manage inboxes and messages.",
)

response = agent.chat("Create an inbox called 'alerts' and send a test message to admin@example.com")
print(response)
        

Path 2: RAG Document Reader

The DeadSimpleReader loads email messages as LlamaIndex Document objects, ready for indexing and retrieval. This is the only email API with a native LlamaIndex document reader -- no other provider offers this out of the box.

          
          rag_reader.py
        
from deadsimple.integrations.llamaindex import DeadSimpleReader

reader = DeadSimpleReader(api_key="dse_your_api_key")
documents = reader.load_data(inbox_id="inb_xxx")
# Use with any LlamaIndex index for retrieval

Each email becomes a Document with the message body as text and metadata including sender, recipient, subject, timestamp, and message ID. This means you can build semantic search over your email data with a few lines of code.

          
          rag_pipeline.py
        
from llama_index.core import VectorStoreIndex
from deadsimple.integrations.llamaindex import DeadSimpleReader

# Load emails from an inbox
reader = DeadSimpleReader(api_key="dse_your_api_key")
documents = reader.load_data(inbox_id="inb_xxx")

# Build a vector index over the email content
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

# Semantic search over emails
response = query_engine.query("What did the customer say about the delivery delay?")
print(response)

This pattern is powerful for customer support agents, knowledge bases built from email correspondence, and any workflow where you need to search or reason over email history.

Available Tools

The DeadSimpleToolSpec exposes the following tools through to_tool_list().

Tool	Description	Key Parameters
`send_email`	Send an email from an inbox	`inbox_id`, `to`, `subject`, `body`
`read_emails`	List recent messages in an inbox	`inbox_id`, `limit`
`read_email`	Get a single message by ID	`inbox_id`, `message_id`
`reply_to_email`	Reply to an existing message thread	`inbox_id`, `message_id`, `body`
`create_inbox`	Create a new email inbox	`name`
`list_inboxes`	List all inboxes on the account	None

Combining Both Paths: RAG + Agent Tools

The most powerful pattern combines the document reader with agent tools. Load historical emails into a vector index for context, then give the agent tools to act on what it finds.

          
          
          
          rag_plus_agent.py
        

from llama_index.core import VectorStoreIndex
from llama_index.agent.openai import OpenAIAgent
from llama_index.llms.openai import OpenAI
from deadsimple.integrations.llamaindex import (
    DeadSimpleToolSpec, DeadSimpleReader,
)

api_key = "dse_your_api_key"

# 1. Load emails into a searchable index
reader = DeadSimpleReader(api_key=api_key)
documents = reader.load_data(inbox_id="inb_xxx")
index = VectorStoreIndex.from_documents(documents)
query_tool = index.as_query_engine()

# 2. Get email action tools
tool_spec = DeadSimpleToolSpec(api_key=api_key)
email_tools = tool_spec.to_tool_list()

# 3. Build an agent with both retrieval and action capabilities
agent = OpenAIAgent.from_tools(
    email_tools,
    llm=OpenAI(model="gpt-4o"),
    verbose=True,
    system_prompt="You are a support agent. Search past emails for context, then respond to new messages.",
)

response = agent.chat("Find the thread about the billing issue and send a follow-up.")
print(response)
        

This pattern is ideal for customer support, account management, or any workflow where the agent needs historical context before taking action. The reader provides the memory; the tools provide the capability.

Why a Native Document Reader Matters

Most email APIs stop at CRUD operations. Dead Simple Email is the first to ship a native LlamaIndex document reader, which means:

No glue code. You don't need to write a custom loader that fetches emails, extracts text, and wraps them in Document objects. It's one function call.
Structured metadata. Every document includes sender, recipient, subject, timestamp, and message ID as metadata. Filter and facet your search without parsing.
Incremental loading. Pass a since parameter to load only new messages since your last sync. Keep your index fresh without re-indexing everything.
Works with any index. VectorStoreIndex, ListIndex, KnowledgeGraphIndex, or a custom pipeline. Documents are standard LlamaIndex objects.