API Reference

myagentinbox exposes a small REST API for creating disposable email inboxes, reading messages, and downloading attachments. Everything is JSON over HTTPS. No authentication, no API keys, no SDK required.

Overview

The API has four endpoints — create an inbox, get an inbox, list messages, get a message — plus one for downloading attachments. Inboxes and all their data auto-delete 24 hours after creation. There's also an MCP server at /mcp for AI agents.

Authentication

None. All endpoints are public. Rate limits are enforced per IP address.

Base URL

https://myagentinbox.com

Response format

Every JSON response is wrapped in either a data field (success) or an error field (failure). This shape is stable; clients can rely on it.

// Success
{ "data": { ... } }

// Error
{ "error": { "code": "not_found", "message": "Inbox not found or expired" } }

Attachment downloads are the exception — they return raw binary with appropriate Content-Type and Content-Disposition headers.

Errors

Errors use standard HTTP status codes plus a JSON body with a stable code string.

Rate limits

Limits are scoped per client IP, evaluated at the Cloudflare edge.

Rate-limited responses return 429 with a Retry-After: 60 header. If you're hitting limits in CI, lower your worker concurrency or raise the polling interval.

Create inbox

Creates a new disposable inbox with a randomly generated address. The inbox lives for 24 hours, then everything tied to it is deleted.

Request

No body, no headers required.

Example

curl -s -X POST https://myagentinbox.com/api/inboxes

const r = await fetch("https://myagentinbox.com/api/inboxes", {
  method: "POST",
});
const { data } = await r.json();
console.log(data.address);

import httpx

r = httpx.post("https://myagentinbox.com/api/inboxes")
r.raise_for_status()
print(r.json()["data"]["address"])

Response 201 Created

{
  "data": {
    "address": "a7k2m9x4bp@myagentinbox.com",
    "created_at": "2026-04-30T14:22:11.482Z",
    "expires_in": "24h"
  }
}

Get inbox

Returns metadata for an existing inbox. Useful for confirming an address is still alive.

Path parameters

Example

curl -s https://myagentinbox.com/api/inboxes/a7k2m9x4bp@myagentinbox.com

Response 200 OK

{
  "data": {
    "address": "a7k2m9x4bp@myagentinbox.com",
    "created_at": "2026-04-30T14:22:11.482Z"
  }
}

Returns 404 not_found if the inbox doesn't exist or has expired.

List messages

Lists all messages currently in an inbox, newest first. Each entry is a summary — use Get message for full content.

Example

curl -s https://myagentinbox.com/api/inboxes/a7k2m9x4bp@myagentinbox.com/messages

Response 200 OK

{
  "data": [
    {
      "id": "01HZX9...",
      "from": "noreply@example.com",
      "subject": "Verify your email",
      "preview": "Your verification code is 482913. This code expires in...",
      "received_at": "2026-04-30T14:22:48.103Z",
      "has_attachments": false
    }
  ]
}

Returns 404 if the inbox doesn't exist. Returns data: [] if the inbox exists but has no messages yet.

Get message

Returns the full content of a single message: text and HTML bodies, recipient list, attachment metadata.

Path parameters

Response 200 OK

{
  "data": {
    "id": "01HZX9...",
    "from": "noreply@example.com",
    "to": ["a7k2m9x4bp@myagentinbox.com"],
    "subject": "Verify your email",
    "text": "Your verification code is 482913.\n\nThis code expires in 10 minutes.",
    "html": "<p>Your verification code is <b>482913</b>.</p>...",
    "attachments": [
      {
        "filename": "receipt.pdf",
        "content_type": "application/pdf",
        "size": 14823,
        "r2_key": "a7k2m9x4bp@myagentinbox.com/01HZX9.../receipt.pdf"
      }
    ],
    "received_at": "2026-04-30T14:22:48.103Z"
  }
}

Download attachment

Returns the raw bytes of one attachment. The response sets Content-Type from the original email and Content-Disposition: attachment; filename="...".

Example

curl -s -o receipt.pdf \
  https://myagentinbox.com/api/inboxes/a7k2m9x4bp@myagentinbox.com/messages/01HZX9.../attachments/receipt.pdf

Returns 404 if the inbox, message, or attachment doesn't exist.

MCP server

For AI agents, the same operations are exposed as a Model Context Protocol server over Streamable HTTP.

Connect

{
  "mcpServers": {
    "myagentinbox": {
      "command": "npx",
      "args": ["mcp-remote", "https://myagentinbox.com/mcp"]
    }
  }
}

Framework-specific guides: Claude, Cursor, OpenAI Agents SDK, LangChain, Vercel AI SDK.

MCP tools

Object types

Inbox

MessageSummary

Message

Attachment

Expiry behavior

One subtle behavior worth knowing about:

• Inboxes get a 24 h TTL on creation.
• Incoming messages adopt the inbox's remaining TTL — not a fresh 24 h. So a message arriving 23 hours after the inbox was created will live 1 hour, not 24.
• Attachments are stored in object storage with a 1-day lifecycle and are deleted independently.
• Mail sent to an address that has already expired is rejected at the SMTP layer with a bounce. No data is stored.

The practical implication: if a test is going to wait on an email near the inbox's expiry, create a fresh inbox first.

Spotted something wrong or missing? Email hello@myagentinbox.com.