Give an OpenAI Agents SDK agent an email inbox
The OpenAI Agents SDK reaches Trotta Mail through its MCP server. Point MCPServerStreamableHttp at https://api.trotta.email/mcp with an API key, and the agent gets tools to wait for mail, read it, send and reply. Every message is screened before delivery, so the model reads a safe view and held mail stays out of its reach.
Updated
Install and connect
Install the OpenAI Agents SDK, then point it at the Trotta Mail MCP server. The SDK has MCP support built in and the server is remote, so the SDK is the only thing to install.
pip install openai-agentsThe agent connects with MCPServerStreamableHttp from agents.mcp. It takes the server URL and your Trotta Mail key as a bearer header. The SDK reads your OpenAI key from OPENAI_API_KEY as usual. The code below follows the Agents SDK docs, checked on 2026-11-20.
https://api.trotta.email/ mcpA complete example: inbox, wait, read, reply
This example gets an inbox, waits for a message, reads it and replies. Every Trotta Mail integration page runs the same four steps, so you can compare them. Step 1 is one HTTP call. The model takes steps 2 to 4 with tools.
1. Get an inbox
One call creates an inbox and an API key. It needs no account and no key.
curl -X POST https://api.trotta.email/ v1/ agents/ signup \
-H "Content-Type: application/ json" \
-d '{"name": "riley"}'The response carries api_key, inbox.address and a claim_url for the human responsible for the agent. Keep the key: it is shown once. Put it in TROTTA_MAIL_API_KEY.
2 to 4. Wait, read and reply
The model uses three tools: wait_for_message, read_message and reply_to_message.
import asyncio
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp
async def main():
async with MCPServerStreamableHttp(
name="trotta",
params={
"url": "https://api.trotta.email/ mcp",
"headers": {"Authorization": f"Bearer {os.environ['TROTTA_MAIL_API_KEY']}"},
},
client_session_timeout_seconds=90, # wait_for_message can hold a call open for 60 seconds
) as server:
agent = Agent(name="Assistant", mcp_servers=[server])
result = await Runner.run(
agent,
"Wait for the next message in my inbox, read it, and reply in one line.",
)
print(result.final_output)
asyncio.run(main())Run it, then send a mail to the inbox address. wait_for_message holds the call open for up to 60 seconds. The SDK's MCP session gives up after 5 seconds unless you raise client_session_timeout_seconds, which is why the example sets it.
Before a human claims the agent, it can receive from anyone and reply to anyone whose mail to it arrived authenticated. To write to new addresses, a human opens the claim_url.
What your agent reads
Your agent reads screened mail, never the raw message. Three things come back from the tools.
- The verdict. Every message carries one, decided before the message is readable. Its action is
deliver,flag,holdorreject. Malicious mail, known or new, is refused at the door and never reaches the inbox. - The safe view.
read_messagereturns only what a human could see. Hidden text is removed. Instructions aimed at a model are replaced by a note that names what was removed. Links that are not clean are defanged. - Held mail. Dangerous mail is held outside the inbox for a human. The agent sees
withheld: trueand the reason in fixed words, and nothing the sender wrote.wait_for_messagenever returns it.
Screening before delivery matters because Runner.run feeds each tool result straight back to the model. An email is text written by a stranger, and a model may act on an instruction it finds there. With screening at the door, that text is removed or held before the model sees the message.
No filter catches everything. Keep treating mail content as data, never as instructions. The verdict and the safe view are described in Concepts.
Going further
- MCP: every tool the server offers, including drafts, scheduled mail and attachment text.
- Webhooks: Trotta Mail posts a signed event to your endpoint when mail arrives.
- Live events: the same events over a stream, with no public endpoint.
- Pods: one isolated workspace per customer.
- Domains: agent inboxes on your own domain, on paid plans.
Questions
How do I give an OpenAI Agents SDK agent an email tool?
Connect the Trotta Mail MCP server with MCPServerStreamableHttp and pass it in mcp_servers. The agent then has tools to wait for mail, read it in the safe view, send and reply.
Why does wait_for_message time out in the OpenAI Agents SDK?
The SDK's MCP session waits 5 seconds by default, and wait_for_message can hold a call open for up to 60. Set client_session_timeout_seconds on MCPServerStreamableHttp above the longest wait you ask for.
Can the agent read or release held mail?
No. A held message comes back withheld, with the reason in fixed words and nothing its sender wrote. Only a human releases it, and the agent then receives it as an ordinary message.
Does the agent need a Trotta Mail account first?
No. POST /v1/agents/signup returns an inbox and an API key in one call. A human can claim the agent later with the claim_url in the response.
Is Trotta Mail made by OpenAI?
No. Trotta Mail is an independent product that works with the OpenAI Agents SDK as a remote MCP server. It is not made or endorsed by OpenAI.