agentinboxRequest access

Documentation

Give an AI agent a real email inbox with one API call. Run it yourself in one command, or use the managed cloud.

Introduction

agentinbox gives AI agents their own real email inboxes over a simple HTTP API — create an address, send and receive mail, hold threaded conversations, react to inbound mail via webhooks, and extract verification codes. No OAuth, no per-seat mailbox pricing.

There are two ways to use it:

  • Self-host — open source, run the whole stack yourself with one command (below).
  • Managed cloud — we run it with pre-warmed deliverability and zero ops. Request access.

Quickstart

Self-host locally (requires Docker). This brings up the API, a dashboard, and the mail plumbing:

terminal
git clone https://github.com/Unify-DB/AgentInbox.git agentinbox && cd agentinbox./start.sh        # builds, starts, and prints your API key

Then create your first inbox (use the API key printed by start.sh):

terminal
curl -X POST http://localhost:/v1/inboxes \  -H "Authorization: Bearer $AGENTINBOX_API_KEY" \  -H "Content-Type: application/json" \  -d '{"username":"ava"}'# -> { "id": "inb_...", "address": "ava@localhost", ... }

On the managed cloud the base URL is https://api.agentinbox.site and inboxes are created on a warmed, deliverable domain.

Authentication

Every /v1 request is authenticated with an API key in the Authorization header. Keys are created by the bootstrap command (self-host) or the dashboard.

header
Authorization: Bearer aink_your_key_here

Inboxes

An inbox is a real email address your agent fully controls.

bash
# CreatePOST   /v1/inboxes            { "username"?, "display_name"?, "agent_id"? }# List / get / deleteGET    /v1/inboxesGET    /v1/inboxes/{id}DELETE /v1/inboxes/{id}

Sending email

Send from an inbox; a thread is created (or continued).

bash
curl -X POST http://localhost:/v1/inboxes/{id}/messages \  -H "Authorization: Bearer $AGENTINBOX_API_KEY" \  -H "Content-Type: application/json" \  -d '{"to":"lead@company.com","subject":"Hi","text":"Hello from my agent!"}'

Receiving & webhooks

When mail arrives, agentinbox parses it, groups it into a thread, and fires a message.received webhook. Register an endpoint:

bash
POST /v1/webhooks   { "url": "https://your-app.com/hook" }# -> { "id", "url", "events", "secret" }   (secret shown once)

Each delivery is a JSON POST signed with X-Agentinbox-Signature: sha256=<hmac> (HMAC-SHA256 of the raw body using your endpoint secret) plus an X-Agentinbox-Event header. Verify the signature before trusting the payload. You can also poll GET /v1/inboxes/{id}/messages?direction=inbound.

Threads

Related messages are grouped into threads by their Message-ID/In-Reply-To headers (with a subject fallback), so a conversation stays together.

bash
GET /v1/inboxes/{id}/threads     # threads for an inboxGET /v1/threads/{id}             # a thread with its ordered messagesPOST /v1/messages/{id}/reply     { "text": "..." }   # reply in-thread

Verification codes

Agents constantly need OTP/2FA codes out of email. This endpoint extracts the latest one deterministically (no LLM required):

bash
GET /v1/inboxes/{id}/verification-code?within_seconds=# -> { "code": "492013", "message_id": "msg_...", "extracted_at": "..." }#    404 if no code is found in the window

Python SDK

python
from agentinbox import Client client = Client(api_key="aink_...", base_url="http://localhost:")inbox = client.inboxes.create(username="ava")client.messages.send(inbox["id"], to="lead@co.com", subject="hi", text="hello!") for msg in client.messages.list(inbox["id"], direction="inbound"):    client.messages.reply(msg["id"], text="thanks for reaching out!") code = client.verification_code(inbox["id"])   # latest OTP, or None

MCP server

agentinbox ships a Model Context Protocol server so agents in Claude Desktop, Cursor, and other MCP clients get email tools (create_inbox, send_email, list_messages, get_verification_code).

claude_desktop_config.json
{  "mcpServers": {    "agentinbox": {      "command": "python",      "args": ["-m", "server"],      "env": {        "AGENTINBOX_API_KEY": "aink_...",        "AGENTINBOX_BASE_URL": "http://localhost:8000"      }    }  }}

Deploy to production

To send and receive real email you need Amazon SES (or an SMTP relay) and a public host. The full walkthrough — SES setup, DNS, hosting behind HTTPS, and wiring inbound — lives in DEPLOY.md in the repo.

  1. Verify your domain in SES and publish the DNS records.
  2. Set OUTBOUND_PROVIDER=ses, INBOUND_ADAPTER=ses, and your AWS credentials in .env.
  3. Deploy the app behind HTTPS and point your MX at SES inbound.

Prefer not to run any of it? Request access to the managed cloud — we handle deliverability, scaling, and ops for you.