Send & Receive Emails with OpenAI Agents SDK

With the agentmail-toolkit package, an agent built on the OpenAI Agents SDK gets a working email address. On this page you will watch it create its own @agentmail.to inbox, send a message to you, and reply to one you send back.

0. Get API keys

• AGENTMAIL_API_KEY authenticates the email tools. Generate one from the AgentMail Console.
• OPENAI_API_KEY authenticates the model calls the Agents SDK makes. Generate one from the OpenAI dashboard.

export AGENTMAIL_API_KEY="<API_KEY>"
export OPENAI_API_KEY="<OPENAI_API_KEY>"

1. Install and load the tools

Install the toolkit and the Agents SDK. The toolkit needs Python 3.11 or newer.

pip install agentmail-toolkit openai-agents

Define your agent in agent.py. The toolkit’s get_tools() returns the email tools as the SDK’s own FunctionTool type, so the list goes straight into Agent(tools=...):

from agents import Agent
from agentmail_toolkit.openai import AgentMailToolkit

agent = Agent(
    name="Email Agent",
    instructions=(
        "You are an email agent with your own AgentMail inbox. "
        "You can create inboxes, send email, and read and reply to threads."
    ),
    tools=AgentMailToolkit().get_tools(),
)

AgentMailToolkit() picks up AGENTMAIL_API_KEY from the environment. To pass credentials some other way, give it a configured client: AgentMailToolkit(client=AgentMail(api_key="...")).

You can also connect through MCP instead of the toolkit, using the hosted server described in MCP and Skills.

2. Test sending emails

For the first run, the agent creates an inbox and emails you at an address you already own, in Gmail, Outlook, or wherever you read mail. Save this next to agent.py and run it with python send.py.

Check that account a moment later. The email arrives from a newly created @agentmail.to address.

from agents import Runner
from agent import agent

result = Runner.run_sync(
    agent,
    "Create an inbox with the display name 'Support agent', then send an email "
    "from it to you@example.com with the subject 'Hello from my agent' and a "
    "one-line introduction. When finished, tell me the address of the new inbox.",
)
print(result.final_output)

The agent calls the create_inbox tool, then send_message, and reports back:

Email sent successfully.

Sent from: faircost773@agentmail.to

Save the inbox address from the reply. You will email it in the next step.

The prompt above names no username, so AgentMail generates an available one.

3. Test receiving and replying

From your everyday account, send an email to the inbox address from step 2. Give it a subject and a question the agent can answer.

Then ask the agent to read and answer it. You should get the reply in your account, threaded under the message you sent.

from agents import Runner
from agent import agent

result = Runner.run_sync(
    agent,
    "Look at <inbox_id>, open the most recent thread, and answer it with a "
    "brief reply in the same thread.",
)
print(result.final_output)

Replace <inbox_id> with the address from step 2. The agent has no memory between runs, which is why the prompt spells out which inbox to check.

The agent finds the conversation with list_threads, reads it with get_thread, and answers with reply_to_message. Mail moves in about two seconds each way.

Scope the agent’s tools

get_tools() returns the full toolkit. For an agent that should only answer incoming mail, pass names to expose exactly what the job needs:

tools = AgentMailToolkit().get_tools(
    names=["list_threads", "get_thread", "reply_to_message"]
)

Scoped this way, the agent can read and reply to mail in inboxes that already exist, and that is all.

Next Steps