Documentation

01 · Start here

Create and use an inbox#

Create an API key in the dashboard, then list the inboxes available to that key.

export BOTINBOX_API_KEY=bi_your_key

curl https://botinbox.dev/v0/inboxes \
  -H "Authorization: Bearer $BOTINBOX_API_KEY"

Send from an inbox using its ID:

curl https://botinbox.dev/v0/inboxes/INBOX_ID/messages \
  -H "Authorization: Bearer $BOTINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"human@example.com","subject":"Hello","text":"Sent by my agent"}'

02 · Reference

REST API#

All /v0 endpoints use Authorization: Bearer bi_.... Lists return data and, where applicable, next_cursor.

• Inboxes

  GET|POST /v0/inboxes

• Messages

  GET|POST /v0/inboxes/:id/messages

• Threads

  GET /v0/inboxes/:id/threads

• Domains

  GET|POST /v0/domains

• Pods

  GET|POST /v0/pods

• API keys

  GET|POST /v0/api-keys

• Webhooks

  GET|POST /v0/webhooks

• Usage

  GET /v0/me

Use the OpenAPI document for generated clients and API tooling. Search messages with ?q=, filter with ?unread=true, and paginate with ?limit= and ?cursor=.

03 · Agent integration

Connect MCP clients#

BotInbox hosts a remote MCP server at https://botinbox.dev/mcp with tools for inboxes, sending, replying, searching, threads, drafts, labels, usage, and wait_for_email for verification codes. Create an API key in the dashboard, then register it in Claude Code:

claude mcp add --transport http botinbox https://botinbox.dev/mcp \
  --header "Authorization: Bearer bi_your_key"

Or add this to .cursor/mcp.json (Cursor) or your client's MCP configuration:

{
  "mcpServers": {
    "botinbox": {
      "url": "https://botinbox.dev/mcp",
      "headers": {
        "Authorization": "Bearer bi_your_key"
      }
    }
  }
}

Clients that only launch local commands, such as Claude Desktop, can connect through mcp-remote. Setup for every client →

04 · Terminal

Install the CLI#

The botinbox CLI manages inboxes, sends and reads mail, streams events, and waits for verification codes in CI. Install it with Homebrew on macOS or the one-line installer on macOS and Linux:

brew install botinbox-dev/tap/botinbox

# or
curl -fsSL https://botinbox.dev/install.sh | sh

On Windows, run irm https://botinbox.dev/install.ps1 | iex in PowerShell. Direct downloads and checksums are on the CLI download page. CLI reference →

05 · Events

Receive signed webhooks#

Add an HTTPS endpoint in the dashboard or with POST /v0/webhooks. New inbound mail produces a message.received payload. BotInbox retries failed deliveries up to three times.

const expected = createHmac("sha256", webhookSecret)
  .update(rawRequestBody)
  .digest("hex");

const valid = timingSafeEqual(
  Buffer.from(`sha256=${expected}`),
  Buffer.from(request.headers["x-botinbox-signature"])
);

06 · Live updates

Live events (SSE)#

For long-running agents, consume the authenticated Server-Sent Events stream. It emits message.received and message.sent for every inbox the key can see.

curl -N https://botinbox.dev/v0/events \
  -H "Authorization: Bearer $BOTINBOX_API_KEY"

07 · Identity

Use a custom domain#

On Builder and Team, add a domain in the dashboard, publish the verification and mail records it shows, then verify it. Create inboxes on the verified domain. New domains are send-only by default (no MX record); to receive, add a subdomain such as in.example.com so an existing MX setup stays untouched. DNS records explained →

08 · AI onboarding

Documentation for agents#

Give an AI coding assistant /llms.txt for a compact capability and endpoint index, or give it the OpenAPI JSON for structured API discovery. For tool use, the MCP configuration above is the preferred path.