how to build a llama_index functioncallingagent for email

pip install llama-index llama-index-llms-openai
npm install @lobsterkit/lobstermail

We're using Python for the LlamaIndex agent and the LobsterMail Node SDK for email operations. If your agent runs in Python end-to-end, you can call the LobsterMail REST API directly. I'll show both approaches.

For the LLM, we'll start with OpenAI since it has the widest function calling support in LlamaIndex. Swapping to Anthropic or Mistral later is a one-line change.

## Defining real email tools

Here's where most tutorials go wrong. They define a tool like this:

```python
def send_email(to: str, subject: str, body: str) -> str:
    """Send an email."""
    print(f"Sending to {to}: {subject}")
    return "Email sent successfully"
That function does nothing. Your agent thinks it sent an email, but the recipient never gets one. In production, this kind of gap causes silent failures that are nearly impossible to debug.

Instead, we need tools that talk to real email infrastructure. Here's a `send_email` tool backed by the LobsterMail API:

```python
import requests

LOBSTERMAIL_TOKEN = os.environ["LOBSTERMAIL_TOKEN"]
INBOX_ADDRESS = os.environ["LOBSTERMAIL_INBOX"]
API_BASE = "https://api.lobstermail.ai/v1"

def send_email(to: str, subject: str, body: str) -> str:
    """Send an email from the agent's inbox to a recipient."""
    resp = requests.post(
        f"{API_BASE}/emails/send",
        headers={"Authorization": f"Bearer {LOBSTERMAIL_TOKEN}"},
        json={
            "from": INBOX_ADDRESS,
            "to": to,
            "subject": subject,
            "body": body
        }
    )
    if resp.status_code == 200:
        return f"Email sent to {to}"
    return f"Failed to send: {resp.status_code} {resp.text}"

def read_emails(limit: int = 10) -> str:
    """Read recent emails from the agent's inbox."""
    resp = requests.get(
        f"{API_BASE}/inboxes/{INBOX_ADDRESS}/emails",
        headers={"Authorization": f"Bearer {LOBSTERMAIL_TOKEN}"},
        params={"limit": limit}
    )
    if resp.status_code != 200:
        return f"Failed to fetch emails: {resp.status_code}"

    emails = resp.json().get("emails", [])
    if not emails:
        return "No emails in inbox."

    summaries = []
    for e in emails:
        summaries.append(
            f"From: {e['from']} | Subject: {e['subject']} | Preview: {e['preview']}"
        )
    return "\n".join(summaries)

These functions hit a real API. When `send_email` returns success, an actual email lands in someone's inbox. When `read_emails` returns messages, those are real messages from real senders.

## Building the agent

Now we wire the tools into a `FunctionAgent`:

```python
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI


# Wrap our functions as LlamaIndex tools
send_tool = FunctionTool.from_defaults(fn=send_email)
read_tool = FunctionTool.from_defaults(fn=read_emails)

# Initialize the LLM
llm = OpenAI(model="gpt-4o", temperature=0)

# Create the agent
agent = FunctionAgent(
    tools=[send_tool, read_tool],
    llm=llm,
    system_prompt=(
        "You are an email assistant. You can read emails from your inbox "
        "and send replies. Always confirm the recipient address before sending. "
        "Be concise in your responses."
    ),
)

The `system_prompt` matters more than you'd think. Without the instruction to confirm recipients, the agent will happily send emails to whatever address it infers from context. For an email agent, that's a real risk with real consequences.

To run the agent:

```python
from llama_index.core.workflow import Context

ctx = Context(agent)

response = await agent.run(
    "Check my inbox and reply to any emails from alice@example.com",
    ctx=ctx,
)
print(response)

# Anthropic
from llama_index.llms.anthropic import Anthropic
llm = Anthropic(model="claude-sonnet-4-20250514", temperature=0)

# Mistral
from llama_index.llms.mistral import MistralAI
llm = MistralAI(model="mistral-large-latest", temperature=0)

The tools stay identical. The agent behavior will differ slightly (each model interprets function schemas a bit differently), but the email operations work the same way. In my testing, GPT-4o and Claude 3.5 Sonnet are the most reliable at correctly populating email fields. Mistral Large occasionally omits the subject line when the user doesn't specify one explicitly.

## Handling errors and edge cases

Real email has failure modes that simulated email doesn't. Your tools need to account for them.

**Bounces.** A 550 error means the recipient's server permanently rejected the message. Your tool should return a clear error so the agent can inform the user instead of silently failing. We wrote a [full guide to 550 errors](/blog/550-email-rejected-how-to-fix-outbound-failures-from-your-agent) if you're seeing these in production.

**Rate limits.** On LobsterMail's free tier, you get 1,000 emails per month. Your tool should handle 429 responses gracefully:

```python
if resp.status_code == 429:
    return "Rate limit reached. Try again later or upgrade your plan."

if email.get("injection_risk", 0) > 0.7:
    return "⚠️ This email was flagged as potentially malicious. Skipping."

agent = FunctionAgent(
    tools=[send_tool, read_tool, draft_tool],
    llm=llm,
    system_prompt=(
        "You are an email assistant. When asked to reply to an email, "
        "first draft the reply and show it to the user. Only call send_email "
        "after the user explicitly approves the draft."
    ),
)