Metadata-Version: 2.4
Name: llamaindex-multimail
Version: 0.1.0
Summary: LlamaIndex tools for MultiMail -- give your LlamaIndex agents email capabilities
Project-URL: Homepage, https://multimail.dev
Project-URL: Documentation, https://multimail.dev/docs
Project-URL: Repository, https://github.com/multimail-dev/llamaindex-multimail
Author-email: David Hanke <david@multimail.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,email,llama-index,llamaindex,multimail,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: llama-index-core>=0.10.0
Requires-Dist: multimail>=0.1.0
Provides-Extra: dev
Requires-Dist: llama-index>=0.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# llamaindex-multimail

LlamaIndex tools for [MultiMail](https://multimail.dev) -- give your LlamaIndex agents email capabilities with graduated human oversight.

## Installation

```bash
pip install llamaindex-multimail
```

## Quick Start

```python
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
from llamaindex_multimail import MultiMailToolSpec

# Create tools from your API key
tool_spec = MultiMailToolSpec(api_key="mm_live_your_api_key")
tools = tool_spec.to_tool_list()

# Create agent
llm = OpenAI(model="gpt-4o")
agent = ReActAgent.from_tools(tools, llm=llm, verbose=True)

# Run
response = agent.chat("Check mailbox 'mbx_123' for new emails")
print(response)
```

## Available Tools

| Tool | Description |
|------|-------------|
| `send_email` | Send an email (held for approval if gated) |
| `check_inbox` | List recent emails in a mailbox |
| `read_email` | Read the full content of an email |
| `reply_email` | Reply to an existing email thread |
| `search_contacts` | Search contacts by name or email |
| `list_pending` | List emails awaiting human approval |
| `decide_email` | Approve or reject a pending email |
| `get_thread` | Get all emails in a conversation |
| `tag_email` | Add tags to an email for classification |

## Oversight Modes

MultiMail supports graduated oversight so your agent doesn't send unsupervised email:

- **`gated_all`** -- Agent drafts, human approves everything
- **`gated_send`** -- Agent reads freely, human approves outbound *(default)*
- **`monitored`** -- Agent sends, human can review after
- **`autonomous`** -- Full agent control

When a mailbox uses gated oversight, `send_email` returns `pending_send_approval` and the email waits for human review. The agent can check status with `list_pending`.

## Using with Other LlamaIndex Patterns

The `MultiMailToolSpec` follows the standard LlamaIndex `BaseToolSpec` pattern, so it works with any agent framework that accepts LlamaIndex tools:

```python
from llamaindex_multimail import MultiMailToolSpec

spec = MultiMailToolSpec(api_key="mm_live_your_api_key")

# Get all tools
tools = spec.to_tool_list()

# Or get a specific tool
send_tool = spec.to_tool_list(func_to_metadata_mapping={
    "send_email": {"name": "send_email", "description": "Send an email"},
})
```

## Links

- [MultiMail](https://multimail.dev) -- Homepage & docs
- [multimail](https://pypi.org/project/multimail/) -- Base Python SDK
- [langchain-multimail](https://pypi.org/project/langchain-multimail/) -- LangChain integration
- [MCP Server](https://www.npmjs.com/package/@multimail/mcp-server) -- For Claude, Cursor, and other MCP clients
