The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Agentboxd listing page.
Real email inboxes for AI agents. Create an address with one API call, send and reply from it, block until the next email arrives, and pull the one-time code or magic link out of a sign-up email.
This repository holds the open-source clients for the hosted Agentboxd API:
| Package | Install | Source |
|---|---|---|
| TypeScript / Node client | npm install agentboxd | sdk/ |
| Command line | npx agentboxd --help | sdk/src/cli/ |
| MCP server (Claude Desktop, Claude Code, Cursor, ...) | npx -y @agentboxd/mcp | mcp/ |
| Python client (sync + async) | Coming soon to PyPI; install from sdk-python/ meanwhile | sdk-python/ |
| Example agents and guide code | examples/ | |
| Agent skill (Claude Code, Cursor, Codex, OpenClaw, ...) | npx skills add agentboxd/skills | agentboxd/skills |
homingbox.net or your own domain, with SPF, DKIM and DMARC handled.extracted_text holds only the new text of a reply, without quoted history or
signatures; attachments, threads and authentication results are all there.messages.wait() long-polls until the next matching email arrives.message.received and friends, plus a verifier in each SDK.Get an API key from the dashboard (Free plan, no card), then:
TypeScript
Python
MCP (Claude Code)
The hosted connector needs no API key: you sign in and choose what the client may do.
Or run the server locally with a key:
Then ask: "Create an inbox, sign up for the newsletter at example.com with it, and tell me the
confirmation link." Config snippets for Claude Desktop, Cursor and other clients are in
mcp/README.md.
examples/echo-agent.ts: registers a webhook and replies to every email
with a short summary. Needs a public URL for the webhook (e.g. a tunnel):
AGENTBOXD_API_KEY=mr_... AGENTBOXD_BASE_URL=https://api.agentboxd.com ECHO_WEBHOOK_URL=https://<your-tunnel>/webhook npm run echo-agentexamples/deepseek-agent/: a tool-calling agent that signs up for things
and triages an inbox, with the email-is-untrusted guardrails wired in.The Agentboxd API server itself is not part of this repository.
Issues and pull requests are welcome: see CONTRIBUTING.md. Please report security problems privately as described in SECURITY.md, not in public issues.