AgentBox

Open-source email inbox infrastructure for AI agents.

AgentBox gives software agents their own programmable inboxes. Create inboxes over an API, send and receive threaded email, stream realtime events, search messages, and let agents operate email through MCP—on infrastructure you control.

Early-stage software. The API is usable today; production email deliverability still depends on a correctly configured SMTP provider, inbound route, DNS, and abuse controls.

Why AgentBox?

• Self-hostable: MIT licensed, one Docker command, portable SQLite data.
• Agent-native: inboxes, threads, search, SSE events, and an MCP server are first-class.
• Provider-agnostic: use any SMTP provider; connect any inbound email service that can POST a webhook.
• Secure defaults: bearer authentication and HMAC-signed inbound webhooks.
• Honest local mode: without SMTP, sends are recorded as simulated so development never silently contacts real recipients.

Quick start

git clone https://github.com/sagnik11/agentbox.git
cd agentbox
cp .env.example .env
npm install
AGENTBOX_API_KEY=local-secret npm run dev

Create an inbox:

curl -X POST http://localhost:3000/v1/inboxes \
  -H 'Authorization: Bearer local-secret' \
  -H 'Content-Type: application/json' \
  -d '{"username":"researcher","domain":"agents.example.com"}'

Open http://localhost:3000/docs for interactive API documentation. Or run with Docker:

AGENTBOX_API_KEY=local-secret docker compose up --build

API

Method	Endpoint	Purpose
POST	/v1/inboxes	Provision an inbox
GET	/v1/inboxes	List inboxes
DELETE	/v1/inboxes/:id	Delete an inbox
POST	/v1/inboxes/:id/messages	Send a message
GET	/v1/inboxes/:id/messages	Read an inbox
GET	/v1/threads/:id	Read a thread
GET	/v1/search?q=...	Search messages
GET	/v1/events	Stream SSE events
POST	/v1/inbound	Ingest signed inbound mail

Receiving email

Configure your mail provider to transform inbound messages into this JSON shape and POST it to /v1/inbound:

{"to":"researcher@agents.example.com","from":"alice@example.com","subject":"Hello","text":"Hi agent"}

Set X-AgentBox-Signature to the hex HMAC-SHA256 of the exact JSON body using INBOUND_WEBHOOK_SECRET. Provider-specific adapters are welcome contributions.

MCP

Start the API, then configure an MCP client to run:

{
  "mcpServers": {
    "agentbox": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentbox/src/mcp.ts"],
      "env": {"AGENTBOX_URL":"http://localhost:3000","AGENTBOX_API_KEY":"local-secret"}
    }
  }
}

Tools: create_inbox, list_inboxes, list_messages, send_email, and search_email.

Production checklist

• Put AgentBox behind TLS and replace both development secrets.
• Configure authenticated SMTP plus SPF, DKIM, and DMARC for your sending domain.
• Route inbound MX email through a provider adapter to the signed webhook.
• Add tenant isolation, per-key rate limits, retention rules, and an abuse-reporting workflow before offering a public service.
• Back up the SQLite volume, or contribute a PostgreSQL store for multi-instance deployments.

Roadmap

• Inbound adapters for AWS SES, Mailgun, Postmark, and Cloudflare Email Workers
• Attachments and object-storage backends
• Webhook subscriptions with retries and signatures
• PostgreSQL, multi-tenancy, API key management, and quotas
• Python and TypeScript SDK packages
• Semantic search and structured extraction hooks

Contributing

Issues and pull requests are welcome. Please add tests for behavior changes and run npm test && npm run typecheck before opening a PR. See SECURITY.md for private vulnerability reporting.

License

MIT © Sagnik Ghosh. AgentBox is an independent project and is not affiliated with AgentMail.