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.

Creation limits are enforced globally, so they apply no matter which Cloudflare location serves your request. The read limit is evaluated per edge location, which means a client spread across regions may see more headroom than the stated figure — do not depend on that.

Rate-limited responses return 429 with a Retry-After header indicating how long to wait:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit reached: 1 inbox per 5 minutes per IP. ...",
    "retry_after": 300,
    "higher_limits": "hello@myagentinbox.com"
  }
}

If you're hitting limits in CI, raise the polling interval and keep email-dependent tests to a nightly job. If you need volume, get in touch — higher limits and a dedicated domain are what we're building next.

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.