Metadata-Version: 2.5
Name: carlyemail-toolkit
Version: 0.1.1
Summary: CarlyEmail's email tools for the OpenAI Agents SDK, LangChain, LiveKit Agents, and any other framework.
Project-URL: Homepage, https://carlyemail.com
Project-URL: Documentation, https://docs.carlyemail.com/integrations/toolkit
Author: SWH Labs LLC
License-Expression: MIT
Keywords: agents,carlyemail,email,langchain,livekit,llm,openai-agents,toolkit
Requires-Python: >=3.10
Requires-Dist: carlyemail>=0.4.0
Provides-Extra: dev
Requires-Dist: langchain-core<2,>=0.3; extra == 'dev'
Requires-Dist: livekit-agents>=1.0; extra == 'dev'
Requires-Dist: openai-agents>=0.1; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core<2,>=0.3; extra == 'langchain'
Provides-Extra: livekit
Requires-Dist: livekit-agents>=1.0; extra == 'livekit'
Provides-Extra: openai
Requires-Dist: openai-agents>=0.1; extra == 'openai'
Description-Content-Type: text/markdown

# carlyemail-toolkit

CarlyEmail's email tools for the OpenAI Agents SDK, LangChain, LiveKit Agents,
and any other agent framework. A real inbox your agent can send, receive and
reply from, without writing the tools yourself.

```bash
pip install "carlyemail-toolkit[openai]"     # or [langchain], [livekit]
export CARLYEMAIL_API_KEY=ce_us_...
```

```python
from agents import Agent
from carlyemail_toolkit.openai import CarlyEmailToolkit

agent = Agent(
    name="Inbox",
    instructions="Read the thread before replying. Draft when unsure.",
    tools=CarlyEmailToolkit().get_tools(),
)
```

```python
from langchain.agents import create_agent
from carlyemail_toolkit.langchain import CarlyEmailToolkit

agent = create_agent("openai:gpt-5-mini", CarlyEmailToolkit().get_tools())
```

```python
from livekit.agents import Agent
from carlyemail_toolkit.livekit import CarlyEmailToolkit

agent = Agent(instructions="...", tools=CarlyEmailToolkit().get_tools())
```

```python
from carlyemail_toolkit import CarlyEmailToolkit   # no framework

for tool in CarlyEmailToolkit().get_tools():
    tool.name, tool.description, tool.input_schema, tool.read_only
    tool(thread_id="...")                          # runs it
```

## What is in it

The 25 tools the hosted [MCP server](https://docs.carlyemail.com/mcp) serves —
inboxes, threads, messages, drafts, attachments, labels, and account
verification — with the same names, descriptions and parameter schemas, called
over the REST API. Pass names to take only some:

```python
tools = CarlyEmailToolkit().get_tools(["list_messages", "get_thread", "reply_to_message"])
```

A name that is not a tool raises rather than being dropped.

## Which inbox

Every tool takes `inbox_id`, and most work without it. A key scoped to one
inbox means that inbox. An organization with one inbox means that one. With
several, the tools that read threads and drafts look across all of them, and
every other tool refuses and names the inboxes so the agent can ask which —
the same behaviour as the hosted server.

## Errors

A failed call comes back to the model as one bounded line carrying the API's
message and the fix it suggests — an `Error: …` tool result on the OpenAI
Agents SDK, a handled `ToolException` on LangChain, a `ToolError` on LiveKit —
so the agent can act on it next turn instead of the run ending.

See <https://docs.carlyemail.com/integrations/toolkit>.
