Introduction

Email infrastructure for AI agents — provision an inbox in one API call, then receive and read mail over a simple REST API.

InboxAgents gives your AI agents their own email inboxes. Create a live, addressable inbox in a single API call, then receive and read the mail that lands in it — over a small, predictable REST API authenticated by one API key.

The v1 API is receive-focused: provision inboxes, then read the threads, messages, and attachments that arrive. Sending is not part of v1.

Start here

Quickstart

Provision an inbox, send it a test email, and read the message — end to end, in REST, TypeScript, Python, and the CLI.

Connect an AI assistant

Give Claude, ChatGPT, or a coding agent its own inboxes over MCP — point-and-click or one-line install.

Authentication

API keys, permissions and scopes, and the whoami identity check.

API reference

Every endpoint, generated from the OpenAPI contract so it never drifts from the live API.

How it works

Inboxes are the core primitive — a live email identity you create, list, read, update, and delete. New inboxes get an address on the shared agents.theinboxagents.com domain.
Threads, messages, and attachments are read as subresources of the inbox that owns them (/v1/inboxes/{inbox_id}/threads/…).
Every request authenticates with a single API key. There is no OAuth dance for the REST API.
Real-time delivery happens two ways: register a webhook to be notified when mail arrives, or hold a WebSocket for a live stream.

Conventions at a glance

Base URL — https://app.theinboxagents.com/api/v1. The API is versioned at /v1.
Auth — send your key as Authorization: Bearer <key> (or the x-api-key header). See Authentication.
JSON everywhere — request and response bodies are JSON; timestamps are ISO-8601 UTC.
Opaque, typed ids — ids carry a short prefix so their type is obvious: inb_ (inbox), thr_ (thread), msg_ (message), att_ (attachment), key_ (API key), ia_ (the API key secret itself).
Consistent errors — every error is a { name, message } envelope with a stable name. See Errors.
Cursor pagination — list endpoints page with page_token. See Pagination.
Rate limits — per-key limits return 429 with Retry-After. See Rate limits.

For coding agents

The docs are published in agent-readable form: an /llms.txt index, a full /llms-full.txt concatenation, and clean Markdown per page. Point your agent at those to ingest the docs cheaply.