Disposable Email for the OpenAI Agents SDK

The OpenAI Agents SDK doesn't speak MCP, but it has first-class support for function tools. This guide wraps the myagentinbox REST API as a small toolbelt so a GPT-4 / o-series agent can create inboxes and read email mid-task.

Install

pip install openai-agents httpx

Define the tools

Three function tools cover almost every workflow — create, check, read.

import httpx
from agents import Agent, Runner, function_tool

BASE = "https://myagentinbox.com"

@function_tool
def create_inbox() -> dict:
    """Create a disposable email inbox that expires in 24 hours."""
    r = httpx.post(f"{BASE}/api/inboxes", timeout=10)
    r.raise_for_status()
    return r.json()["data"]

@function_tool
def check_inbox(address: str) -> list:
    """List messages in a disposable inbox. Returns sender, subject, preview."""
    r = httpx.get(f"{BASE}/api/inboxes/{address}/messages", timeout=10)
    r.raise_for_status()
    return r.json()["data"]

@function_tool
def read_message(address: str, message_id: str) -> dict:
    """Return the full body of one message."""
    r = httpx.get(f"{BASE}/api/inboxes/{address}/messages/{message_id}", timeout=10)
    r.raise_for_status()
    return r.json()["data"]

Wire it into an agent

agent = Agent(
    name="Signup helper",
    instructions=(
        "You can create a disposable email inbox and read incoming mail. "
        "When a task needs an email address, call create_inbox first and "
        "use the returned address. Wait 5-10 seconds between check_inbox calls."
    ),
    tools=[create_inbox, check_inbox, read_message],
)

result = Runner.run_sync(
    agent,
    "Sign up for example.com using a throwaway email and report the verification code.",
)
print(result.final_output)

TypeScript

The JS SDK uses the same shape with tool():

import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const BASE = "https://myagentinbox.com";

const createInbox = tool({
  name: "create_inbox",
  description: "Create a disposable email inbox (24h TTL).",
  parameters: z.object({}),
  execute: async () => {
    const r = await fetch(`${BASE}/api/inboxes`, { method: "POST" });
    return (await r.json()).data;
  },
});

const checkInbox = tool({
  name: "check_inbox",
  description: "List messages in a disposable inbox.",
  parameters: z.object({ address: z.string() }),
  execute: async ({ address }) => {
    const r = await fetch(`${BASE}/api/inboxes/${address}/messages`);
    return (await r.json()).data;
  },
});

const agent = new Agent({
  name: "Signup helper",
  instructions: "Use create_inbox for any task needing an email.",
  tools: [createInbox, checkInbox],
});

const result = await run(agent, "Sign up for example.com.");
console.log(result.finalOutput);

Limits to bake into your prompt

• Create: 3 per minute per IP
• Reads: 20 per minute per IP
• Inbox lifetime: 24 hours
• Max email size: 10 MB